Change Requests

A change request in GitBook is the entity of a revision to a space in progress.

List all change requests

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

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

Default: openPossible values:

creatorstringOptional

If defined, only change requests created by this user will be returned.

contributorstringOptional

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

requestedReviewerstringOptional

If defined, only change requests with a requested reviewer for this user will be returned.

conversationsIssuesClusterstringOptional

If defined, only change requests associated with this conversations issues cluster will be returned.

orderBystring · enumOptional

The field to sort change requests by. Defaults to 'updatedAt'.

Default: updatedAtPossible values:

Responses

200

List of the space's change requests

application/json

get

/spaces/{spaceId}/change-requests

HTTPcURLJavaScriptPython

GET /v1/spaces/{spaceId}/change-requests HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

List of the space's change requests

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "change-request",
      "id": "text",
      "number": 1,
      "status": "draft",
      "subject": "text",
      "description": {
        "object": "document",
        "data": {
          "schemaVersion": 1,
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "nodes": [
          "[Circular Reference]"
        ],
        "meta": {
          "token": "text"
        }
      },
      "createdBy": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      },
      "createdAt": "2025-12-27T04:30:12.310Z",
      "updatedAt": "2025-12-27T04:30:12.310Z",
      "space": "text",
      "revision": "text",
      "revisionInitial": "text",
      "revisionMergedAncestor": "text",
      "revisionMerged": "text",
      "comments": 1,
      "outdated": true,
      "conversationsIssuesCluster": "text",
      "urls": {
        "app": "https://example.com",
        "location": "https://example.com"
      }
    }
  ]
}

Create a change request

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

Body

application/json

subjectstringOptional

Subject of the change-request

Other propertiesanyOptional

Responses

201

Change Request Created

application/json

post

/spaces/{spaceId}/change-requests

HTTPcURLJavaScriptPython

POST /v1/spaces/{spaceId}/change-requests HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 178

{
  "subject": "text",
  "template": {
    "id": "text",
    "params": {
      "contentRefs": {
        "ANY_ADDITIONAL_PROPERTY": {
          "kind": "file",
          "file": "text",
          "space": "text"
        }
      }
    }
  },
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

201

Change Request Created

{
  "object": "change-request",
  "id": "text",
  "number": 1,
  "status": "draft",
  "subject": "text",
  "description": {
    "object": "document",
    "data": {
      "schemaVersion": 1,
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "nodes": [
      {
        "object": "block",
        "type": "paragraph",
        "key": "text",
        "nodes": [
          "[Circular Reference]"
        ],
        "isVoid": false,
        "data": {
          "align": "start"
        }
      }
    ],
    "meta": {
      "token": "text"
    }
  },
  "createdBy": {
    "object": "user",
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "urls": {
      "location": "https://example.com"
    }
  },
  "createdAt": "2025-12-27T04:30:12.310Z",
  "updatedAt": "2025-12-27T04:30:12.310Z",
  "space": "text",
  "revision": "text",
  "revisionInitial": "text",
  "revisionMergedAncestor": "text",
  "revisionMerged": "text",
  "comments": 1,
  "outdated": true,
  "conversationsIssuesCluster": "text",
  "urls": {
    "app": "https://example.com",
    "location": "https://example.com"
  }
}

Merge a change request

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

changeRequestIdstringRequired

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

Responses

200

OK

application/json

post

/spaces/{spaceId}/change-requests/{changeRequestId}/merge

HTTPcURLJavaScriptPython

POST /v1/spaces/{spaceId}/change-requests/{changeRequestId}/merge HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "revision": "text",
  "result": "merge"
}

Pull primary content into the change request

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

changeRequestIdstringRequired

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

Responses

200

OK

application/json

post

/spaces/{spaceId}/change-requests/{changeRequestId}/update

HTTPcURLJavaScriptPython

POST /v1/spaces/{spaceId}/change-requests/{changeRequestId}/update HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "revision": "text",
  "result": "update"
}

Get a change request the latest content revision

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

metadatabooleanOptional

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

Default: true

computedbooleanOptional

If false is passed, content will not be computed

Default: true

Responses

200

OK

application/json

Responseone of

or

or

or

or

get

/spaces/{spaceId}/change-requests/{changeRequestId}/content

HTTPcURLJavaScriptPython

GET /v1/spaces/{spaceId}/change-requests/{changeRequestId}/content HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "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",
      "git": {
        "oid": "text",
        "path": "text"
      }
    }
  ],
  "variables": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "createdAt": "2025-12-27T04:30:12.310Z",
  "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"
}

List all change request files

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

metadatabooleanOptional

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

Default: true

computedbooleanOptional

If false is passed, content will not be computed

Default: true

Responses

200

OK

application/json

get

/spaces/{spaceId}/change-requests/{changeRequestId}/content/files

HTTPcURLJavaScriptPython

GET /v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/files HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "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"
      }
    }
  ]
}

Get a change request page by its path

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

