Revisions

Review and manage content revisions.

Get a specific revision in a space

get

/spaces/{spaceId}/revisions/{revisionId}

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

revisionIdstringrequired

The unique id of the revision

Query parameters

metadataboolean · default: true

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

computedboolean · default: true

If false is passed, content will not be computed

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/revisions/{revisionId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

200

{
  "id": "text",
  "createdAt": "2025-03-09T02:44:49.181Z",
  "git": {
    "oid": "text",
    "message": "text",
    "createdByGitBook": true,
    "url": "text",
    "ref": "text"
  },
  "object": "revision",
  "parents": [
    "text"
  ],
  "pages": "[Circular Reference]",
  "files": [
    {
      "id": "text",
      "name": "text",
      "contentType": "text",
      "downloadURL": "text",
      "size": 1,
      "git": {
        "oid": "text",
        "path": "text"
      },
      "dimensions": {
        "width": 1,
        "height": 1
      }
    }
  ],
  "reusableContents": [
    {
      "id": "text",
      "title": "text",
      "document": "text",
      "git": {
        "oid": "text",
        "path": "text"
      }
    }
  ],
  "urls": {
    "app": "https://example.com",
    "published": "https://example.com",
    "public": "https://example.com"
  },
  "type": "edits"
}

OK

Return the semantic changes between a revision and its parent.

get

/spaces/{spaceId}/revisions/{revisionId}/changes

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

revisionIdstringrequired

The unique id of the revision

Query parameters

metadataboolean · default: true

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

computedboolean · default: true

If false is passed, content will not be computed

limitnumber · default: 10

Limit the number of changes returned

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/revisions/{revisionId}/changes' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

200

{
  "more": 1,
  "changes": [
    {
      "page": {
        "id": "text",
        "type": "document",
        "title": "text",
        "path": "text"
      },
      "type": "page_created"
    }
  ]
}

OK

Get a file in a revision by its ID

get

/spaces/{spaceId}/revisions/{revisionId}/files/{fileId}

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

revisionIdstringrequired

The unique id of the revision

fileIdstringrequired

The unique id of the file

Query parameters

metadataboolean · default: true

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

computedboolean · default: true

If false is passed, content will not be computed

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/revisions/{revisionId}/files/{fileId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

200

{
  "id": "text",
  "name": "text",
  "contentType": "text",
  "downloadURL": "text",
  "size": 1,
  "git": {
    "oid": "text",
    "path": "text"
  },
  "dimensions": {
    "width": 1,
    "height": 1
  }
}

OK

Get a page by its ID in a revision.

get

/spaces/{spaceId}/revisions/{revisionId}/page/{pageId}

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

revisionIdstringrequired

The unique id of the revision

pageIdstringrequired

The unique id of the page

Query parameters

formatstring · enum

Output format for the content.

Options: document, markdown

metadataboolean · default: true

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

computedboolean · default: true

If false is passed, content will not be computed

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/revisions/{revisionId}/page/{pageId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

200

{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2025-03-09T02:44:49.181Z",
  "updatedAt": "2025-03-09T02:44:49.181Z",
  "markdown": "text",
  "slug": "text",
  "path": "text",
  "description": "text",
  "documentId": "text",
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "cover": true,
    "coverSize": "hero",
    "title": true,
    "description": true,
    "tableOfContents": true,
    "outline": true,
    "pagination": true
  },
  "cover": {
    "ref": {
      "file": "text",
      "kind": "file"
    },
    "yPos": 1
  },
  "hidden": false,
  "noIndex": false,
  "noRobotsIndex": false,
  "computed": "[Circular Reference]",
  "kind": "sheet",
  "type": "document",
  "urls": {
    "app": "https://example.com"
  },
  "pages": "[Circular Reference]"
}

OK

Get reusable content in a revision by its ID

get

/spaces/{spaceId}/revisions/{revisionId}/reusable-contents/{reusableContentId}

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

revisionIdstringrequired

The unique id of the revision

reusableContentIdstringrequired

The unique id of the reusable content

Query parameters

metadataboolean · default: true

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

computedboolean · default: true

If false is passed, content will not be computed

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/revisions/{revisionId}/reusable-contents/{reusableContentId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

200

{
  "id": "text",
  "title": "text",
  "document": "text",
  "git": {
    "oid": "text",
    "path": "text"
  }
}

OK

Get a page by its path in a revision.

get

/spaces/{spaceId}/revisions/{revisionId}/path/{pagePath}

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

revisionIdstringrequired

The unique id of the revision

pagePathstringrequired

The path of the page in the revision.

Query parameters

formatstring · enum

Output format for the content.

Options: document, markdown

metadataboolean · default: true

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

computedboolean · default: true

If false is passed, content will not be computed

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/revisions/{revisionId}/path/{pagePath}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

200

{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2025-03-09T02:44:49.181Z",
  "updatedAt": "2025-03-09T02:44:49.181Z",
  "markdown": "text",
  "slug": "text",
  "path": "text",
  "description": "text",
  "documentId": "text",
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "cover": true,
    "coverSize": "hero",
    "title": true,
    "description": true,
    "tableOfContents": true,
    "outline": true,
    "pagination": true
  },
  "cover": {
    "ref": {
      "file": "text",
      "kind": "file"
    },
    "yPos": 1
  },
  "hidden": false,
  "noIndex": false,
  "noRobotsIndex": false,
  "computed": "[Circular Reference]",
  "kind": "sheet",
  "type": "document",
  "urls": {
    "app": "https://example.com"
  },
  "pages": "[Circular Reference]"
}

OK

List all pages in a revision

get

/spaces/{spaceId}/revisions/{revisionId}/pages

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

revisionIdstringrequired

The unique id of the revision

Query parameters

metadataboolean · default: true

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

computedboolean · default: true

If false is passed, content will not be computed

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/revisions/{revisionId}/pages' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

200

{
  "pages": [
    {
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "icon": "gear",
      "createdAt": "2025-03-09T02:44:49.181Z",
      "updatedAt": "2025-03-09T02:44:49.181Z",
      "markdown": "text",
      "slug": "text",
      "path": "text",
      "description": "text",
      "documentId": "text",
      "git": {
        "oid": "text",
        "path": "text"
      },
      "layout": {
        "cover": true,
        "coverSize": "hero",
        "title": true,
        "description": true,
        "tableOfContents": true,
        "outline": true,
        "pagination": true
      },
      "cover": {
        "ref": {
          "file": "text",
          "kind": "file"
        },
        "yPos": 1
      },
      "hidden": false,
      "noIndex": false,
      "noRobotsIndex": false,
      "computed": "[Circular Reference]",
      "kind": "sheet",
      "type": "document",
      "urls": {
        "app": "https://example.com"
      },
      "pages": "[Circular Reference]"
    }
  ]
}

OK

List all files in a revision

get

/spaces/{spaceId}/revisions/{revisionId}/files

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

revisionIdstringrequired

The unique id of the revision

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

metadataboolean · default: true

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

computedboolean · default: true

If false is passed, content will not be computed

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/revisions/{revisionId}/files' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

200

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "name": "text",
      "contentType": "text",
      "downloadURL": "text",
      "size": 1,
      "git": {
        "oid": "text",
        "path": "text"
      },
      "dimensions": {
        "width": 1,
        "height": 1
      }
    }
  ]
}

OK