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

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.

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-05-05T12:23:40.255Z",
  "updatedAt": "2025-05-05T12:23:40.255Z",
  "revision": "text",
  "revisionInitial": "text",
  "revisionMergedAncestor": "text",
  "revisionMerged": "text",
  "comments": 1,
  "outdated": true,
  "urls": {
    "app": "https://example.com",
    "location": "https://example.com"
  }
}

List all change requests

get

Authorizations

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:

contributorstringOptional

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

Responses

200

List of the space's change requests

application/json

Responseall of

get

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",
      "createdBy": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      },
      "createdAt": "2025-05-05T12:23:40.255Z",
      "updatedAt": "2025-05-05T12:23:40.255Z",
      "revision": "text",
      "revisionInitial": "text",
      "revisionMergedAncestor": "text",
      "revisionMerged": "text",
      "comments": 1,
      "outdated": true,
      "urls": {
        "app": "https://example.com",
        "location": "https://example.com"
      }
    }
  ]
}

Create a change request

post

Authorizations

Path parameters

spaceIdstringRequired

The unique id of the space

Body

subjectstringOptional

Subject of the change-request

Responses

201

Change Request Created

application/json

post

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: 18

{
  "subject": "text"
}

201

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-05-05T12:23:40.255Z",
  "updatedAt": "2025-05-05T12:23:40.255Z",
  "revision": "text",
  "revisionInitial": "text",
  "revisionMergedAncestor": "text",
  "revisionMerged": "text",
  "comments": 1,
  "outdated": true,
  "urls": {
    "app": "https://example.com",
    "location": "https://example.com"
  }
}

Get a change request by its ID

get

Authorizations

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

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",
  "createdBy": {
    "object": "user",
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "urls": {
      "location": "https://example.com"
    }
  },
  "createdAt": "2025-05-05T12:23:40.255Z",
  "updatedAt": "2025-05-05T12:23:40.255Z",
  "revision": "text",
  "revisionInitial": "text",
  "revisionMergedAncestor": "text",
  "revisionMerged": "text",
  "comments": 1,
  "outdated": true,
  "urls": {
    "app": "https://example.com",
    "location": "https://example.com"
  }
}

Update a change request

patch

Authorizations

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

subjectstring · max: 100Optional

Subject of the change request

statusstring · enumOptionalPossible values:

Responses

200

The change request has been updated

application/json

patch

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: 35

{
  "subject": "text",
  "status": "draft"
}

200

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-05-05T12:23:40.255Z",
  "updatedAt": "2025-05-05T12:23:40.255Z",
  "revision": "text",
  "revisionInitial": "text",
  "revisionMergedAncestor": "text",
  "revisionMerged": "text",
  "comments": 1,
  "outdated": true,
  "urls": {
    "app": "https://example.com",
    "location": "https://example.com"
  }
}

Merge a change request

post

Authorizations

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

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

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

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

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

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