Homepage
CommunityPricingBlogGitBook Docs

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
Path parameters
spaceId*string

The unique id of the space

Query parameters
Response

OK

Body
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)

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)
revision*string

ID of the active revision in the space.

defaultLevel*DefaultLevel (one of)

Default level for a piece of content

Request
const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();
Response
{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2024-11-21T07:48:14.124Z",
  "updatedAt": "2024-11-21T07:48:14.124Z",
  "deletedAt": "2024-11-21T07:48:14.124Z",
  "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": "text",
    "operation": {
      "state": "running",
      "startedAt": "2024-11-21T07:48:14.124Z",
      "completedAt": "2024-11-21T07:48:14.124Z",
      "error": "text"
    },
    "url": "text",
    "updatedAt": "2024-11-21T07:48:14.124Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin"
}

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
Path parameters
spaceId*string

The unique id of the space

Query parameters
Response

Listing of users who can access the space.

Body
nextobject
countnumber

Total count of objects in the list

items*array of UserContentPermission (object)
Request
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
{
  "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
Path parameters
organizationId*string

The unique id of the organization

Body
titlestring
emojiEmoji (string)

Unicode codepoint or character of the emoji

Example: "🎉"
parentstring

ID of a parent collection

Response

Space created

Headers
Body
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)

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)
revision*string

ID of the active revision in the space.

defaultLevel*DefaultLevel (one of)

Default level for a piece of content

Request
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
{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2024-11-21T07:48:14.124Z",
  "updatedAt": "2024-11-21T07:48:14.124Z",
  "deletedAt": "2024-11-21T07:48:14.124Z",
  "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": "text",
    "operation": {
      "state": "running",
      "startedAt": "2024-11-21T07:48:14.124Z",
      "completedAt": "2024-11-21T07:48:14.124Z",
      "error": "text"
    },
    "url": "text",
    "updatedAt": "2024-11-21T07:48:14.124Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin"
}

POST a duplicate of a space

Create a duplicate of the space.

POSThttps://api.gitbook.com/v1/spaces/{spaceId}/duplicate
Authorization
Path parameters
spaceId*string

The unique id of the space

Response

Space duplicated

Headers
Body
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)

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)
revision*string

ID of the active revision in the space.

defaultLevel*DefaultLevel (one of)

Default level for a piece of content

Request
const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/duplicate', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();
Response
{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2024-11-21T07:48:14.124Z",
  "updatedAt": "2024-11-21T07:48:14.124Z",
  "deletedAt": "2024-11-21T07:48:14.124Z",
  "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": "text",
    "operation": {
      "state": "running",
      "startedAt": "2024-11-21T07:48:14.124Z",
      "completedAt": "2024-11-21T07:48:14.124Z",
      "error": "text"
    },
    "url": "text",
    "updatedAt": "2024-11-21T07:48:14.124Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin"
}

UPDATE a specific space

Update the details of a space

PATCHhttps://api.gitbook.com/v1/spaces/{spaceId}
Authorization
Path parameters
spaceId*string

The unique id of the space

Body
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

one of
Response

The space has been updated

Body
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)

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)
revision*string

ID of the active revision in the space.

defaultLevel*DefaultLevel (one of)

Default level for a piece of content

Request
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
{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2024-11-21T07:48:14.124Z",
  "updatedAt": "2024-11-21T07:48:14.124Z",
  "deletedAt": "2024-11-21T07:48:14.124Z",
  "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": "text",
    "operation": {
      "state": "running",
      "startedAt": "2024-11-21T07:48:14.124Z",
      "completedAt": "2024-11-21T07:48:14.124Z",
      "error": "text"
    },
    "url": "text",
    "updatedAt": "2024-11-21T07:48:14.124Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin"
}

Last updated