Site spaces

Control which spaces are linked and displayed in a docs site.

Associate or dissociate your organization's spaces to keep your content organized. This is particularly useful for larger organizations with numerous spaces.

The SiteSpace object

Attributes

objectstring · enumRequired

The object type, which is always "site-space"

Possible values:

idstringRequired

Unique identifier of the site-space

pathstring · min: 1 · max: 100Required

Path to the space on the site

sectionstringOptional

ID of the section the space belongs to in the site

titlestringRequired

defaultbooleanOptional

Whether this is the default space for the site

conditionstring · min: 1 · max: 1024Optional

Conditional expression used to evaluate whether the site space should be shown to the site's visitor.

hasAdvancedCustomizationFeaturebooleanOptional

Whether the space has advanced customization feature enabled

The SiteSpace object

{
  "object": "site-space",
  "id": "text",
  "path": "text",
  "section": "text",
  "space": {
    "object": "space",
    "id": "text",
    "title": "text",
    "emoji": "🎉",
    "visibility": "public",
    "createdAt": "2025-08-26T23:19:07.272Z",
    "updatedAt": "2025-08-26T23:19:07.272Z",
    "deletedAt": "2025-08-26T23:19:07.272Z",
    "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",
    "language": "en",
    "gitSync": {
      "repoName": "text",
      "installationProvider": "github",
      "integration": "text",
      "url": "text",
      "updatedAt": "2025-08-26T23:19:07.272Z"
    },
    "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
    }
  },
  "title": "text",
  "default": true,
  "condition": "text",
  "hasAdvancedCustomizationFeature": true,
  "urls": {
    "published": "https://example.com"
  }
}

List all the site spaces

get

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

shareKeystringOptional

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

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

defaultbooleanOptional

If true, only the default site space will be returned. If false, only the non-default site spaces are returned. If undefined, all site spaces are returned.

Responses

200

OK

application/json

Responseall of

get

HTTPcURLJavaScriptPython

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

200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site-space",
      "id": "text",
      "path": "text",
      "section": "text",
      "space": {
        "object": "space",
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-08-26T23:19:07.272Z",
        "updatedAt": "2025-08-26T23:19:07.272Z",
        "deletedAt": "2025-08-26T23:19:07.272Z",
        "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",
        "language": "en",
        "gitSync": {
          "repoName": "text",
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-08-26T23:19:07.272Z"
        },
        "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
        }
      },
      "title": "text",
      "default": true,
      "condition": "text",
      "hasAdvancedCustomizationFeature": true,
      "urls": {
        "published": "https://example.com"
      }
    }
  ]
}

Add a space to a site

post

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

spaceIdstringRequired

ID of the space

sectionIdstringOptional

ID of the section to add the space to. If not provided, the space will be added to the default section or at the root level if the site has no sections.

Responses

201

Space added to the site

application/json

post

HTTPcURLJavaScriptPython

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

{
  "spaceId": "text",
  "sectionId": "text"
}

201

Space added to the site

{
  "object": "site-space",
  "id": "text",
  "path": "text",
  "section": "text",
  "space": {
    "object": "space",
    "id": "text",
    "title": "text",
    "emoji": "🎉",
    "visibility": "public",
    "createdAt": "2025-08-26T23:19:07.272Z",
    "updatedAt": "2025-08-26T23:19:07.272Z",
    "deletedAt": "2025-08-26T23:19:07.272Z",
    "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",
    "language": "en",
    "gitSync": {
      "repoName": "text",
      "installationProvider": "github",
      "integration": "text",
      "url": "text",
      "updatedAt": "2025-08-26T23:19:07.272Z"
    },
    "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
    }
  },
  "title": "text",
  "default": true,
  "condition": "text",
  "hasAdvancedCustomizationFeature": true,
  "urls": {
    "published": "https://example.com"
  }
}

Delete a site space

delete

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

siteSpaceIdstringRequired

The unique id of the site-space relationship

Responses

204

Site space did not exist

205

Site space has been deleted

delete

HTTPcURLJavaScriptPython

DELETE /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a site space

patch

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

siteSpaceIdstringRequired

The unique id of the site-space relationship

Body

pathstring · min: 1 · max: 100Optional

Path to the space on the site

conditionone ofOptional

Conditional expression used to evaluate whether the site space should be shown to the site's visitor (should evaluate to a boolean). If not set, the condition will remain unchanged. If set to null, the condition will be removed.

string · min: 1 · max: 1024Optional

or

string · enum | nullableOptionalPossible values:

spaceIdstringOptional

The content that this site space points to. If not set, the space will remain unchanged.

Responses

200

OK

application/json

patch

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "path": "text",
  "condition": "text",
  "spaceId": "text"
}

200

OK

{
  "object": "site-space",
  "id": "text",
  "path": "text",
  "section": "text",
  "space": {
    "object": "space",
    "id": "text",
    "title": "text",
    "emoji": "🎉",
    "visibility": "public",
    "createdAt": "2025-08-26T23:19:07.272Z",
    "updatedAt": "2025-08-26T23:19:07.272Z",
    "deletedAt": "2025-08-26T23:19:07.272Z",
    "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",
    "language": "en",
    "gitSync": {
      "repoName": "text",
      "installationProvider": "github",
      "integration": "text",
      "url": "text",
      "updatedAt": "2025-08-26T23:19:07.272Z"
    },
    "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
    }
  },
  "title": "text",
  "default": true,
  "condition": "text",
  "hasAdvancedCustomizationFeature": true,
  "urls": {
    "published": "https://example.com"
  }
}

Deprecated

Move a site space to a new position. (Deprecated) use sortSiteStructure instead.

post

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

siteSpaceIdstringRequired

The unique id of the site-space relationship

Body

Responses

200

Site space moved

application/json

400

Invalid move site space position provided

application/json

404

No matching Site space found

application/json

post

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/move HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 113

{
  "position": {
    "before": {
      "type": "site-space",
      "siteSpace": "text"
    },
    "after": {
      "type": "site-space",
      "siteSpace": "text"
    }
  }
}

{
  "object": "site-space",
  "id": "text",
  "path": "text",
  "section": "text",
  "space": {
    "object": "space",
    "id": "text",
    "title": "text",
    "emoji": "🎉",
    "visibility": "public",
    "createdAt": "2025-08-26T23:19:07.272Z",
    "updatedAt": "2025-08-26T23:19:07.272Z",
    "deletedAt": "2025-08-26T23:19:07.272Z",
    "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",
    "language": "en",
    "gitSync": {
      "repoName": "text",
      "installationProvider": "github",
      "integration": "text",
      "url": "text",
      "updatedAt": "2025-08-26T23:19:07.272Z"
    },
    "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
    }
  },
  "title": "text",
  "default": true,
  "condition": "text",
  "hasAdvancedCustomizationFeature": true,
  "urls": {
    "published": "https://example.com"
  }
}