The State of Docs Survey 2025. Use your voice to prove why docs matter:
Take the survey
Product
PricingLog inSign up

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-12T21:04:01.285Z",
    "updatedAt": "2025-04-12T21:04:01.285Z",
    "deletedAt": "2025-04-12T21:04:01.285Z",
    "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-12T21:04:01.285Z"
    },
    "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
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "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-12T21:04:01.285Z",
        "updatedAt": "2025-04-12T21:04:01.285Z",
        "deletedAt": "2025-04-12T21:04:01.285Z",
        "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-12T21:04:01.285Z"
        },
        "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"
      }
    }
  ]
}

OK

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
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "spaceId": "text",
    "sectionId": "text"
  }'
{
  "object": "site-space",
  "id": "text",
  "path": "text",
  "section": "text",
  "space": {
    "object": "space",
    "id": "text",
    "title": "text",
    "emoji": "🎉",
    "visibility": "public",
    "createdAt": "2025-04-12T21:04:01.285Z",
    "updatedAt": "2025-04-12T21:04:01.285Z",
    "deletedAt": "2025-04-12T21:04:01.285Z",
    "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-12T21:04:01.285Z"
    },
    "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"
  }
}

Space added to the site

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
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Content

Site space has been deleted

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
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "path": "text",
    "condition": "text"
  }'
{
  "object": "site-space",
  "id": "text",
  "path": "text",
  "section": "text",
  "space": {
    "object": "space",
    "id": "text",
    "title": "text",
    "emoji": "🎉",
    "visibility": "public",
    "createdAt": "2025-04-12T21:04:01.285Z",
    "updatedAt": "2025-04-12T21:04:01.285Z",
    "deletedAt": "2025-04-12T21:04:01.285Z",
    "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-12T21:04:01.285Z"
    },
    "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"
  }
}

OK

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
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/move' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "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-12T21:04:01.285Z",
    "updatedAt": "2025-04-12T21:04:01.285Z",
    "deletedAt": "2025-04-12T21:04:01.285Z",
    "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-12T21:04:01.285Z"
    },
    "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"
  }
}

Site space moved

Was this helpful?