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
or
or
organizationstringRequired
ID of the organization owning this space
parentstringOptional
ID of the parent collection.
languagestring · enumOptionalPossible values:
visitorAuthone ofOptional
or
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.
The Space object
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
OK
application/json
get
/spaces/{spaceId}
200
OK
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}
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
or
or
Responses
200
The space has been updated
application/json
patch
/spaces/{spaceId}
200
The space has been updated
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
201
Space duplicated
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
post
/spaces/{spaceId}/restore
200
Space restored
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
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
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
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
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
OK
application/json
404
The space could not be found.
application/json
get
/spaces/{spaceId}/links
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
OK
application/json
get
/orgs/{organizationId}/spaces
200
OK
Create a space
post
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
