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.
Type of Object, always equals to "change-request"
Unique identifier for the change request
Incremental identifier of the change request
Subject of the change request
ID of the active revision in the change request.
ID of the initial revision in the space from which the change request was created.
ID of the latest revision when updating from main space content.
When merged, ID of the revision resulting from the merge.
Count of opened comments on the change request.
If true, the change request is not up-to-date with latest changes in the main content.
The ChangeRequest object
{
"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-06-21T02:26:33.754Z",
"updatedAt": "2025-06-21T02:26:33.754Z",
"revision": "text",
"revisionInitial": "text",
"revisionMergedAncestor": "text",
"revisionMerged": "text",
"comments": 1,
"outdated": true,
"urls": {
"app": "https://example.com",
"location": "https://example.com"
}
}The unique id of the space
Identifier of the page results to fetch.
The number of results per page
If defined, only change requests matching this status will be returned.
openPossible values: If defined, only change requests with contributions from this user will be returned.
GET /v1/spaces/{spaceId}/change-requests HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
List of the space's change requests
{
"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-06-21T02:26:33.754Z",
"updatedAt": "2025-06-21T02:26:33.754Z",
"revision": "text",
"revisionInitial": "text",
"revisionMergedAncestor": "text",
"revisionMerged": "text",
"comments": 1,
"outdated": true,
"urls": {
"app": "https://example.com",
"location": "https://example.com"
}
}
]
}The unique id of the space
Subject of the change-request
ID of the agent task to implement
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: 39
{
"subject": "text",
"agentTaskId": "text"
}Change Request Created
{
"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-06-21T02:26:33.754Z",
"updatedAt": "2025-06-21T02:26:33.754Z",
"revision": "text",
"revisionInitial": "text",
"revisionMergedAncestor": "text",
"revisionMerged": "text",
"comments": 1,
"outdated": true,
"urls": {
"app": "https://example.com",
"location": "https://example.com"
}
}The unique id of the space
The unique ID of the change request or its number identifier in the space
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",
"createdBy": {
"object": "user",
"id": "text",
"displayName": "text",
"email": "text",
"photoURL": "text",
"urls": {
"location": "https://example.com"
}
},
"createdAt": "2025-06-21T02:26:33.754Z",
"updatedAt": "2025-06-21T02:26:33.754Z",
"revision": "text",
"revisionInitial": "text",
"revisionMergedAncestor": "text",
"revisionMerged": "text",
"comments": 1,
"outdated": true,
"urls": {
"app": "https://example.com",
"location": "https://example.com"
}
}The unique id of the space
The unique ID of the change request or its number identifier in the space
Subject of the change request
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: 35
{
"subject": "text",
"status": "draft"
}The change request has been updated
{
"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-06-21T02:26:33.754Z",
"updatedAt": "2025-06-21T02:26:33.754Z",
"revision": "text",
"revisionInitial": "text",
"revisionMergedAncestor": "text",
"revisionMerged": "text",
"comments": 1,
"outdated": true,
"urls": {
"app": "https://example.com",
"location": "https://example.com"
}
}The unique id of the space
The unique ID of the change request or its number identifier in the space
POST /v1/spaces/{spaceId}/change-requests/{changeRequestId}/merge HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
OK
{
"revision": "text",
"result": "merge"
}The unique id of the space
The unique ID of the change request or its number identifier in the space
POST /v1/spaces/{spaceId}/change-requests/{changeRequestId}/update HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
OK
{
"revision": "text",
"result": "update"
}The unique id of the space
The unique ID of the change request or its number identifier in the space
Generate a PDF only for the provided page.
ID of a specific page to generate a PDF for.
GET /v1/spaces/{spaceId}/change-requests/{changeRequestId}/pdf HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
URL of the PDF
{
"url": "https://example.com"
}Was this helpful?