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

Spaces

Manage your project spaces.

Get the details about a space.

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-03T20:28:16.020Z",
  "updatedAt": "2025-04-03T20:28:16.020Z",
  "deletedAt": "2025-04-03T20:28:16.020Z",
  "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-03T20:28:16.020Z"
  },
  "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

Soft-deletes a space. Soft-deleted spaces will be permanently removed after 7 days.

delete
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 body

Space has been deleted

Update the details of 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-03T20:28:16.020Z",
  "updatedAt": "2025-04-03T20:28:16.020Z",
  "deletedAt": "2025-04-03T20:28:16.020Z",
  "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-03T20:28:16.020Z"
  },
  "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

Create a duplicate of the 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-03T20:28:16.020Z",
  "updatedAt": "2025-04-03T20:28:16.020Z",
  "deletedAt": "2025-04-03T20:28:16.020Z",
  "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-03T20:28:16.020Z"
  },
  "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 recently soft-deleted 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}/restore' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2025-04-03T20:28:16.020Z",
  "updatedAt": "2025-04-03T20:28:16.020Z",
  "deletedAt": "2025-04-03T20:28:16.020Z",
  "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-03T20:28:16.020Z"
  },
  "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-03T20:28:16.020Z",
  "updatedAt": "2025-04-03T20:28:16.020Z",
  "deletedAt": "2025-04-03T20:28:16.020Z",
  "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-03T20:28:16.020Z"
  },
  "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 to another organization, collection or both.

post
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-03T20:28:16.020Z",
  "updatedAt": "2025-04-03T20:28:16.020Z",
  "deletedAt": "2025-04-03T20:28:16.020Z",
  "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-03T20:28:16.020Z"
  },
  "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

Resolve a URL to an embed in a given space

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Query parameters
urlstringrequired

URL to resolve

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/embed?url=text' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "title": "text",
  "site": "text",
  "icon": "text",
  "type": "link"
}

OK

Import a Git repository

post
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Body
urlstringrequired

URL of the Git repository to import. It can contain basic auth credentials.

refstringrequired

Git ref to import in the format "refs/heads/main"

repoCacheIDstringoptional

Unique identifier to use to cache the Git repository across multiple operations.

repoTreeURLstringoptional

URL to use as a prefix for external file references.

repoCommitURLstringoptional

URL to use as a prefix for the commit URL.

repoProjectDirectorystringoptional

Path to a root directory for the project in the repository.

timestampstring · date-timeoptional

The timestamp of the event that triggered this import. It ensures that Git sync import and export operations are executed in the same order on GitBook and on the remote repository.

forcebooleanoptional
standalonebooleanoptional

If true, the import will generate a revision without updating the space primary content.

gitInfoobjectoptional

Optional metadata to store on the space about the Git provider

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/git/import' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "text",
    "ref": "text",
    "repoCacheID": "text",
    "repoTreeURL": "text",
    "repoCommitURL": "text",
    "repoProjectDirectory": "text",
    "timestamp": "2025-04-03T20:28:16.020Z",
    "force": true,
    "standalone": true,
    "gitInfo": {
      "provider": "github",
      "url": "text"
    }
  }'
No body

Operation to import the repository has been started.

Export the space content to a Git repository.

post
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Body
urlstringrequired

URL of the Git repository to export to. It can contain basic auth credentials.

refstringrequired

Git ref to push the commit to in the format "refs/heads/main"

commitMessagestringrequired

Message for the commit generated by the export

repoCacheIDstringoptional

Unique identifier to use to cache the Git repository across multiple operations.

repoTreeURLstringoptional

URL to use as a prefix for external file references.

repoCommitURLstringoptional

URL to use as a prefix for the commit URL.

repoProjectDirectorystringoptional

Path to a root directory for the project in the repository.

timestampstring · date-timeoptional

The timestamp of the event that triggered this export. It ensures that Git sync import and export operations are executed in the same order on GitBook and on the remote repository.

forcebooleanoptional
gitInfoobjectoptional

Optional metadata to store on the space about the Git provider

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/git/export' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "text",
    "ref": "text",
    "commitMessage": "text",
    "repoCacheID": "text",
    "repoTreeURL": "text",
    "repoCommitURL": "text",
    "repoProjectDirectory": "text",
    "timestamp": "2025-04-03T20:28:16.020Z",
    "force": true,
    "gitInfo": {
      "provider": "github",
      "url": "text"
    }
  }'
No body

Operation to export the space has been started.

Get metadata about the Git Sync provider currently set up on the space

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/git/info' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "repoName": "text",
  "installationProvider": "github",
  "integration": "text",
  "url": "text",
  "updatedAt": "2025-04-03T20:28:16.020Z"
}

