Revisions

Revisions in GitBook are the entity for updates made to content.

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

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

computedboolean

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-02-15T12:22:36.431Z",
  "git": {
    "oid": "text",
    "message": "text",
    "createdByGitBook": true,
    "url": "text",
    "ref": "text"
  },
  "object": "revision",
  "pages": [
    {
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "icon": "gear",
      "createdAt": "2025-02-15T12:22:36.431Z",
      "updatedAt": "2025-02-15T12:22:36.431Z",
      "markdown": "text",
      "description": "text",
      "git": {
        "oid": "text",
        "path": "text"
      },
      "layout": {
        "coverSize": "hero",
        "cover": true,
        "title": true,
        "description": true,
        "tableOfContents": true,
        "outline": true,
        "pagination": true
      },
      "cover": {
        "ref": {
          "file": "text",
          "kind": "file"
        },
        "yPos": 1
      },
      "kind": "sheet",
      "type": "document",
      "slug": "text",
      "path": "text",
      "documentId": "text",
      "hidden": false,
      "noIndex": false,
      "noRobotsIndex": false,
      "computed": "[Circular Reference]",
      "urls": {
        "app": "https://example.com"
      },
      "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"
      }
    }
  ],
  "parents": [
    "text"
  ],
  "urls": {
    "app": "https://example.com",
    "published": "https://example.com",
    "public": "https://example.com"
  },
  "type": "edits"
}

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

formatenum

Output format for the content.

Options: document, markdown

metadataboolean

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

computedboolean

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-02-15T12:22:36.431Z",
  "updatedAt": "2025-02-15T12:22:36.431Z",
  "markdown": "text",
  "description": "text",
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "coverSize": "hero",
    "cover": true,
    "title": true,
    "description": true,
    "tableOfContents": true,
    "outline": true,
    "pagination": true
  },
  "cover": {
    "ref": {
      "file": "text",
      "kind": "file"
    },
    "yPos": 1
  },
  "kind": "sheet",
  "type": "document",
  "slug": "text",
  "path": "text",
  "documentId": "text",
  "hidden": false,
  "noIndex": false,
  "noRobotsIndex": false,
  "computed": "[Circular Reference]",
  "urls": {
    "app": "https://example.com"
  },
  "pages": "[Circular Reference]"
}

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

formatenum

Output format for the content.

Options: document, markdown

metadataboolean

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

computedboolean

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-02-15T12:22:36.431Z",
  "updatedAt": "2025-02-15T12:22:36.431Z",
  "markdown": "text",
  "description": "text",
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "coverSize": "hero",
    "cover": true,
    "title": true,
    "description": true,
    "tableOfContents": true,
    "outline": true,
    "pagination": true
  },
  "cover": {
    "ref": {
      "file": "text",
      "kind": "file"
    },
    "yPos": 1
  },
  "kind": "sheet",
  "type": "document",
  "slug": "text",
  "path": "text",
  "documentId": "text",
  "hidden": false,
  "noIndex": false,
  "noRobotsIndex": false,
  "computed": "[Circular Reference]",
  "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

The number of results per page

metadataboolean

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

computedboolean

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