Spaces

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

GET a specific space

Get the details about a space.

GEThttps://api.gitbook.com/v1/spaces/{spaceId}

Authorization

user

Path parameters

spaceId*string

The unique id of the space

Query parameters

Response

200default

OK

Body

application/json

object*enum

Type of Object, always equals to "space"

space

id*string

Unique identifier for the space

title*SpaceTitle (string)

Title of the space

emoji*Emoji (string (emoji))

Unicode codepoint or character of the emoji

Example: "🎉"

visibility*ContentVisibility (enum)

• public: Anyone can access the content, and the content is indexed by search engines.
• unlisted: Anyone can access the content, and the content is not indexed by search engines
• share-link: Anyone with a secret token in the url can access the content.
• visitor-auth: Anyone authenticated through a JWT token can access the content.
• in-collection: Anyone who can access the parent collection can access the content. Only available for spaces in a collection.
• private: Authorized members can access the content.

publicunlistedshare-linkvisitor-authin-collectionprivate

createdAt*Timestamp (string (date-time))

updatedAt*Timestamp (string (date-time))

deletedAtTimestamp (string (date-time))

editModeSpaceEditMode (enum)

Determines how a Space can be edited.

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

livelocked

urls*object

URLs associated with the object

organization*string

ID of the organization owning this space

parentstring

ID of the parent collection.

gitSyncGitSyncState (object)

visitorAuthVisitorAuth (one of)

Custom backend for Visitor Authenticationall of

revision*string

ID of the active revision in the space.

defaultLevel*DefaultLevel (one of)

Default level for a piece of content

MemberRole (enum)nullable enumenum

comments*number

Count of opened comments on the space.

changeRequests*number

Total count of change requests on the space.

changeRequestsOpen*number

Count of open change requests on the space.

changeRequestsDraft*number

Count of draft change requests on the space.

permissions*object

The set of permissions for the space

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200default

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

GET permissions for all users in a space

List permissions for all users in a space.

GEThttps://api.gitbook.com/v1/spaces/{spaceId}/permissions/aggregate

Authorization

user

Path parameters

spaceId*string

The unique id of the space

Query parameters

Response

200default

Listing of users who can access the space.

Body

application/json

nextobject

countnumber

Total count of objects in the list