The Git Sync info for the space

Invite to a space

post
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Body
roleone ofrequired

Role to set.

"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.

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/permissions' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "role": "admin",
    "teams": [
      "text"
    ]
  }'
No body

OK

Remove a team from a space

delete
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

teamIdstringrequired

The unique ID of the Team

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

The team has been removed from the space

Update a team's permission in a space

patch
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

teamIdstringrequired

The unique ID of the Team

Body
roleone ofoptional

The role of a member in an organization, null for guests

"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.

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/permissions/teams/{teamId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "role": "admin"
  }'
No body

Team permission was updated

Remove a user from a space

delete
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

userIdstringrequired

The unique ID of the User

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

The user has been removed from the space

Update a user's permission a space

patch
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

userIdstringrequired

The unique ID of the User

Body
roleone ofoptional

The role of a member in an organization, null for guests

"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.

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/permissions/users/{userId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "role": "admin"
  }'
No body

User permission was updated

Get the current primary content revision for a space

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Query parameters
metadataboolean · default: trueoptional

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean · default: trueoptional

If false is passed, content will not be computed

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "revision",
  "id": "text",
  "parents": [
    "text"
  ],
  "pages": [
    "[Circular Reference]"
  ],
  "files": [
    {
      "id": "text",
      "name": "text",
      "contentType": "text",
      "downloadURL": "text",
      "size": 1,
      "dimensions": {
        "width": 1,
        "height": 1
      },
      "git": {
        "oid": "text",
        "path": "text"
      }
    }
  ],
  "reusableContents": [
    {
      "id": "text",
      "title": "text",
      "document": "text",
      "git": {
        "oid": "text",
        "path": "text"
      }
    }
  ],
  "createdAt": "2025-04-03T20:28:16.020Z",
  "git": {
    "oid": "text",
    "message": "text",
    "createdByGitBook": true,
    "url": "text",
    "ref": "text"
  },
  "urls": {
    "app": "https://example.com",
    "published": "https://example.com",
    "public": "https://example.com"
  },
  "type": "edits"
}

OK

Import content in a space.

post
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Body
urlstring · urirequired

URL of the content to import.

sourcestring · enumrequired
Available options:
Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content/import' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com",
    "source": "website"
  }'
{
  "revision": "text",
  "importedResources": 1,
  "totalResources": 1
}

Content imported in a new revision

List all pages for the main revision content of a space

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Query parameters
metadataboolean · default: trueoptional

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean · default: trueoptional

If false is passed, content will not be computed

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content/pages' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "pages": [
    {
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "icon": "gear",
      "createdAt": "2025-04-03T20:28:16.020Z",
      "updatedAt": "2025-04-03T20:28:16.020Z",
      "markdown": "text",
      "kind": "sheet",
      "type": "document",
      "urls": {
        "app": "https://example.com"
      },
      "slug": "text",
      "path": "text",
      "description": "text",
      "documentId": "text",
      "pages": [
        "[Circular Reference]"
      ],
      "git": {
        "oid": "text",
        "path": "text"
      },
      "layout": {
        "cover": true,
        "coverSize": "hero",
        "title": true,
        "description": true,
        "tableOfContents": true,
        "outline": true,
        "pagination": true
      },
      "cover": {
        "ref": {
          "kind": "file",
          "file": "text"
        },
        "yPos": 1
      },
      "hidden": true,
      "noIndex": true,
      "noRobotsIndex": true,
      "computed": {
        "type": "builtin:openapi",
        "dependencies": {
          "spec": {
            "ref": {
              "kind": "openapi",
              "spec": "text"
            }
          }
        },
        "props": {
          "doc": "models"
        }
      },
      "computedSeed": "text"
    }
  ]
}

OK

List all files for the main revision content of a space

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

metadataboolean · default: trueoptional

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean · default: trueoptional

If false is passed, content will not be computed

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content/files' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "id": "text",
      "name": "text",
      "contentType": "text",
      "downloadURL": "text",
      "size": 1,
      "dimensions": {
        "width": 1,
        "height": 1
      },
      "git": {
        "oid": "text",
        "path": "text"
      }
    }
  ]
}

OK

Get a file by its ID in the main revision of a space

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

fileIdstringrequired

The unique id of the file

Query parameters
metadataboolean · default: trueoptional

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean · default: trueoptional

If false is passed, content will not be computed

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content/files/{fileId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "id": "text",
  "name": "text",
  "contentType": "text",
  "downloadURL": "text",
  "size": 1,
  "dimensions": {
    "width": 1,
    "height": 1
  },
  "git": {
    "oid": "text",
    "path": "text"
  }
}

