Spaces

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

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

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": "2025-12-27T04:17:57.776Z",
  "updatedAt": "2025-12-27T04:17:57.776Z",
  "deletedAt": "2025-12-27T04:17:57.776Z",
  "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": "2025-12-27T04:17:57.776Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "permissions": {
    "view": true,
    "access": true,
    "admin": true,
    "viewInviteLinks": true,
    "edit": true,
    "triggerGitSync": true,
    "comment": true,
    "merge": true,
    "review": true,
    "installIntegration": true
  }
}

List all space users permissions

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

rolestring · enumOptional

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

Responses

200

Listing of users who can access the space.

application/json

get

/spaces/{spaceId}/permissions/aggregate

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

200

Listing of users who can access the space.

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

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": "2025-12-27T04:17:57.776Z",
  "updatedAt": "2025-12-27T04:17:57.776Z",
  "deletedAt": "2025-12-27T04:17:57.776Z",
  "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": "2025-12-27T04:17:57.776Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "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": "2025-12-27T04:17:57.776Z",
  "updatedAt": "2025-12-27T04:17:57.776Z",
  "deletedAt": "2025-12-27T04:17:57.776Z",
  "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": "2025-12-27T04:17:57.776Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "permissions": {
    "view": true,
    "access": true,
    "admin": true,
    "viewInviteLinks": true,
    "edit": true,
    "triggerGitSync": true,
    "comment": true,
    "merge": true,
    "review": true,
    "installIntegration": true
  }
}

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

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": "2025-12-27T04:17:57.776Z",
  "updatedAt": "2025-12-27T04:17:57.776Z",
  "deletedAt": "2025-12-27T04:17:57.776Z",
  "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": "2025-12-27T04:17:57.776Z"
  },
  "visitorAuth": {
    "backend": "custom"
  },
  "revision": "text",
  "defaultLevel": "admin",
  "comments": 1,
  "changeRequests": 1,
  "changeRequestsOpen": 1,
  "changeRequestsDraft": 1,
  "permissions": {
    "view": true,
    "access": true,
    "admin": true,
    "viewInviteLinks": true,
    "edit": true,
    "triggerGitSync": true,
    "comment": true,
    "merge": true,
    "review": true,
    "installIntegration": true
  }
}

PreviousCollections NextChange Requests

Was this helpful?

Good night

Get a space by its ID

List all space users permissions

Create a space

Duplicate a space

Update a space