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"

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-04-26T13:19:44.919Z",
  "updatedAt": "2025-04-26T13:19:44.919Z",
  "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
Responseall of
get
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-04-26T13:19:44.919Z",
      "updatedAt": "2025-04-26T13:19:44.919Z",
      "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
post
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-04-26T13:19:44.919Z",
  "updatedAt": "2025-04-26T13:19:44.919Z",
  "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
get
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-04-26T13:19:44.919Z",
  "updatedAt": "2025-04-26T13:19:44.919Z",
  "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
patch
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-04-26T13:19:44.919Z",
  "updatedAt": "2025-04-26T13:19:44.919Z",
  "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
post
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
post
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
get
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"
}

Was this helpful?