OK

Get backlink locations for a file existing in a space.

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

fileIdstringrequired

The unique id of the file

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/spaces/{spaceId}/content/files/{fileId}/backlinks' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "kind": "file",
      "organization": {
        "object": "organization",
        "id": "text",
        "title": "text",
        "createdAt": "2025-04-03T20:28:16.020Z",
        "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-03T20:28:16.020Z",
          "hasPaymentFailed": true,
          "isScheduledToCancel": true
        },
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "logo": "https://example.com"
        },
        "trial": {
          "status": "notapplicable",
          "endDate": "2025-04-03T20:28:16.020Z",
          "decision": "downgrade"
        },
        "customHostname": "text",
        "blocked": {
          "reason": "security"
        },
        "internal_isOnNewTrial": true,
        "internal_billingMigration": {
          "deadline": "2025-04-03T20:28:16.020Z",
          "discountPercent": 1,
          "discountEndDate": "2025-04-03T20:28:16.020Z"
        },
        "permissions": {
          "admin": true,
          "createContent": true
        }
      },
      "space": {
        "object": "space",
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-04-03T20:28:16.020Z",
        "updatedAt": "2025-04-03T20:28:16.020Z",
        "deletedAt": "2025-04-03T20:28:16.020Z",
        "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-03T20:28:16.020Z"
        },
        "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": {
        "type": "revision",
        "revision": "[Circular Reference]"
      },
      "file": {
        "id": "text",
        "name": "text",
        "contentType": "text",
        "downloadURL": "text",
        "size": 1,
        "dimensions": {
          "width": 1,
          "height": 1
        },
        "git": {
          "oid": "text",
          "path": "text"
        }
      }
    }
  ]
}

OK

Get a page by its ID in the primary content.

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

pageIdstringrequired

The unique id of the page

Query parameters
formatstring · enumoptional

Output format for the content.

Available options:
metadataboolean · default: trueoptional

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean · default: trueoptional

If false is passed, content will not be computed

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content/page/{pageId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2025-04-03T20:28:16.020Z",
  "updatedAt": "2025-04-03T20:28:16.020Z",
  "markdown": "text",
  "kind": "sheet",
  "type": "document",
  "urls": {
    "app": "https://example.com"
  },
  "slug": "text",
  "path": "text",
  "description": "text",
  "documentId": "text",
  "pages": [
    "[Circular Reference]"
  ],
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "cover": true,
    "coverSize": "hero",
    "title": true,
    "description": true,
    "tableOfContents": true,
    "outline": true,
    "pagination": true
  },
  "cover": {
    "ref": {
      "kind": "file",
      "file": "text"
    },
    "yPos": 1
  },
  "hidden": true,
  "noIndex": true,
  "noRobotsIndex": true,
  "computed": {
    "type": "builtin:openapi",
    "dependencies": {
      "spec": {
        "ref": {
          "kind": "openapi",
          "spec": "text"
        }
      }
    },
    "props": {
      "doc": "models"
    }
  },
  "computedSeed": "text"
}

OK

List all links in a page

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

pageIdstringrequired

The unique id of the page

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}/content/page/{pageId}/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-03T20:28:16.020Z",
          "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-03T20:28:16.020Z",
            "hasPaymentFailed": true,
            "isScheduledToCancel": true
          },
          "urls": {
            "location": "https://example.com",
            "app": "https://example.com",
            "logo": "https://example.com"
          },
          "trial": {
            "status": "notapplicable",
            "endDate": "2025-04-03T20:28:16.020Z",
            "decision": "downgrade"
          },
          "customHostname": "text",
          "blocked": {
            "reason": "security"
          },
          "internal_isOnNewTrial": true,
          "internal_billingMigration": {
            "deadline": "2025-04-03T20:28:16.020Z",
            "discountPercent": 1,
            "discountEndDate": "2025-04-03T20:28:16.020Z"
          },
          "permissions": {
            "admin": true,
            "createContent": true
          }
        },
        "space": {
          "object": "space",
          "id": "text",
          "title": "text",
          "emoji": "🎉",
          "visibility": "public",
          "createdAt": "2025-04-03T20:28:16.020Z",
          "updatedAt": "2025-04-03T20:28:16.020Z",
          "deletedAt": "2025-04-03T20:28:16.020Z",
          "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-03T20:28:16.020Z"
          },
          "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-03T20:28:16.020Z",
            "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-03T20:28:16.020Z",
              "hasPaymentFailed": true,
              "isScheduledToCancel": true
            },
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "logo": "https://example.com"
            },
            "trial": {
              "status": "notapplicable",
              "endDate": "2025-04-03T20:28:16.020Z",
              "decision": "downgrade"
            },
            "customHostname": "text",
            "blocked": {
              "reason": "security"
            },
            "internal_isOnNewTrial": true,
            "internal_billingMigration": {
              "deadline": "2025-04-03T20:28:16.020Z",
              "discountPercent": 1,
              "discountEndDate": "2025-04-03T20:28:16.020Z"
            },
            "permissions": {
              "admin": true,
              "createContent": true
            }
          },
          "space": {
            "object": "space",
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-04-03T20:28:16.020Z",
            "updatedAt": "2025-04-03T20:28:16.020Z",
            "deletedAt": "2025-04-03T20:28:16.020Z",
            "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-03T20:28:16.020Z"
            },
            "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

