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

Spaces

Create, maintain, and remove content spaces.

Spaces are containers for your documentation or knowledge base content. Use this API to create new spaces, manage existing ones, and delete or archive spaces you no longer need.

The Space object

Attributes
objectstring · enumrequired

Type of Object, always equals to "space"

Available options:
idstringrequired

Unique identifier for the space

titlestring · max: 50required

Title of the space

emojistring · emoji · max: 50required

An emoji for this space. It'll match the emoji shown in the GitBook app.

Example: 🎉
visibilitystring · enumrequired
  • public: Anyone can access the content, and the content is indexed by search engines.
  • unlisted: Anyone can access the content, and the content is not indexed by search engines
  • share-link: Anyone with a secret token in the url can access the content.
  • visitor-auth: Anyone authenticated through a JWT token can access the content.
  • in-collection: Anyone who can access the parent collection can access the content. Only available for spaces in a collection.
  • private: Authorized members can access the content.
Available options:
createdAtstring · date-timerequired
updatedAtstring · date-timerequired
deletedAtstring · date-timeoptional
editModestring · enumoptional

Determines how a Space can be edited.

  • live: Users can directly edit the space
  • locked: All edits are locked for this space.
Available options:
urlsobjectrequired

URLs associated with the object

organizationstringrequired

ID of the organization owning this space

parentstringoptional

ID of the parent collection.

gitSyncobjectoptional

visitorAuthone ofoptional

revisionstringrequired

ID of the active revision in the space.

defaultLevelone ofrequired

Default level for a piece of content

"The role of a member in an organization. "admin": Can administrate the content: create, delete spaces, ... "create": Can create content. "review": Can review content. "edit": Can edit the content (live or change requests). "comment": Can access the content and its discussions. "read": Can access the content, but cannot update it in any way.

commentsnumberrequired

Count of opened comments on the space.

changeRequestsnumberrequired

Total count of change requests on the space.

changeRequestsOpennumberrequired

Count of open change requests on the space.

changeRequestsDraftnumberrequired

Count of draft change requests on the space.

permissionsobjectrequired

The set of permissions for the space

The Space object

{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2025-04-16T19:26:17.148Z",
  "updatedAt": "2025-04-16T19:26:17.148Z",
  "deletedAt": "2025-04-16T19:26:17.148Z",
  "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-16T19:26:17.148Z"
  },
  "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
  }
}

Get a space by its ID

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Query parameters
shareKeystringoptional

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

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2025-04-16T19:26:17.148Z",
  "updatedAt": "2025-04-16T19:26:17.148Z",
  "deletedAt": "2025-04-16T19:26:17.148Z",
  "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-16T19:26:17.148Z"
  },
  "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
  }
}

OK

Delete a space

delete

Deleted spaces will be permanently removed after 7 days.

Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Responses
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Content

Space has been deleted

Update a space

patch
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Body
all ofoptional

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "editMode": "live",
    "title": "text",
    "defaultLevel": "admin",
    "emoji": "🎉"
  }'
{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2025-04-16T19:26:17.148Z",
  "updatedAt": "2025-04-16T19:26:17.148Z",
  "deletedAt": "2025-04-16T19:26:17.148Z",
  "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-16T19:26:17.148Z"
  },
  "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
  }
}

The space has been updated

Duplicate a space

post
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/duplicate' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2025-04-16T19:26:17.148Z",
  "updatedAt": "2025-04-16T19:26:17.148Z",
  "deletedAt": "2025-04-16T19:26:17.148Z",
  "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-16T19:26:17.148Z"
  },
  "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
  }
}

Space duplicated

Restore a deleted space

post

Only spaces deleted in the last 7 days can be restored.

Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/restore' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2025-04-16T19:26:17.148Z",
  "updatedAt": "2025-04-16T19:26:17.148Z",
  "deletedAt": "2025-04-16T19:26:17.148Z",
  "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-16T19:26:17.148Z"
  },
  "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
  }
}

Space restored

Move a space to a new position

post
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Body
parentstring | nullableoptional

The unique id of the parent collection

positionobjectoptional

Where to move the space. By default, it will be moved at the end.

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/move' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "parent": "text",
    "position": {
      "before": {
        "type": "space",
        "space": "text"
      },
      "after": {
        "type": "space",
        "space": "text"
      }
    }
  }'
{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2025-04-16T19:26:17.148Z",
  "updatedAt": "2025-04-16T19:26:17.148Z",
  "deletedAt": "2025-04-16T19:26:17.148Z",
  "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-16T19:26:17.148Z"
  },
  "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
  }
}

Space moved

Transfer a space

post

Transfer a space to another organization, collection or both.

Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Body
organizationstringrequired

The unique id of the target organization

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/transfer' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "organization": "text"
  }'
{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2025-04-16T19:26:17.148Z",
  "updatedAt": "2025-04-16T19:26:17.148Z",
  "deletedAt": "2025-04-16T19:26:17.148Z",
  "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-16T19:26:17.148Z"
  },
  "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
  }
}

Space transferred

Get all links in a space including their status and location where they appear.

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

statusstring · enumoptional

Text to display to represent the reference. Possible values include:

  • ok - No problems detected for this content reference.
  • broken - The target does not exist in the revision.
  • in-app - The target is a URL link pointing to an internal location in the app.
