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"

Available options:
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

spaceobjectrequired
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

urlsobjectrequired

URLs associated with the object

The SiteSpace object

{
  "object": "site-space",
  "id": "text",
  "path": "text",
  "section": "text",
  "space": {
    "object": "space",
    "id": "text",
    "title": "text",
    "emoji": "🎉",
    "visibility": "public",
    "createdAt": "2025-04-16T04:38:07.745Z",
    "updatedAt": "2025-04-16T04:38:07.745Z",
    "deletedAt": "2025-04-16T04:38:07.745Z",
    "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": {
      "repoName": "text",
      "installationProvider": "github",
      "integration": "text",
      "url": "text",
      "updatedAt": "2025-04-16T04:38:07.745Z"
    },
    "visitorAuth": {
      "backend": "custom"
    },
    "revision": "text",
    "defaultLevel": "admin",
    "comments": 1,
    "changeRequests": 1,
    "changeRequestsOpen": 1,
    "changeRequestsDraft": 1,
    "permissions": {
      "access": true,
      "admin": true,
      "edit": true,
      "comment": true,
      "merge": true,
      "review": 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
application/json
all ofoptional
get
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-04-16T04:38:07.745Z",
        "updatedAt": "2025-04-16T04:38:07.745Z",
        "deletedAt": "2025-04-16T04:38:07.745Z",
        "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": {
          "repoName": "text",
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-04-16T04:38:07.745Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "permissions": {
          "access": true,
          "admin": true,
          "edit": true,
          "comment": true,
          "merge": true,
          "review": 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
application/json
objectoptional
post
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-04-16T04:38:07.745Z",
    "updatedAt": "2025-04-16T04:38:07.745Z",
    "deletedAt": "2025-04-16T04:38:07.745Z",
    "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": {
      "repoName": "text",
      "installationProvider": "github",
      "integration": "text",
      "url": "text",
      "updatedAt": "2025-04-16T04:38:07.745Z"
    },
    "visitorAuth": {
      "backend": "custom"
    },
    "revision": "text",
    "defaultLevel": "admin",
    "comments": 1,
    "changeRequests": 1,
    "changeRequestsOpen": 1,
    "changeRequestsDraft": 1,
    "permissions": {
      "access": true,
      "admin": true,
      "edit": true,
      "comment": true,
      "merge": true,
      "review": 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
delete
DELETE /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
205

Site space has been deleted

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.

Responses
application/json
objectoptional
patch
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: 34

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

OK

{
  "object": "site-space",
  "id": "text",
  "path": "text",
  "section": "text",
  "space": {
    "object": "space",
    "id": "text",
    "title": "text",
    "emoji": "🎉",
    "visibility": "public",
    "createdAt": "2025-04-16T04:38:07.745Z",
    "updatedAt": "2025-04-16T04:38:07.745Z",
    "deletedAt": "2025-04-16T04:38:07.745Z",
    "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": {
      "repoName": "text",
      "installationProvider": "github",
      "integration": "text",
      "url": "text",
      "updatedAt": "2025-04-16T04:38:07.745Z"
    },
    "visitorAuth": {
      "backend": "custom"
    },
    "revision": "text",
    "defaultLevel": "admin",
    "comments": 1,
    "changeRequests": 1,
    "changeRequestsOpen": 1,
    "changeRequestsDraft": 1,
    "permissions": {
      "access": true,
      "admin": true,
      "edit": true,
      "comment": true,
      "merge": true,
      "review": true
    }
  },
  "title": "text",
  "default": true,
  "condition": "text",
  "hasAdvancedCustomizationFeature": true,
  "urls": {
    "published": "https://example.com"
  }
}

Move a site space to a new position

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
positionobjectoptional

The position where to move the site space. When not provided the site space is moved at the end of the site.

Responses
application/json
objectoptional
post
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-04-16T04:38:07.745Z",
    "updatedAt": "2025-04-16T04:38:07.745Z",
    "deletedAt": "2025-04-16T04:38:07.745Z",
    "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": {
      "repoName": "text",
      "installationProvider": "github",
      "integration": "text",
      "url": "text",
      "updatedAt": "2025-04-16T04:38:07.745Z"
    },
    "visitorAuth": {
      "backend": "custom"
    },
    "revision": "text",
    "defaultLevel": "admin",
    "comments": 1,
    "changeRequests": 1,
    "changeRequestsOpen": 1,
    "changeRequestsDraft": 1,
    "permissions": {
      "access": true,
      "admin": true,
      "edit": true,
      "comment": true,
      "merge": true,
      "review": true
    }
  },
  "title": "text",
  "default": true,
  "condition": "text",
  "hasAdvancedCustomizationFeature": true,
  "urls": {
    "published": "https://example.com"
  }
}

Was this helpful?