Get backlink locations for a page existing in a space.

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

pageIdstringrequired

The unique id of the page

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/spaces/{spaceId}/content/page/{pageId}/backlinks' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "kind": "file",
      "organization": {
        "object": "organization",
        "id": "text",
        "title": "text",
        "createdAt": "2025-04-03T20:28:16.020Z",
        "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-03T20:28:16.020Z",
          "hasPaymentFailed": true,
          "isScheduledToCancel": true
        },
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "logo": "https://example.com"
        },
        "trial": {
          "status": "notapplicable",
          "endDate": "2025-04-03T20:28:16.020Z",
          "decision": "downgrade"
        },
        "customHostname": "text",
        "blocked": {
          "reason": "security"
        },
        "internal_isOnNewTrial": true,
        "internal_billingMigration": {
          "deadline": "2025-04-03T20:28:16.020Z",
          "discountPercent": 1,
          "discountEndDate": "2025-04-03T20:28:16.020Z"
        },
        "permissions": {
          "admin": true,
          "createContent": true
        }
      },
      "space": {
        "object": "space",
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-04-03T20:28:16.020Z",
        "updatedAt": "2025-04-03T20:28:16.020Z",
        "deletedAt": "2025-04-03T20:28:16.020Z",
        "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-03T20:28:16.020Z"
        },
        "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": {
        "type": "revision",
        "revision": "[Circular Reference]"
      },
      "file": {
        "id": "text",
        "name": "text",
        "contentType": "text",
        "downloadURL": "text",
        "size": 1,
        "dimensions": {
          "width": 1,
          "height": 1
        },
        "git": {
          "oid": "text",
          "path": "text"
        }
      }
    }
  ]
}

OK

Import external content into a page by its ID.

post
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

pageIdstringrequired

The unique id of the page

Body
urlstring · urirequired

URL of the content to import.

sourcestring · enumrequired
Available options:
Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content/page/{pageId}/import' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com",
    "source": "website"
  }'
{
  "revision": "text",
  "importedResources": 1,
  "totalResources": 1
}

Content imported in a new revision

Get a page by its path in the primary content.

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

pagePathstringrequired

The path of the page in the revision.

Query parameters
formatstring · enumoptional

Output format for the content.

Available options:
metadataboolean · default: trueoptional

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean · default: trueoptional

If false is passed, content will not be computed

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content/path/{pagePath}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2025-04-03T20:28:16.020Z",
  "updatedAt": "2025-04-03T20:28:16.020Z",
  "markdown": "text",
  "kind": "sheet",
  "type": "document",
  "urls": {
    "app": "https://example.com"
  },
  "slug": "text",
  "path": "text",
  "description": "text",
  "documentId": "text",
  "pages": [
    "[Circular Reference]"
  ],
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "cover": true,
    "coverSize": "hero",
    "title": true,
    "description": true,
    "tableOfContents": true,
    "outline": true,
    "pagination": true
  },
  "cover": {
    "ref": {
      "kind": "file",
      "file": "text"
    },
    "yPos": 1
  },
  "hidden": true,
  "noIndex": true,
  "noRobotsIndex": true,
  "computed": {
    "type": "builtin:openapi",
    "dependencies": {
      "spec": {
        "ref": {
          "kind": "openapi",
          "spec": "text"
        }
      }
    },
    "props": {
      "doc": "models"
    }
  },
  "computedSeed": "text"
}

OK

Get a reusable content by its ID in the main revision of a space

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

reusableContentIdstringrequired

The unique id of the reusable content

Query parameters
metadataboolean · default: trueoptional

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean · default: trueoptional

If false is passed, content will not be computed

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/content/reusable-contents/{reusableContentId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "id": "text",
  "title": "text",
  "document": "text",
  "git": {
    "oid": "text",
    "path": "text"
  }
}

OK

Get a document by its ID in a space.

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

documentIdstringrequired