changeRequestIdstringRequired

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

pagePathstringRequired

The path of the page in the revision.

Query parameters

formatstring · enumOptional

Output format for the content.

Possible values:

evaluatedone ofOptional

Controls whether the document should be evaluated.

• When set to true, the entire document will be evaluated.
• When set to deterministic-only, only expressions that depend exclusively on deterministic inputs will be evaluated.

Default: false

booleanOptional

or

string · enumOptionalPossible values:

dereferencedone ofOptional

Controls whether the document should be deferenced (eference to other content will be resolved and expanded).

• When set to true, the entire document will be deferenced
• When set to reusable-contents, only reusable contents will be deferenced.

Default: false

booleanOptional

or

string · enumOptionalPossible values:

metadatabooleanOptional

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

Default: true

computedbooleanOptional

If false is passed, content will not be computed

Default: true

Responses

200

OK

application/json

Responseone of

or

get

/spaces/{spaceId}/change-requests/{changeRequestId}/content/path/{pagePath}

HTTPcURLJavaScriptPython

GET /v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/path/{pagePath} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "id": "text",
  "title": "text",
  "linkTitle": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2025-12-27T04:30:12.310Z",
  "updatedAt": "2025-12-27T04:30:12.310Z",
  "markdown": "text",
  "type": "document",
  "urls": {
    "app": "https://example.com"
  },
  "slug": "text",
  "path": "text",
  "description": "text",
  "pages": [
    "[Circular Reference]"
  ],
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "width": "default",
    "cover": true,
    "coverSize": "hero",
    "title": true,
    "description": true,
    "tableOfContents": true,
    "outline": true,
    "pagination": true,
    "metadata": true
  },
  "cover": {
    "ref": {
      "kind": "file",
      "file": "text",
      "space": "text"
    },
    "refDark": {
      "kind": "file",
      "file": "text",
      "space": "text"
    },
    "yPos": 0,
    "height": 240
  },
  "variables": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "hidden": false,
  "noIndex": false,
  "noRobotsIndex": false,
  "metaLinks": {
    "canonical": {
      "kind": "page",
      "page": "text",
      "space": "text"
    },
    "alternates": [
      {
        "kind": "page",
        "page": "text",
        "space": "text"
      }
    ]
  },
  "computed": {
    "type": "builtin:openapi",
    "dependencies": {
      "spec": {
        "ref": {
          "kind": "openapi",
          "spec": "text"
        }
      }
    },
    "props": {
      "doc": "models"
    }
  },
  "computedSeed": "text"
}

Get a change request page by its ID

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

changeRequestIdstringRequired

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

pageIdstringRequired

The unique id of the page

Query parameters

formatstring · enumOptional

Output format for the content.

Possible values:

evaluatedone ofOptional

Controls whether the document should be evaluated.

• When set to true, the entire document will be evaluated.
• When set to deterministic-only, only expressions that depend exclusively on deterministic inputs will be evaluated.

Default: false

booleanOptional

or

string · enumOptionalPossible values:

dereferencedone ofOptional

Controls whether the document should be deferenced (eference to other content will be resolved and expanded).

• When set to true, the entire document will be deferenced
• When set to reusable-contents, only reusable contents will be deferenced.

Default: false

booleanOptional

or

string · enumOptionalPossible values:

metadatabooleanOptional

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

Default: true

computedbooleanOptional

If false is passed, content will not be computed

Default: true

Responses

200

OK

application/json

Responseone of

or

or

or

get

/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}

HTTPcURLJavaScriptPython

GET /v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "id": "text",
  "title": "text",
  "linkTitle": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2025-12-27T04:30:12.310Z",
  "updatedAt": "2025-12-27T04:30:12.310Z",
  "markdown": "text",
  "type": "document",
  "urls": {
    "app": "https://example.com"
  },
  "slug": "text",
  "path": "text",
  "description": "text",
  "pages": [
    "[Circular Reference]"
  ],
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "width": "default",
    "cover": true,
    "coverSize": "hero",
    "title": true,
    "description": true,
    "tableOfContents": true,
    "outline": true,
    "pagination": true,
    "metadata": true
  },
  "cover": {
    "ref": {
      "kind": "file",
      "file": "text",
      "space": "text"
    },
    "refDark": {
      "kind": "file",
      "file": "text",
      "space": "text"
    },
    "yPos": 0,
    "height": 240
  },
  "variables": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "hidden": false,
  "noIndex": false,
  "noRobotsIndex": false,
  "metaLinks": {
    "canonical": {
      "kind": "page",
      "page": "text",
      "space": "text"
    },
    "alternates": [
      {
        "kind": "page",
        "page": "text",
        "space": "text"
      }
    ]
  },
  "computed": {
    "type": "builtin:openapi",
    "dependencies": {
      "spec": {
        "ref": {
          "kind": "openapi",
          "spec": "text"
        }
      }
    },
    "props": {
      "doc": "models"
    }
  },
  "computedSeed": "text"
}