Change requests

Review and collaborate on proposed documentation changes before merging.

This API helps you keep your space clean by letting contributors propose changes, review them, and then merge or discard as needed.

The ChangeRequest object

Attributes

objectstring · enumRequired

Type of Object, always equals to "change-request"

Possible values:

idstringRequired

Unique identifier for the change request

numbernumberRequired

Incremental identifier of the change request

statusstring · enumRequiredPossible values:

subjectstring · max: 100Required

Subject of the change request

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

spacestringRequired

ID of the space in which the change request was created.

revisionstringRequired

ID of the active revision in the change request.

revisionInitialstringRequired

ID of the initial revision in the space from which the change request was created.

revisionMergedAncestorstringOptional

ID of the latest revision when updating from main space content.

revisionMergedstringOptional

When merged, ID of the revision resulting from the merge.

commentsnumberRequired

Count of opened comments on the change request.

outdatedbooleanRequired

If true, the change request is not up-to-date with latest changes in the main content.

conversationsIssuesClusterstringOptional

ID of the conversations issues cluster associated with this change request.

The ChangeRequest object

{
  "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-09T00:36:25.523Z",
  "updatedAt": "2025-12-09T00:36:25.523Z",
  "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"
  }
}

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-09T00:36:25.523Z",
      "updatedAt": "2025-12-09T00:36:25.523Z",
      "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-09T00:36:25.523Z",
  "updatedAt": "2025-12-09T00:36:25.523Z",
  "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"
  }
}

Get a change request 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

Responses

200

The matching change request

application/json

404

The change request could not be found.

application/json

get

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

HTTPcURLJavaScriptPython

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

{
  "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-09T00:36:25.523Z",
  "updatedAt": "2025-12-09T00:36:25.523Z",
  "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"
  }
}

Update a change request

patch

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

Body

application/json

subjectstring · max: 100Optional

Subject of the change request

statusstring · enumOptionalPossible values:

Responses

200

The change request has been updated

application/json

patch

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

HTTPcURLJavaScriptPython

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

{
  "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"
    }
  },
  "status": "draft"
}

200

The change request has been updated

{
  "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-09T00:36:25.523Z",
  "updatedAt": "2025-12-09T00:36:25.523Z",
  "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 URL of the content of a change request as PDF

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

onlybooleanOptional

Generate a PDF only for the provided page.

pagestringOptional

ID of a specific page to generate a PDF for.

Responses

200

URL of the PDF

application/json

get

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

HTTPcURLJavaScriptPython

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

200

URL of the PDF

{
  "url": "https://example.com"
}

List all change requests in an organization

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

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 organization's change requests

application/json

get

/orgs/{organizationId}/change-requests

HTTPcURLJavaScriptPython

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

200

List of the organization'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-09T00:36:25.523Z",
      "updatedAt": "2025-12-09T00:36:25.523Z",
      "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"
      }
    }
  ]
}