ID of the document in the space

Query parameters
schemastring · enumoptional

Version of the schema used for the document.

Available options:
Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/documents/{documentId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "document",
  "data": {
    "schemaVersion": 1,
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "nodes": [
    {
      "object": "block",
      "type": "paragraph",
      "key": "text",
      "nodes": [
        {
          "object": "inline",
          "type": "link",
          "key": "text",
          "nodes": [
            {
              "object": "text",
              "key": "text",
              "leaves": [
                {
                  "object": "leaf",
                  "text": "text",
                  "marks": [
                    {
                      "object": "mark",
                      "type": "bold"
                    }
                  ]
                }
              ]
            }
          ],
          "data": {
            "ref": {
              "kind": "file",
              "file": "text"
            }
          },
          "isVoid": false
        }
      ],
      "isVoid": false,
      "data": {}
    }
  ]
}

Document

List change requests for a space.

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 · enum · default: "open"optional

If defined, only change requests matching this status will be returned.

Available options:
contributorstringoptional

If defined, only change requests with contributions from this user will be returned.

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "change-request",
      "id": "text",
      "number": 1,
      "status": "draft",
      "subject": "text",
      "createdBy": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      },
      "createdAt": "2025-04-03T20:28:16.020Z",
      "updatedAt": "2025-04-03T20:28:16.020Z",
      "revision": "text",
      "revisionInitial": "text",
      "revisionMergedAncestor": "text",
      "revisionMerged": "text",
      "comments": 1,
      "outdated": true,
      "urls": {
        "app": "https://example.com",
        "location": "https://example.com"
      }
    }
  ]
}

List of the space's change requests

Create a new change request for a space.

post
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Body
subjectstringoptional

Subject of the change-request

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "subject": "text"
  }'
{
  "object": "change-request",
  "id": "text",
  "number": 1,
  "status": "draft",
  "subject": "text",
  "createdBy": {
    "object": "user",
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "urls": {
      "location": "https://example.com"
    }
  },
  "createdAt": "2025-04-03T20:28:16.020Z",
  "updatedAt": "2025-04-03T20:28:16.020Z",
  "revision": "text",
  "revisionInitial": "text",
  "revisionMergedAncestor": "text",
  "revisionMerged": "text",
  "comments": 1,
  "outdated": true,
  "urls": {
    "app": "https://example.com",
    "location": "https://example.com"
  }
}

Change Request Created

Get all requested reviewers for a change request.

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

changeRequestIdstringrequired

The unique ID of the change request or its number identifier in the space

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/spaces/{spaceId}/change-requests/{changeRequestId}/requested-reviewers' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "change-request-requested-reviewer",
      "revision": "text",
      "requestedBy": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      },
      "createdAt": "2025-04-03T20:28:16.020Z",
      "kind": "user",
      "user": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      }
    }
  ]
}

A list of requested reviewers

Request reviewers on a change request. Note that requesting a review from teams is not yet supported.

post
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

changeRequestIdstringrequired

The unique ID of the change request or its number identifier in the space

Body
usersstring[]required

An array of user ids that will be requested.

subjectstringoptional

Optionally, update the subject of the change request when requesting reviewers.

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/requested-reviewers' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "users": [
      "text"
    ],
    "subject": "text"
  }'
{
  "users": [
    {
      "object": "change-request-requested-reviewer",
      "revision": "text",
      "requestedBy": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      },
      "createdAt": "2025-04-03T20:28:16.020Z",
      "kind": "user",
      "user": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      }
    }
  ]
}

The requests have successfully been sent.

Get a comment in a space.

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

commentIdstringrequired

The unique id of the comment

Query parameters
formatstring · enumoptional

Output format for the content.

Available options:
Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/comments/{commentId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "comment",
  "id": "text",
  "postedBy": {
    "object": "user",
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "urls": {
      "location": "https://example.com"
    }
  },
  "postedAt": "2025-04-03T20:28:16.020Z",
  "editedAt": "2025-04-03T20:28:16.020Z",
  "reactions": [
    {
      "emoji": "text",
      "count": 1,
      "users": [
        {
          "user": {
            "object": "user",
            "id": "text",
            "displayName": "text",
            "email": "text",
            "photoURL": "text",
            "urls": {
              "location": "https://example.com"
            }
          },
          "reactedAt": "2025-04-03T20:28:16.020Z"
        }
      ]
    }
  ],
  "replies": 1,
  "body": {
    "markdown": "text"
  },
  "target": {
    "node": {
      "id": "text",
      "preview": "text"
    },
    "changeRequest": "text",
    "review": "text",
    "page": {
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "icon": "gear",
      "createdAt": "2025-04-03T20:28:16.020Z",
      "updatedAt": "2025-04-03T20:28:16.020Z",
      "path": "text",
      "outdated": true
    },
    "space": "text",
    "revision": "text"
  },
  "urls": {
    "location": "https://example.com"
  },
  "status": "resolved",
  "resolvedAt": "2025-04-03T20:28:16.020Z",
  "resolvedBy": {
    "object": "user",
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "urls": {
      "location": "https://example.com"
    }
  }
}

