Add a space to a site as a content source

Links an existing space to the site by creating a site space relationship.

Available in MCP

post

Authorizations

useroauth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

siteIdstringRequired

The unique id of the site

Body

application/json

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.

draftbooleanOptional

Whether the site space should be created as draft. Defaults to false.

Default: false

Responses

201

Space added to the site

application/json

post/orgs/{organizationId}/sites/{siteId}/site-spaces

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

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

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": "2026-07-21T22:59:54.399Z",
    "updatedAt": "2026-07-21T22:59:54.399Z",
    "deletedAt": "2026-07-21T22:59:54.399Z",
    "editMode": "live",
    "type": "styleguide",
    "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",
      "installationStatus": "unauthenticated",
      "installationProvider": "github",
      "installationId": "text",
      "url": "text",
      "operation": {
        "state": "running"
      },
      "updatedAt": "2026-07-21T22:59:54.399Z"
    },
    "visitorAuth": {
      "backend": "custom"
    },
    "revision": "text",
    "defaultLevel": "admin",
    "comments": 1,
    "changeRequests": 1,
    "changeRequestsOpen": 1,
    "changeRequestsDraft": 1,
    "internal_poweredByV2": true,
    "internal_singleWebsocket": true,
    "permissions": {
      "view": true,
      "access": true,
      "admin": true,
      "viewInviteLinks": true,
      "edit": true,
      "triggerGitSync": true,
      "comment": true,
      "merge": true,
      "review": true,
      "installIntegration": true
    }
  },
  "title": "text",
  "localizedTitle": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "default": true,
  "condition": "text",
  "draft": true,
  "hasAdvancedCustomizationFeature": true,
  "urls": {
    "published": "https://example.com"
  },
  "hidden": true
}