The State of Docs Survey 2025. Use your voice to prove why docs matter:
Take the survey
Product
PricingLog inSign up

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"

Available options:
idstringrequired

Unique identifier for the change request

numbernumberrequired

Incremental identifier of the change request

statusstring · enumrequiredAvailable options:
subjectstring · max: 100required

Subject of the change request

createdByobjectrequired

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.

urlsobjectrequired

URLs associated with the object

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-04-16T19:34:42.780Z",
  "updatedAt": "2025-04-16T19:34:42.780Z",
  "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: openAvailable options:
contributorstringoptional

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

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "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-04-16T19:34:42.780Z",
      "updatedAt": "2025-04-16T19:34:42.780Z",
      "revision": "text",
      "revisionInitial": "text",
      "revisionMergedAncestor": "text",
      "revisionMerged": "text",
      "comments": 1,
      "outdated": true,
      "urls": {
        "app": "https://example.com",
        "location": "https://example.com"
      }
    }
  ]
}

List of the space's change requests

Create a change request

post
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Body
subjectstringoptional

Subject of the change-request

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "subject": "text"
  }'
{
  "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-04-16T19:34:42.780Z",
  "updatedAt": "2025-04-16T19:34:42.780Z",
  "revision": "text",
  "revisionInitial": "text",
  "revisionMergedAncestor": "text",
  "revisionMerged": "text",
  "comments": 1,
  "outdated": true,
  "urls": {
    "app": "https://example.com",
    "location": "https://example.com"
  }
}

Change Request Created

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
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "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-04-16T19:34:42.780Z",
  "updatedAt": "2025-04-16T19:34:42.780Z",
  "revision": "text",
  "revisionInitial": "text",
  "revisionMergedAncestor": "text",
  "revisionMerged": "text",
  "comments": 1,
  "outdated": true,
  "urls": {
    "app": "https://example.com",
    "location": "https://example.com"
  }
}

The matching change request

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 · enumoptionalAvailable options:
Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "subject": "text",
    "status": "draft"
  }'
{
  "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-04-16T19:34:42.780Z",
  "updatedAt": "2025-04-16T19:34:42.780Z",
  "revision": "text",
  "revisionInitial": "text",
  "revisionMergedAncestor": "text",
  "revisionMerged": "text",
  "comments": 1,
  "outdated": true,
  "urls": {
    "app": "https://example.com",
    "location": "https://example.com"
  }
}

The change request has been updated

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
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/merge' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "revision": "text",
  "result": "merge"
}

OK

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
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/update' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "revision": "text",
  "result": "update"
}

OK

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
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/pdf' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "url": "https://example.com"
}

URL of the PDF

Was this helpful?