The returned comment.

Update a comment in a space.

put
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

commentIdstringrequired

The unique id of the comment

Body
resolvedbooleanoptional

Whether the comment is resolved or not.

bodyone ofoptional

Content of the comment.

addedReactionsstring[]optional

Reactions to add to the comment.

removedReactionsstring[]optional

Reactions to remove from the comment.

Responses
curl -L \
  --request PUT \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/comments/{commentId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "resolved": true,
    "body": {
      "markdown": "text"
    },
    "addedReactions": [
      "text"
    ],
    "removedReactions": [
      "text"
    ]
  }'
{
  "object": "comment",
  "id": "text",
  "postedBy": {
    "object": "user",
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "urls": {
      "location": "https://example.com"
    }
  },
  "postedAt": "2025-04-03T20:28:16.020Z",
  "editedAt": "2025-04-03T20:28:16.020Z",
  "reactions": [
    {
      "emoji": "text",
      "count": 1,
      "users": [
        {
          "user": {
            "object": "user",
            "id": "text",
            "displayName": "text",
            "email": "text",
            "photoURL": "text",
            "urls": {
              "location": "https://example.com"
            }
          },
          "reactedAt": "2025-04-03T20:28:16.020Z"
        }
      ]
    }
  ],
  "replies": 1,
  "body": {
    "markdown": "text"
  },
  "target": {
    "node": {
      "id": "text",
      "preview": "text"
    },
    "changeRequest": "text",
    "review": "text",
    "page": {
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "icon": "gear",
      "createdAt": "2025-04-03T20:28:16.020Z",
      "updatedAt": "2025-04-03T20:28:16.020Z",
      "path": "text",
      "outdated": true
    },
    "space": "text",
    "revision": "text"
  },
  "urls": {
    "location": "https://example.com"
  },
  "status": "resolved",
  "resolvedAt": "2025-04-03T20:28:16.020Z",
  "resolvedBy": {
    "object": "user",
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "urls": {
      "location": "https://example.com"
    }
  }
}

The comment was updated.

Delete a comment in a space.

delete
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

commentIdstringrequired

The unique id of the comment

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

The comment has been deleted.

List the scripts to embed in published content for a space.

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/integration-scripts' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
[
  {
    "script": "https://example.com",
    "contentSecurityPolicy": "text",
    "cookies": true
  }
]

OK

Get the values of the custom fields set on a space

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/custom-fields' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
[
  {
    "customField": {
      "id": "text",
      "name": "text",
      "title": "text",
      "description": "text",
      "type": "text",
      "placeholder": "text",
      "options": [
        "text"
      ],
      "createdAt": "2025-04-03T20:28:16.020Z",
      "updatedAt": "2025-04-03T20:28:16.020Z",
      "urls": {
        "location": "https://example.com"
      }
    },
    "value": "text"
  }
]

OK

Update the custom fields in a space

patch
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Body
valuesobjectrequired

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/custom-fields' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "values": {
      "ANY_ADDITIONAL_PROPERTY": {
        "value": "text"
      }
    }
  }'
No body

Custom fields updated

Generate a URL to export the content of the space as a PDF.

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Query parameters
onlybooleanoptional

Generate a PDF only for the provided page.

pagestringoptional

ID of a specific page to generate a PDF for.

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/pdf' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "url": "https://example.com"
}

