Spaces

Create, maintain, and remove content spaces.

Spaces are containers for your documentation or knowledge base content. Use this API to create new spaces, manage existing ones, and delete or archive spaces you no longer need.

The Space object

Attributes

objectstring · enumRequired

Type of Object, always equals to "space"

Possible values:

idstringRequired

Unique identifier for the space

titlestring · max: 50Required

Title of the space

emojistring · emoji · max: 50Required

An emoji for this space. It'll match the emoji shown in the GitBook app.

Example: 🎉

visibilitystring · enumRequired

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.

Possible values:

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

deletedAtstring · date-timeOptional

editModestring · enumOptional

Determines how a Space can be edited.

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

Possible values:

mergeRulesone ofRequired

organizationstringRequired

ID of the organization owning this space

parentstringOptional

ID of the parent collection.

languagestring · enumOptionalPossible values:

visitorAuthone ofOptional

revisionstringRequired

ID of the active revision in the space.

defaultLevelone ofRequired

Default level for a piece of content

string · enum · nullableOptional

"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.

Possible values:

commentsnumberRequired

Count of opened comments on the space.

changeRequestsnumberRequired

Total count of change requests on the space.

changeRequestsOpennumberRequired

Count of open change requests on the space.

changeRequestsDraftnumberRequired

Count of draft change requests on the space.

internal_poweredByV2booleanOptional

Whether the space is powered by V2 of the content system.

internal_singleWebsocketbooleanOptional

Whether the space uses a single websocket connection for all real-time communication.

The Space object

