Create a new documentation space in an organization

Creates a new space within the organization. A space is the primary container for documentation content, holding pages, files, and revisions. After creation, add the space to a site to make it publicly accessible, or start adding content directly via the space content endpoints.

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_-]+$

Body

application/json

and

anyOptional

or

anyOptional

or

or

Responses

201

Space created

application/json

post/orgs/{organizationId}/spaces

HTTPcURLJavaScriptPython

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": "2026-07-21T20:55:04.098Z",
  "updatedAt": "2026-07-21T20:55:04.098Z",
  "deletedAt": "2026-07-21T20:55:04.098Z",
  "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-21T20:55:04.098Z"
  },
  "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
  }
}