URL of the PDF

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-03T20:28:16.020Z",
          "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-03T20:28:16.020Z",
            "hasPaymentFailed": true,
            "isScheduledToCancel": true
          },
          "urls": {
            "location": "https://example.com",
            "app": "https://example.com",
            "logo": "https://example.com"
          },
          "trial": {
            "status": "notapplicable",
            "endDate": "2025-04-03T20:28:16.020Z",
            "decision": "downgrade"
          },
          "customHostname": "text",
          "blocked": {
            "reason": "security"
          },
          "internal_isOnNewTrial": true,
          "internal_billingMigration": {
            "deadline": "2025-04-03T20:28:16.020Z",
            "discountPercent": 1,
            "discountEndDate": "2025-04-03T20:28:16.020Z"
          },
          "permissions": {
            "admin": true,
            "createContent": true
          }
        },
        "space": {
          "object": "space",
          "id": "text",
          "title": "text",
          "emoji": "🎉",
          "visibility": "public",
          "createdAt": "2025-04-03T20:28:16.020Z",
          "updatedAt": "2025-04-03T20:28:16.020Z",
          "deletedAt": "2025-04-03T20:28:16.020Z",
          "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-03T20:28:16.020Z"
          },
          "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-03T20:28:16.020Z",
            "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-03T20:28:16.020Z",
              "hasPaymentFailed": true,
              "isScheduledToCancel": true
            },
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "logo": "https://example.com"
            },
            "trial": {
              "status": "notapplicable",
              "endDate": "2025-04-03T20:28:16.020Z",
              "decision": "downgrade"
            },
            "customHostname": "text",
            "blocked": {
              "reason": "security"
            },
            "internal_isOnNewTrial": true,
            "internal_billingMigration": {
              "deadline": "2025-04-03T20:28:16.020Z",
              "discountPercent": 1,
              "discountEndDate": "2025-04-03T20:28:16.020Z"
            },
            "permissions": {
              "admin": true,
              "createContent": true
            }
          },
          "space": {
            "object": "space",
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-04-03T20:28:16.020Z",
            "updatedAt": "2025-04-03T20:28:16.020Z",
            "deletedAt": "2025-04-03T20:28:16.020Z",
            "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-03T20:28:16.020Z"
            },
            "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 organization spaces

get

Lists spaces for the specified organization.

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-03T20:28:16.020Z",
      "updatedAt": "2025-04-03T20:28:16.020Z",
      "deletedAt": "2025-04-03T20:28:16.020Z",
      "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-03T20:28:16.020Z"
      },
      "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 an organization 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": "🎉",
    "private": true,
    "parent": "text"
  }'
{
  "object": "space",
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "visibility": "public",
  "createdAt": "2025-04-03T20:28:16.020Z",
  "updatedAt": "2025-04-03T20:28:16.020Z",
  "deletedAt": "2025-04-03T20:28:16.020Z",
  "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-03T20:28:16.020Z"
  },
  "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

List integrations available to an organization.

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

searchstringoptional

A search string to filter integrations by name

categorystring · enumoptional

Filter the integrations by category

Available options:
blockDomainstring · max: 100optional

Filter the integrations by block's domains

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

If true, returns only integrations with blocks. If false, returns only integrations without blocks.

contentSourcesbooleanoptional

If true, returns only integrations with contentSources. If false, returns only integrations without contentSources.

ownerstringoptional

If defined, only list integrations owned by the given organization.

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/integrations' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "integration",
      "name": "text",
      "version": 1,
      "title": "text",
      "description": "text",
      "summary": "text",
      "previewImages": [
        "text"
      ],
      "target": "all",
      "verified": true,
      "visibility": "public",
      "scopes": [
        "space:views:read"
      ],
      "categories": [
        "analytics"
      ],
      "blocks": [
        {
          "id": "text",
          "title": "text",
          "description": "text",
          "icon": "text",
          "urlUnfurl": [
            "text"
          ],
          "markdown": {
            "codeblock": "text",
            "body": "text"
          }
        }
      ],
      "contentSources": [
        {
          "id": "text",
          "title": "text",
          "description": "text",
          "icon": "text",
          "configuration": {
            "componentId": "text"
          }
        }
      ],
      "configurations": {
        "account": {
          "properties": {
            "ANY_ADDITIONAL_PROPERTY": {
              "title": "text",
              "description": "text",
              "type": "string",
              "default": "text",
              "completion_url": "text",
              "enum": [
                "text"
              ]
            }
          },
          "required": [
            "text"
          ]
        },
        "space": {
          "properties": {
            "ANY_ADDITIONAL_PROPERTY": {
              "title": "text",
              "description": "text",
              "type": "string",
              "default": "text",
              "completion_url": "text",
              "enum": [
                "text"
              ]
            }
          },
          "required": [
            "text"
          ]
        },
        "site": {
          "properties": {
            "ANY_ADDITIONAL_PROPERTY": {
              "title": "text",
              "description": "text",
              "type": "string",
              "default": "text",
              "completion_url": "text",
              "enum": [
                "text"
              ]
            }
          },
          "required": [
            "text"
          ]
        }
      },
      "externalLinks": [
        {
          "url": "https://example.com",
          "label": "text"
        }
      ],
      "owner": {
        "object": "organization",
        "id": "text",
        "title": "text",
        "createdAt": "2025-04-03T20:28:16.020Z",
        "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-03T20:28:16.020Z",
          "hasPaymentFailed": true,
          "isScheduledToCancel": true
        },
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "logo": "https://example.com"
        },
        "trial": {
          "status": "notapplicable",
          "endDate": "2025-04-03T20:28:16.020Z",
          "decision": "downgrade"
        },
        "customHostname": "text",
        "blocked": {
          "reason": "security"
        },
        "internal_isOnNewTrial": true,
        "internal_billingMigration": {
          "deadline": "2025-04-03T20:28:16.020Z",
          "discountPercent": 1,
          "discountEndDate": "2025-04-03T20:28:16.020Z"
        },
        "permissions": {
          "admin": true,
          "createContent": true
        }
      },
      "urls": {
        "location": "https://example.com",
        "icon": "https://example.com",
        "app": "https://example.com",
        "assets": "https://example.com",
        "publicEndpoint": "https://example.com"
      },
      "permissions": {
        "admin": true,
        "install": true
      },
      "contentSecurityPolicy": "text"
    }
  ]
}