{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2026-02-25T02:16:51.196Z",
  "updatedAt": "2026-02-25T02:16:51.196Z",
  "deletedAt": "2026-02-25T02:16:51.196Z",
  "editMode": "live",
  "mergeRules": {
    "type": "inherit"
  },
  "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",
  "language": "en",
  "gitSync": {
    "repoName": "text",
    "installationProvider": "github",
    "integration": "text",
    "url": "text",
    "updatedAt": "2026-02-25T02:16:51.196Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "internal_poweredByV2": true,
  "internal_singleWebsocket": true,
  "permissions": {
    "view": true,
    "access": true,
    "admin": true,
    "viewInviteLinks": true,
    "edit": true,
    "triggerGitSync": true,
    "comment": true,
    "merge": true,
    "review": true,
    "installIntegration": true
  }
}

Get a space by its ID

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

Query parameters

shareKeystringOptional

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

Responses

200

application/json

objectstring · enumRequired

Type of Object, always equals to "space"

Possible values:

idstringRequired

Unique identifier for the space

titlestring · max: 50Required

Title of the space

emojistring · emoji · max: 50Required

An emoji for this space. It'll match the emoji shown in the GitBook app.

Example: 🎉

visibilitystring · enumRequired

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.

Possible values:

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

deletedAtstring · date-timeOptional

editModestring · enumOptional

Determines how a Space can be edited.

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

Possible values:

mergeRulesone ofRequired

organizationstringRequired

ID of the organization owning this space

parentstringOptional

ID of the parent collection.

languagestring · enumOptionalPossible values:

visitorAuthone ofOptional

revisionstringRequired

ID of the active revision in the space.

defaultLevelone ofRequired

Default level for a piece of content

string · enum · nullableOptional

Possible values:

commentsnumberRequired

Count of opened comments on the space.

changeRequestsnumberRequired

Total count of change requests on the space.

changeRequestsOpennumberRequired

Count of open change requests on the space.

changeRequestsDraftnumberRequired

Count of draft change requests on the space.

internal_poweredByV2booleanOptional

Whether the space is powered by V2 of the content system.

internal_singleWebsocketbooleanOptional

Whether the space uses a single websocket connection for all real-time communication.

get

/spaces/{spaceId}

GET /v1/spaces/{spaceId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2026-02-25T02:16:51.196Z",
  "updatedAt": "2026-02-25T02:16:51.196Z",
  "deletedAt": "2026-02-25T02:16:51.196Z",
  "editMode": "live",
  "mergeRules": {
    "type": "inherit"
  },
  "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",
  "language": "en",
  "gitSync": {
    "repoName": "text",
    "installationProvider": "github",
    "integration": "text",
    "url": "text",
    "updatedAt": "2026-02-25T02:16:51.196Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "internal_poweredByV2": true,
  "internal_singleWebsocket": true,
  "permissions": {
    "view": true,
    "access": true,
    "admin": true,
    "viewInviteLinks": true,
    "edit": true,
    "triggerGitSync": true,
    "comment": true,
    "merge": true,
    "review": true,
    "installIntegration": true
  }
}

Delete a space

delete

Deleted spaces will be permanently removed after 7 days.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

Responses

204

Space did not exist

205

Space has been deleted

delete

/spaces/{spaceId}

DELETE /v1/spaces/{spaceId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a space

patch

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

Body

and

anyOptional

Responses

200

The space has been updated

application/json

objectstring · enumRequired

Type of Object, always equals to "space"

Possible values:

idstringRequired

Unique identifier for the space

titlestring · max: 50Required

Title of the space

emojistring · emoji · max: 50Required

An emoji for this space. It'll match the emoji shown in the GitBook app.

Example: 🎉

visibilitystring · enumRequired

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.

Possible values:

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

deletedAtstring · date-timeOptional

editModestring · enumOptional

Determines how a Space can be edited.

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

Possible values:

mergeRulesone ofRequired

organizationstringRequired

ID of the organization owning this space

parentstringOptional

ID of the parent collection.

languagestring · enumOptionalPossible values:

visitorAuthone ofOptional

revisionstringRequired

ID of the active revision in the space.

defaultLevelone ofRequired

Default level for a piece of content

string · enum · nullableOptional

Possible values:

commentsnumberRequired

Count of opened comments on the space.

changeRequestsnumberRequired

Total count of change requests on the space.

changeRequestsOpennumberRequired

Count of open change requests on the space.

changeRequestsDraftnumberRequired

Count of draft change requests on the space.

internal_poweredByV2booleanOptional

Whether the space is powered by V2 of the content system.

internal_singleWebsocketbooleanOptional

Whether the space uses a single websocket connection for all real-time communication.

patch

/spaces/{spaceId}

PATCH /v1/spaces/{spaceId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 120

{
  "editMode": "live",
  "title": "text",
  "defaultLevel": "admin",
  "language": "en",
  "mergeRules": {
    "type": "inherit"
  },
  "emoji": "🎉"
}

200

The space has been updated

{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2026-02-25T02:16:51.196Z",
  "updatedAt": "2026-02-25T02:16:51.196Z",
  "deletedAt": "2026-02-25T02:16:51.196Z",
  "editMode": "live",
  "mergeRules": {
    "type": "inherit"
  },
  "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",
  "language": "en",
  "gitSync": {
    "repoName": "text",
    "installationProvider": "github",
    "integration": "text",
    "url": "text",
    "updatedAt": "2026-02-25T02:16:51.196Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "internal_poweredByV2": true,
  "internal_singleWebsocket": true,
  "permissions": {
    "view": true,
    "access": true,
    "admin": true,
    "viewInviteLinks": true,
    "edit": true,
    "triggerGitSync": true,
    "comment": true,
    "merge": true,
    "review": true,
    "installIntegration": true
  }
}

Duplicate a space

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

Responses

201

Space duplicated

application/json

post

/spaces/{spaceId}/duplicate

POST /v1/spaces/{spaceId}/duplicate HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

201

Space duplicated

{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2026-02-25T02:16:51.196Z",
  "updatedAt": "2026-02-25T02:16:51.196Z",
  "deletedAt": "2026-02-25T02:16:51.196Z",
  "editMode": "live",
  "mergeRules": {
    "type": "inherit"
  },
  "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",
  "language": "en",
  "gitSync": {
    "repoName": "text",
    "installationProvider": "github",
    "integration": "text",
    "url": "text",
    "updatedAt": "2026-02-25T02:16:51.196Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "internal_poweredByV2": true,
  "internal_singleWebsocket": true,
  "permissions": {
    "view": true,
    "access": true,
    "admin": true,
    "viewInviteLinks": true,
    "edit": true,
    "triggerGitSync": true,
    "comment": true,
    "merge": true,
    "review": true,
    "installIntegration": true
  }
}

Restore a deleted space

post

Only spaces deleted in the last 7 days can be restored.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

Responses

200

Space restored

application/json

objectstring · enumRequired

Type of Object, always equals to "space"

Possible values:

idstringRequired

Unique identifier for the space

titlestring · max: 50Required

Title of the space

emojistring · emoji · max: 50Required

An emoji for this space. It'll match the emoji shown in the GitBook app.

Example: 🎉

visibilitystring · enumRequired

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.

Possible values:

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

deletedAtstring · date-timeOptional

editModestring · enumOptional

Determines how a Space can be edited.

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

Possible values:

mergeRulesone ofRequired

organizationstringRequired

ID of the organization owning this space

parentstringOptional

ID of the parent collection.

languagestring · enumOptionalPossible values:

visitorAuthone ofOptional

revisionstringRequired

ID of the active revision in the space.

defaultLevelone ofRequired

Default level for a piece of content

string · enum · nullableOptional

Possible values:

commentsnumberRequired

Count of opened comments on the space.

changeRequestsnumberRequired

Total count of change requests on the space.

changeRequestsOpennumberRequired

Count of open change requests on the space.

changeRequestsDraftnumberRequired

Count of draft change requests on the space.

internal_poweredByV2booleanOptional

Whether the space is powered by V2 of the content system.

internal_singleWebsocketbooleanOptional

Whether the space uses a single websocket connection for all real-time communication.

post

/spaces/{spaceId}/restore

POST /v1/spaces/{spaceId}/restore HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Space restored

{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2026-02-25T02:16:51.196Z",
  "updatedAt": "2026-02-25T02:16:51.196Z",
  "deletedAt": "2026-02-25T02:16:51.196Z",
  "editMode": "live",
  "mergeRules": {
    "type": "inherit"
  },
  "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",
  "language": "en",
  "gitSync": {
    "repoName": "text",
    "installationProvider": "github",
    "integration": "text",
    "url": "text",
    "updatedAt": "2026-02-25T02:16:51.196Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "internal_poweredByV2": true,
  "internal_singleWebsocket": true,
  "permissions": {
    "view": true,
    "access": true,
    "admin": true,
    "viewInviteLinks": true,
    "edit": true,
    "triggerGitSync": true,
    "comment": true,
    "merge": true,
    "review": true,
    "installIntegration": true
  }
}

Move a space to a new position

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

Body

parentstring · nullableOptional

The unique id of the parent collection

Responses

200

Space moved

application/json

objectstring · enumRequired

Type of Object, always equals to "space"

Possible values:

idstringRequired

Unique identifier for the space

titlestring · max: 50Required

Title of the space

emojistring · emoji · max: 50Required

An emoji for this space. It'll match the emoji shown in the GitBook app.

Example: 🎉

visibilitystring · enumRequired

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.

Possible values:

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

deletedAtstring · date-timeOptional

editModestring · enumOptional

Determines how a Space can be edited.

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

Possible values:

mergeRulesone ofRequired

organizationstringRequired

ID of the organization owning this space

parentstringOptional

ID of the parent collection.

languagestring · enumOptionalPossible values:

visitorAuthone ofOptional

revisionstringRequired

ID of the active revision in the space.

defaultLevelone ofRequired

Default level for a piece of content

string · enum · nullableOptional

Possible values:

commentsnumberRequired

Count of opened comments on the space.

changeRequestsnumberRequired

Total count of change requests on the space.

changeRequestsOpennumberRequired

Count of open change requests on the space.

changeRequestsDraftnumberRequired

Count of draft change requests on the space.

internal_poweredByV2booleanOptional

Whether the space is powered by V2 of the content system.

internal_singleWebsocketbooleanOptional

Whether the space uses a single websocket connection for all real-time communication.

400

Invalid position space or collection provided

application/json

404

No matching Space found for given ID

application/json

409

Operation would not result in any update

application/json

post

/spaces/{spaceId}/move

POST /v1/spaces/{spaceId}/move HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 111

{
  "parent": "text",
  "position": {
    "before": {
      "type": "space",
      "space": "text"
    },
    "after": {
      "type": "space",
      "space": "text"
    }
  }
}

{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2026-02-25T02:16:51.196Z",
  "updatedAt": "2026-02-25T02:16:51.196Z",
  "deletedAt": "2026-02-25T02:16:51.196Z",
  "editMode": "live",
  "mergeRules": {
    "type": "inherit"
  },
  "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",
  "language": "en",
  "gitSync": {
    "repoName": "text",
    "installationProvider": "github",
    "integration": "text",
    "url": "text",
    "updatedAt": "2026-02-25T02:16:51.196Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "internal_poweredByV2": true,
  "internal_singleWebsocket": true,
  "permissions": {
    "view": true,
    "access": true,
    "admin": true,
    "viewInviteLinks": true,
    "edit": true,
    "triggerGitSync": true,
    "comment": true,
    "merge": true,
    "review": true,
    "installIntegration": true
  }
}

Transfer a space

post

Transfer a space to another organization, collection or both.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

Body

organizationstringRequired

The unique id of the target organization

Responses

200

Space transferred

application/json

objectstring · enumRequired

Type of Object, always equals to "space"

Possible values:

idstringRequired

Unique identifier for the space

titlestring · max: 50Required

Title of the space

emojistring · emoji · max: 50Required

An emoji for this space. It'll match the emoji shown in the GitBook app.

Example: 🎉

visibilitystring · enumRequired

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.

Possible values:

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

deletedAtstring · date-timeOptional

editModestring · enumOptional

Determines how a Space can be edited.

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

Possible values:

mergeRulesone ofRequired

organizationstringRequired

ID of the organization owning this space

parentstringOptional

ID of the parent collection.

languagestring · enumOptionalPossible values:

visitorAuthone ofOptional

revisionstringRequired

ID of the active revision in the space.

defaultLevelone ofRequired

Default level for a piece of content

string · enum · nullableOptional

Possible values:

commentsnumberRequired

Count of opened comments on the space.

changeRequestsnumberRequired

Total count of change requests on the space.

changeRequestsOpennumberRequired

Count of open change requests on the space.

changeRequestsDraftnumberRequired

Count of draft change requests on the space.

internal_poweredByV2booleanOptional

Whether the space is powered by V2 of the content system.

internal_singleWebsocketbooleanOptional

Whether the space uses a single websocket connection for all real-time communication.

404

No matching Space found for given ID

application/json

409

Transfer would not result in any update

application/json

412

The space cannot be moved.

application/json

post

/spaces/{spaceId}/transfer

POST /v1/spaces/{spaceId}/transfer HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "organization": "text"
}

{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2026-02-25T02:16:51.196Z",
  "updatedAt": "2026-02-25T02:16:51.196Z",
  "deletedAt": "2026-02-25T02:16:51.196Z",
  "editMode": "live",
  "mergeRules": {
    "type": "inherit"
  },
  "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",
  "language": "en",
  "gitSync": {
    "repoName": "text",
    "installationProvider": "github",
    "integration": "text",
    "url": "text",
    "updatedAt": "2026-02-25T02:16:51.196Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "internal_poweredByV2": true,
  "internal_singleWebsocket": true,
  "permissions": {
    "view": true,
    "access": true,
    "admin": true,
    "viewInviteLinks": true,
    "edit": true,
    "triggerGitSync": true,
    "comment": true,
    "merge": true,
    "review": true,
    "installIntegration": true
  }
}

Get all links in a space including their status and location where they appear.

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

statusstring · enumOptional

Text to display to represent the reference. Possible values include:

ok - No problems detected for this content reference.
broken - The target does not exist in the revision.
in-app - The target is a URL link pointing to an internal location in the app.

Possible values:

Responses

200

application/json

404

The space could not be found.

application/json

get

/spaces/{spaceId}/links

GET /v1/spaces/{spaceId}/links HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "stats": {
    "total": 1,
    "broken": {
      "total": 1,
      "changeRequest": 1
    }
  },
  "items": [
    {
      "status": "ok",
      "relation": "reference",
      "targetReference": {
        "kind": "file",
        "organization": {
          "object": "organization",
          "id": "text",
          "title": "text",
          "createdAt": "2026-02-25T02:16:51.196Z",
          "emailDomains": [
            "text"
          ],
          "hostname": "text",
          "type": "business",
          "useCase": "internalDocs",
          "communityType": "nonProfit",
          "defaultRole": "admin",
          "defaultContent": {
            "type": "site",
            "site": "text"
          },
          "sso": true,
          "ai": true,
          "inviteLinks": true,
          "plan": "free_2024",
          "billing": {
            "interval": "monthly",
            "endDate": "2026-02-25T02:16:51.196Z",
            "hasPaymentFailed": true,
            "isScheduledToCancel": true,
            "pricing": {
              "members": {
                "plus_2024": {
                  "monthly": 1,
                  "yearly": 1
                },
                "pro_2024": {
                  "monthly": 1,
                  "yearly": 1
                }
              },
              "sites": {
                "premium": {
                  "monthly": 1,
                  "yearly": 1
                },
                "ultimate": {
                  "monthly": 1,
                  "yearly": 1
                }
              }
            },
            "usageAddons": {
              "ANY_ADDITIONAL_PROPERTY": {
                "enabled": true
              }
            },
            "minUsers": 1,
            "maxUsers": 1,
            "paidMembers": 1
          },
          "mergeRules": {
            "type": "rules",
            "rules": [
              {
                "rule": "require_specific_reviewers",
                "users": [
                  "text"
                ]
              }
            ]
          },
          "urls": {
            "location": "https://example.com",
            "app": "https://example.com",
            "logo": "https://example.com"
          },
          "trial": {
            "status": "notapplicable",
            "count": 1,
            "endDate": "2026-02-25T02:16:51.196Z",
            "decision": "downgrade"
          },
          "customHostname": "text",
          "blocked": {
            "source": "backoffice",
            "reason": "text"
          },
          "internal_billingMigration": {
            "deadline": "2026-02-25T02:16:51.196Z",
            "discountPercent": 1,
            "discountEndDate": "2026-02-25T02:16:51.196Z"
          },
          "permissions": {
            "view": true,
            "access": true,
            "admin": true,
            "ownTeam": true,
            "createContent": true,
            "createOpenAPISpec": true,
            "ingestConversations": true,
            "viewBilling": true,
            "listMembers": true,
            "listTeams": true,
            "listIntegrations": true,
            "listInstallations": true,
            "installIntegration": true
          }
        },
        "space": {
          "object": "space",
          "id": "text",
          "title": "text",
          "emoji": "🎉",
          "visibility": "public",
          "createdAt": "2026-02-25T02:16:51.196Z",
          "updatedAt": "2026-02-25T02:16:51.196Z",
          "deletedAt": "2026-02-25T02:16:51.196Z",
          "editMode": "live",
          "mergeRules": {
            "type": "inherit"
          },
          "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",
          "language": "en",
          "gitSync": {
            "repoName": "text",
            "installationProvider": "github",
            "integration": "text",
            "url": "text",
            "updatedAt": "2026-02-25T02:16:51.196Z"
          },
          "visitorAuth": {
            "backend": "custom"
          },
          "revision": "text",
          "defaultLevel": "admin",
          "comments": 1,
          "changeRequests": 1,
          "changeRequestsOpen": 1,
          "changeRequestsDraft": 1,
          "internal_poweredByV2": true,
          "internal_singleWebsocket": true,
          "permissions": {
            "view": true,
            "access": true,
            "admin": true,
            "viewInviteLinks": true,
            "edit": true,
            "triggerGitSync": true,
            "comment": true,
            "merge": true,
            "review": true,
            "installIntegration": true
          }
        },
        "versionContext": "[Circular Reference]",
        "file": {
          "id": "text",
          "name": "text",
          "contentType": "text",
          "downloadURL": "text",
          "size": 1,
          "dimensions": {
            "width": 1,
            "height": 1
          },
          "git": {
            "oid": "text",
            "path": "text"
          }
        }
      },
      "locationReferences": [
        {
          "kind": "file",
          "organization": {
            "object": "organization",
            "id": "text",
            "title": "text",
            "createdAt": "2026-02-25T02:16:51.196Z",
            "emailDomains": [
              "text"
            ],
            "hostname": "text",
            "type": "business",
            "useCase": "internalDocs",
            "communityType": "nonProfit",
            "defaultRole": "admin",
            "defaultContent": {
              "type": "site",
              "site": "text"
            },
            "sso": true,
            "ai": true,
            "inviteLinks": true,
            "plan": "free_2024",
            "billing": {
              "interval": "monthly",
              "endDate": "2026-02-25T02:16:51.196Z",
              "hasPaymentFailed": true,
              "isScheduledToCancel": true,
              "pricing": {
                "members": {
                  "plus_2024": {
                    "monthly": 1,
                    "yearly": 1
                  },
                  "pro_2024": {
                    "monthly": 1,
                    "yearly": 1
                  }
                },
                "sites": {
                  "premium": {
                    "monthly": 1,
                    "yearly": 1
                  },
                  "ultimate": {
                    "monthly": 1,
                    "yearly": 1
                  }
                }
              },
              "usageAddons": {
                "ANY_ADDITIONAL_PROPERTY": {
                  "enabled": true
                }
              },
              "minUsers": 1,
              "maxUsers": 1,
              "paidMembers": 1
            },
            "mergeRules": {
              "type": "rules",
              "rules": [
                {
                  "rule": "require_specific_reviewers",
                  "users": [
                    "text"
                  ]
                }
              ]
            },
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "logo": "https://example.com"
            },
            "trial": {
              "status": "notapplicable",
              "count": 1,
              "endDate": "2026-02-25T02:16:51.196Z",
              "decision": "downgrade"
            },
            "customHostname": "text",
            "blocked": {
              "source": "backoffice",
              "reason": "text"
            },
            "internal_billingMigration": {
              "deadline": "2026-02-25T02:16:51.196Z",
              "discountPercent": 1,
              "discountEndDate": "2026-02-25T02:16:51.196Z"
            },
            "permissions": {
              "view": true,
              "access": true,
              "admin": true,
              "ownTeam": true,
              "createContent": true,
              "createOpenAPISpec": true,
              "ingestConversations": true,
              "viewBilling": true,
              "listMembers": true,
              "listTeams": true,
              "listIntegrations": true,
              "listInstallations": true,
              "installIntegration": true
            }
          },
          "space": {
            "object": "space",
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2026-02-25T02:16:51.196Z",
            "updatedAt": "2026-02-25T02:16:51.196Z",
            "deletedAt": "2026-02-25T02:16:51.196Z",
            "editMode": "live",
            "mergeRules": {
              "type": "inherit"
            },
            "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",
            "language": "en",
            "gitSync": {
              "repoName": "text",
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2026-02-25T02:16:51.196Z"
            },
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "internal_poweredByV2": true,
            "internal_singleWebsocket": true,
            "permissions": {
              "view": true,
              "access": true,
              "admin": true,
              "viewInviteLinks": true,
              "edit": true,
              "triggerGitSync": true,
              "comment": true,
              "merge": true,
              "review": true,
              "installIntegration": true
            }
          },
          "versionContext": "[Circular Reference]",
          "file": {
            "id": "text",
            "name": "text",
            "contentType": "text",
            "downloadURL": "text",
            "size": 1,
            "dimensions": {
              "width": 1,
              "height": 1
            },
            "git": {
              "oid": "text",
              "path": "text"
            }
          }
        }
      ]
    }
  ]
}

List all spaces

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

application/json

get

/orgs/{organizationId}/spaces

GET /v1/orgs/{organizationId}/spaces HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "space",
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "visibility": "public",
      "createdAt": "2026-02-25T02:16:51.196Z",
      "updatedAt": "2026-02-25T02:16:51.196Z",
      "deletedAt": "2026-02-25T02:16:51.196Z",
      "editMode": "live",
      "mergeRules": {
        "type": "inherit"
      },
      "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",
      "language": "en",
      "gitSync": {
        "repoName": "text",
        "installationProvider": "github",
        "integration": "text",
        "url": "text",
        "updatedAt": "2026-02-25T02:16:51.196Z"
      },
      "visitorAuth": {
        "backend": "custom"
      },
      "revision": "text",
      "defaultLevel": "admin",
      "comments": 1,
      "changeRequests": 1,
      "changeRequestsOpen": 1,
      "changeRequestsDraft": 1,
      "internal_poweredByV2": true,
      "internal_singleWebsocket": true,
      "permissions": {
        "view": true,
        "access": true,
        "admin": true,
        "viewInviteLinks": true,
        "edit": true,
        "triggerGitSync": true,
        "comment": true,
        "merge": true,
        "review": true,
        "installIntegration": true
      }
    }
  ]
}

Create a space

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

Body

and

anyOptional

Responses

201

Space created

application/json

post

/orgs/{organizationId}/spaces

POST /v1/orgs/{organizationId}/spaces HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 118

{
  "title": "text",
  "emoji": "🎉",
  "parent": "text",
  "language": "en",
  "editMode": "live",
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

201

Space created

{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2026-02-25T02:16:51.196Z",
  "updatedAt": "2026-02-25T02:16:51.196Z",
  "deletedAt": "2026-02-25T02:16:51.196Z",
  "editMode": "live",
  "mergeRules": {
    "type": "inherit"
  },
  "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",
  "language": "en",
  "gitSync": {
    "repoName": "text",
    "installationProvider": "github",
    "integration": "text",
    "url": "text",
    "updatedAt": "2026-02-25T02:16:51.196Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "internal_poweredByV2": true,
  "internal_singleWebsocket": true,
  "permissions": {
    "view": true,
    "access": true,
    "admin": true,
    "viewInviteLinks": true,
    "edit": true,
    "triggerGitSync": true,
    "comment": true,
    "merge": true,
    "review": true,
    "installIntegration": true
  }
}

Last updated 9 hours ago

Was this helpful?

Good night

hashtagThe Space object

The Space object

hashtagGet a space by its ID

hashtagDelete a space

hashtagUpdate a space

hashtagDuplicate a space

hashtagRestore a deleted space

hashtagMove a space to a new position

hashtagTransfer a space

hashtagGet all links in a space including their status and location where they appear.

hashtagList all spaces

hashtagCreate a space

The Space object

Get a space by its ID

Delete a space

Update a space

Duplicate a space

Restore a deleted space

Move a space to a new position

Transfer a space

Get all links in a space including their status and location where they appear.

List all spaces

Create a space