items*array of UserContentPermission (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/permissions/aggregate', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200default

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

POST a new space in an organization

Create an organization space

POSThttps://api.gitbook.com/v1/orgs/{organizationId}/spaces

Authorization

user

Path parameters

organizationId*string

The unique id of the organization

Body

application/json

titlestring

emojiEmoji (string (emoji))

Unicode codepoint or character of the emoji

Example: "🎉"

parentstring

ID of a parent collection

Response

201default

Space created

Headers

Body

application/json

object*enum

Type of Object, always equals to "space"

space

id*string

Unique identifier for the space

title*SpaceTitle (string)

Title of the space

emoji*Emoji (string (emoji))

Unicode codepoint or character of the emoji

Example: "🎉"

visibility*ContentVisibility (enum)

• public: Anyone can access the content, and the content is indexed by search engines.
• unlisted: Anyone can access the content, and the content is not indexed by search engines
• share-link: Anyone with a secret token in the url can access the content.
• visitor-auth: Anyone authenticated through a JWT token can access the content.
• in-collection: Anyone who can access the parent collection can access the content. Only available for spaces in a collection.
• private: Authorized members can access the content.

publicunlistedshare-linkvisitor-authin-collectionprivate

createdAt*Timestamp (string (date-time))

updatedAt*Timestamp (string (date-time))

deletedAtTimestamp (string (date-time))

editModeSpaceEditMode (enum)

Determines how a Space can be edited.

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

livelocked

urls*object

URLs associated with the object

organization*string

ID of the organization owning this space

parentstring

ID of the parent collection.

gitSyncGitSyncState (object)

visitorAuthVisitorAuth (one of)

Custom backend for Visitor Authenticationall of

revision*string

ID of the active revision in the space.

defaultLevel*DefaultLevel (one of)

Default level for a piece of content

MemberRole (enum)nullable enumenum

comments*number

Count of opened comments on the space.

changeRequests*number

Total count of change requests on the space.

changeRequestsOpen*number

Count of open change requests on the space.

changeRequestsDraft*number

Count of draft change requests on the space.

permissions*object

The set of permissions for the space

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/orgs/{organizationId}/spaces', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

201default

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

POST a duplicate of a space

Create a duplicate of the space.

POSThttps://api.gitbook.com/v1/spaces/{spaceId}/duplicate

Authorization

user

Path parameters

spaceId*string

The unique id of the space

Response

201default

Space duplicated

Headers

Body

application/json

object*enum

Type of Object, always equals to "space"

space

id*string

Unique identifier for the space

title*SpaceTitle (string)

Title of the space

emoji*Emoji (string (emoji))

Unicode codepoint or character of the emoji

Example: "🎉"

visibility*ContentVisibility (enum)

• public: Anyone can access the content, and the content is indexed by search engines.
• unlisted: Anyone can access the content, and the content is not indexed by search engines
• share-link: Anyone with a secret token in the url can access the content.
• visitor-auth: Anyone authenticated through a JWT token can access the content.
• in-collection: Anyone who can access the parent collection can access the content. Only available for spaces in a collection.
• private: Authorized members can access the content.

publicunlistedshare-linkvisitor-authin-collectionprivate

createdAt*Timestamp (string (date-time))

updatedAt*Timestamp (string (date-time))

deletedAtTimestamp (string (date-time))

editModeSpaceEditMode (enum)

Determines how a Space can be edited.

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

livelocked

urls*object

URLs associated with the object

organization*string

ID of the organization owning this space

parentstring

ID of the parent collection.

gitSyncGitSyncState (object)

visitorAuthVisitorAuth (one of)

Custom backend for Visitor Authenticationall of

revision*string

ID of the active revision in the space.

defaultLevel*DefaultLevel (one of)

Default level for a piece of content

MemberRole (enum)nullable enumenum

comments*number

Count of opened comments on the space.

changeRequests*number

Total count of change requests on the space.

changeRequestsOpen*number

Count of open change requests on the space.

changeRequestsDraft*number

Count of draft change requests on the space.

permissions*object

The set of permissions for the space

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/duplicate', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

201default

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

UPDATE a specific space

Update the details of a space

PATCHhttps://api.gitbook.com/v1/spaces/{spaceId}

Authorization

user

Path parameters

spaceId*string

The unique id of the space

Body

application/json

editModeSpaceEditMode (enum)

Determines how a Space can be edited.

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

livelocked

titleSpaceTitle (string)

Title of the space

defaultLevelDefaultLevel (one of)

Default level for a piece of content

MemberRole (enum)nullable enumenum

one of

EmojiIconRemove icon or emoji

Response

200default

The space has been updated

Body

application/json

object*enum

Type of Object, always equals to "space"

space

id*string

Unique identifier for the space

title*SpaceTitle (string)

Title of the space

emoji*Emoji (string (emoji))

Unicode codepoint or character of the emoji

Example: "🎉"

visibility*ContentVisibility (enum)

• public: Anyone can access the content, and the content is indexed by search engines.
• unlisted: Anyone can access the content, and the content is not indexed by search engines
• share-link: Anyone with a secret token in the url can access the content.
• visitor-auth: Anyone authenticated through a JWT token can access the content.
• in-collection: Anyone who can access the parent collection can access the content. Only available for spaces in a collection.
• private: Authorized members can access the content.

publicunlistedshare-linkvisitor-authin-collectionprivate

createdAt*Timestamp (string (date-time))

updatedAt*Timestamp (string (date-time))

deletedAtTimestamp (string (date-time))

editModeSpaceEditMode (enum)

Determines how a Space can be edited.

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

livelocked

urls*object

URLs associated with the object

organization*string

ID of the organization owning this space

parentstring

ID of the parent collection.

gitSyncGitSyncState (object)

visitorAuthVisitorAuth (one of)

Custom backend for Visitor Authenticationall of

revision*string

ID of the active revision in the space.

defaultLevel*DefaultLevel (one of)

Default level for a piece of content

MemberRole (enum)nullable enumenum

comments*number

Count of opened comments on the space.

changeRequests*number

Total count of change requests on the space.

changeRequestsOpen*number

Count of open change requests on the space.

changeRequestsDraft*number

Count of draft change requests on the space.

permissions*object

The set of permissions for the space

Request

JavaScriptCurlPython

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "emoji": "🎉"
    }),
});
const data = await response.json();

Response

200default

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