List of integrations.

List installations of integrations in an organization.

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

searchstringoptional

A search string to filter integrations by name

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/installations' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "installation": {
        "id": "text",
        "status": "active",
        "space_selection": "all",
        "site_selection": "all",
        "spaces": 1,
        "configuration": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "createdAt": "2025-04-03T20:28:16.020Z",
        "updatedAt": "2025-04-03T20:28:16.020Z",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "publicEndpoint": "https://example.com"
        },
        "externalIds": [
          "text"
        ],
        "target": {
          "organization": "text"
        }
      },
      "integration": {
        "object": "integration",
        "name": "text",
        "version": 1,
        "title": "text",
        "description": "text",
        "summary": "text",
        "previewImages": [
          "text"
        ],
        "target": "all",
        "verified": true,
        "visibility": "public",
        "scopes": [
          "space:views:read"
        ],
        "categories": [
          "analytics"
        ],
        "blocks": [
          {
            "id": "text",
            "title": "text",
            "description": "text",
            "icon": "text",
            "urlUnfurl": [
              "text"
            ],
            "markdown": {
              "codeblock": "text",
              "body": "text"
            }
          }
        ],
        "contentSources": [
          {
            "id": "text",
            "title": "text",
            "description": "text",
            "icon": "text",
            "configuration": {
              "componentId": "text"
            }
          }
        ],
        "configurations": {
          "account": {
            "properties": {
              "ANY_ADDITIONAL_PROPERTY": {
                "title": "text",
                "description": "text",
                "type": "string",
                "default": "text",
                "completion_url": "text",
                "enum": [
                  "text"
                ]
              }
            },
            "required": [
              "text"
            ]
          },
          "space": {
            "properties": {
              "ANY_ADDITIONAL_PROPERTY": {
                "title": "text",
                "description": "text",
                "type": "string",
                "default": "text",
                "completion_url": "text",
                "enum": [
                  "text"
                ]
              }
            },
            "required": [
              "text"
            ]
          },
          "site": {
            "properties": {
              "ANY_ADDITIONAL_PROPERTY": {
                "title": "text",
                "description": "text",
                "type": "string",
                "default": "text",
                "completion_url": "text",
                "enum": [
                  "text"
                ]
              }
            },
            "required": [
              "text"
            ]
          }
        },
        "externalLinks": [
          {
            "url": "https://example.com",
            "label": "text"
          }
        ],
        "owner": {
          "object": "organization",
          "id": "text",
          "title": "text",
          "createdAt": "2025-04-03T20:28:16.020Z",
          "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-03T20:28:16.020Z",
            "hasPaymentFailed": true,
            "isScheduledToCancel": true
          },
          "urls": {
            "location": "https://example.com",
            "app": "https://example.com",
            "logo": "https://example.com"
          },
          "trial": {
            "status": "notapplicable",
            "endDate": "2025-04-03T20:28:16.020Z",
            "decision": "downgrade"
          },
          "customHostname": "text",
          "blocked": {
            "reason": "security"
          },
          "internal_isOnNewTrial": true,
          "internal_billingMigration": {
            "deadline": "2025-04-03T20:28:16.020Z",
            "discountPercent": 1,
            "discountEndDate": "2025-04-03T20:28:16.020Z"
          },
          "permissions": {
            "admin": true,
            "createContent": true
          }
        },
        "urls": {
          "location": "https://example.com",
          "icon": "https://example.com",
          "app": "https://example.com",
          "assets": "https://example.com",
          "publicEndpoint": "https://example.com"
        },
        "permissions": {
          "admin": true,
          "install": true
        },
        "contentSecurityPolicy": "text"
      }
    }
  ]
}

List of integrations with the associated installations.

Was this helpful?