Available options:
Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/links' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "stats": {
    "total": 1,
    "broken": {
      "total": 1,
      "changeRequest": 1
    }
  },
  "items": [
    {
      "status": "ok",
      "relation": "reference",
      "targetReference": {
        "kind": "file",
        "organization": {
          "object": "organization",
          "id": "text",
          "title": "text",
          "createdAt": "2025-04-16T19:26:17.148Z",
          "emailDomains": [
            "text"
          ],
          "hostname": "text",
          "type": "business",
          "useCase": "internalDocs",
          "communityType": "nonProfit",
          "defaultRole": "admin",
          "defaultContent": {
            "type": "site",
            "site": "text"
          },
          "sso": true,
          "ai": true,
          "inviteLinks": true,
          "plan": "free_2024",
          "billing": {
            "interval": "monthly",
            "endDate": "2025-04-16T19:26:17.148Z",
            "hasPaymentFailed": true,
            "isScheduledToCancel": true
          },
          "urls": {
            "location": "https://example.com",
            "app": "https://example.com",
            "logo": "https://example.com"
          },
          "trial": {
            "status": "notapplicable",
            "endDate": "2025-04-16T19:26:17.148Z",
            "decision": "downgrade"
          },
          "customHostname": "text",
          "blocked": {
            "reason": "security"
          },
          "internal_isOnNewTrial": true,
          "internal_billingMigration": {
            "deadline": "2025-04-16T19:26:17.148Z",
            "discountPercent": 1,
            "discountEndDate": "2025-04-16T19:26:17.148Z"
          },
          "permissions": {
            "admin": true,
            "createContent": true
          }
        },
        "space": {
          "object": "space",
          "id": "text",
          "title": "text",
          "emoji": "🎉",
          "visibility": "public",
          "createdAt": "2025-04-16T19:26:17.148Z",
          "updatedAt": "2025-04-16T19:26:17.148Z",
          "deletedAt": "2025-04-16T19:26:17.148Z",
          "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-16T19:26:17.148Z"
          },
          "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
          }
        },
        "versionContext": "[Circular Reference]",
        "file": {
          "id": "text",
          "name": "text",
          "contentType": "text",
          "downloadURL": "text",
          "size": 1,
          "dimensions": {
            "width": 1,
            "height": 1
          },
          "git": {
            "oid": "text",
            "path": "text"
          }
        }
      },
      "locationReferences": [
        {
          "kind": "file",
          "organization": {
            "object": "organization",
            "id": "text",
            "title": "text",
            "createdAt": "2025-04-16T19:26:17.148Z",
            "emailDomains": [
              "text"
            ],
            "hostname": "text",
            "type": "business",
            "useCase": "internalDocs",
            "communityType": "nonProfit",
            "defaultRole": "admin",
            "defaultContent": {
              "type": "site",
              "site": "text"
            },
            "sso": true,
            "ai": true,
            "inviteLinks": true,
            "plan": "free_2024",
            "billing": {
              "interval": "monthly",
              "endDate": "2025-04-16T19:26:17.148Z",
              "hasPaymentFailed": true,
              "isScheduledToCancel": true
            },
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "logo": "https://example.com"
            },
            "trial": {
              "status": "notapplicable",
              "endDate": "2025-04-16T19:26:17.148Z",
              "decision": "downgrade"
            },
            "customHostname": "text",
            "blocked": {
              "reason": "security"
            },
            "internal_isOnNewTrial": true,
            "internal_billingMigration": {
              "deadline": "2025-04-16T19:26:17.148Z",
              "discountPercent": 1,
              "discountEndDate": "2025-04-16T19:26:17.148Z"
            },
            "permissions": {
              "admin": true,
              "createContent": true
            }
          },
          "space": {
            "object": "space",
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-04-16T19:26:17.148Z",
            "updatedAt": "2025-04-16T19:26:17.148Z",
            "deletedAt": "2025-04-16T19:26:17.148Z",
            "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-16T19:26:17.148Z"
            },
            "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
            }
          },
          "versionContext": "[Circular Reference]",
          "file": {
            "id": "text",
            "name": "text",
            "contentType": "text",
            "downloadURL": "text",
            "size": 1,
            "dimensions": {
              "width": 1,
              "height": 1
            },
            "git": {
              "oid": "text",
              "path": "text"
            }
          }
        }
      ]
    }
  ]
}

OK

List all spaces

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/spaces' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "space",
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "visibility": "public",
      "createdAt": "2025-04-16T19:26:17.148Z",
      "updatedAt": "2025-04-16T19:26:17.148Z",
      "deletedAt": "2025-04-16T19:26:17.148Z",
      "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-16T19:26:17.148Z"
      },
      "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
      }
    }
  ]
}

OK

Create a space

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Body
titlestring · max: 50optional
emojistring · emoji · max: 50optional

Unicode codepoint or character of the emoji

Example: 🎉
privatebooleanoptionalDeprecated

Private spaces are no longer supported by GitBook.

parentstringoptional

ID of a parent collection

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/spaces' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "emoji": "🎉",
    "parent": "text"
  }'
{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2025-04-16T19:26:17.148Z",
  "updatedAt": "2025-04-16T19:26:17.148Z",
  "deletedAt": "2025-04-16T19:26:17.148Z",
  "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-16T19:26:17.148Z"
  },
  "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
  }
}

Space created

Was this helpful?