Spaces

A space in GitBook is the entity of a project you work in.

Last updated 8 days ago

Was this helpful?

Get the details about a space.

get

/spaces/{spaceId}

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

Query parameters

shareKeystring

For sites published via share-links, the share key is useful to resolve published URLs.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "title": "text",
  "visibility": "public",
  "createdAt": "2025-02-15T16:46:58.930Z",
  "updatedAt": "2025-02-15T16:46:58.930Z",
  "deletedAt": "2025-02-15T16:46:58.930Z",
  "editMode": "live",
  "gitSync": {
    "installationProvider": "github",
    "integration": "text",
    "url": "text",
    "updatedAt": "2025-02-15T16:46:58.930Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "defaultLevel": "admin",
  "id": "text",
  "emoji": "🎉",
  "organization": "text",
  "parent": "text",
  "revision": "text",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "object": "space",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com",
    "public": "https://example.com",
    "icon": "https://example.com"
  },
  "permissions": {
    "access": true,
    "admin": true,
    "edit": true,
    "comment": true,
    "merge": true,
    "review": true
  }
}

List permissions for all users in a space.

get

/spaces/{spaceId}/permissions/aggregate

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber

The number of results per page

roleenum

"The role of a member in an organization. "admin": Can administrate the content: create, delete spaces, ... "create": Can create content. "review": Can review content. "edit": Can edit the content (live or change requests). "comment": Can access the content and its discussions. "read": Can access the content, but cannot update it in any way.

Options: admin, create, edit, review, comment, read

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/permissions/aggregate' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "permission": "admin",
      "user": {
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "object": "user",
        "urls": {
          "location": "https://example.com"
        }
      }
    }
  ]
}

Listing of users who can access the space.

Create an organization space

post

/orgs/{organizationId}/spaces

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Body

titlestring

emojistring emoji

Unicode codepoint or character of the emoji

Example: 🎉

parentstring

ID of a parent collection

privatebooleanDeprecated

Private spaces are no longer supported by GitBook.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/spaces' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"emoji":"🎉"}'

201

default

{
  "title": "text",
  "visibility": "public",
  "createdAt": "2025-02-15T16:46:58.930Z",
  "updatedAt": "2025-02-15T16:46:58.930Z",
  "deletedAt": "2025-02-15T16:46:58.930Z",
  "editMode": "live",
  "gitSync": {
    "installationProvider": "github",
    "integration": "text",
    "url": "text",
    "updatedAt": "2025-02-15T16:46:58.930Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "defaultLevel": "admin",
  "id": "text",
  "emoji": "🎉",
  "organization": "text",
  "parent": "text",
  "revision": "text",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "object": "space",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com",
    "public": "https://example.com",
    "icon": "https://example.com"
  },
  "permissions": {
    "access": true,
    "admin": true,
    "edit": true,
    "comment": true,
    "merge": true,
    "review": true
  }
}

Space created

Create a duplicate of the space.

post

/spaces/{spaceId}/duplicate

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/duplicate' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

201

default

{
  "title": "text",
  "visibility": "public",
  "createdAt": "2025-02-15T16:46:58.930Z",
  "updatedAt": "2025-02-15T16:46:58.930Z",
  "deletedAt": "2025-02-15T16:46:58.930Z",
  "editMode": "live",
  "gitSync": {
    "installationProvider": "github",
    "integration": "text",
    "url": "text",
    "updatedAt": "2025-02-15T16:46:58.930Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "defaultLevel": "admin",
  "id": "text",
  "emoji": "🎉",
  "organization": "text",
  "parent": "text",
  "revision": "text",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "object": "space",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com",
    "public": "https://example.com",
    "icon": "https://example.com"
  },
  "permissions": {
    "access": true,
    "admin": true,
    "edit": true,
    "comment": true,
    "merge": true,
    "review": true
  }
}

Space duplicated

Update the details of a space

patch

/spaces/{spaceId}

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

Body

editModeenum

Determines how a Space can be edited.

live: Users can directly edit the space
locked: All edits are locked for this space.

Options: live, locked

titlestring

Title of the space

defaultLevelone of

Default level for a piece of content

one of

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"editMode":"live","defaultLevel":"admin","emoji":"🎉"}'

200

default

{
  "title": "text",
  "visibility": "public",
  "createdAt": "2025-02-15T16:46:58.930Z",
  "updatedAt": "2025-02-15T16:46:58.930Z",
  "deletedAt": "2025-02-15T16:46:58.930Z",
  "editMode": "live",
  "gitSync": {
    "installationProvider": "github",
    "integration": "text",
    "url": "text",
    "updatedAt": "2025-02-15T16:46:58.930Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "defaultLevel": "admin",
  "id": "text",
  "emoji": "🎉",
  "organization": "text",
  "parent": "text",
  "revision": "text",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "object": "space",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com",
    "public": "https://example.com",
    "icon": "https://example.com"
  },
  "permissions": {
    "access": true,
    "admin": true,
    "edit": true,
    "comment": true,
    "merge": true,
    "review": true
  }
}

The space has been updated