Change Requests

A change request in GitBook is the entity of a revision to a space in progress.

List change requests for a space.

get

/spaces/{spaceId}/change-requests

Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Query parameters
pagestring

Identifier of the page results to fetch.

limitnumber

The number of results per page

statusenum

If defined, only change requests matching this status will be returned.

Options: draft, open, archived, merged
contributorstring

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'
{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "status": "draft",
      "subject": "text",
      "createdBy": {
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "object": "user",
        "urls": {
          "location": "https://example.com"
        }
      },
      "createdAt": "2025-02-18T02:53:35.811Z",
      "updatedAt": "2025-02-18T02:53:35.811Z",
      "id": "text",
      "number": 1,
      "revision": "text",
      "revisionInitial": "text",
      "revisionMergedAncestor": "text",
      "revisionMerged": "text",
      "comments": 1,
      "outdated": true,
      "object": "change-request",
      "urls": {
        "app": "https://example.com",
        "location": "https://example.com"
      }
    }
  ]
}

Create a new change request for a space.

post

/spaces/{spaceId}/change-requests

Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Body
subjectstring

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'
{
  "status": "draft",
  "subject": "text",
  "createdBy": {
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "object": "user",
    "urls": {
      "location": "https://example.com"
    }
  },
  "createdAt": "2025-02-18T02:53:35.811Z",
  "updatedAt": "2025-02-18T02:53:35.811Z",
  "id": "text",
  "number": 1,
  "revision": "text",
  "revisionInitial": "text",
  "revisionMergedAncestor": "text",
  "revisionMerged": "text",
  "comments": 1,
  "outdated": true,
  "object": "change-request",
  "urls": {
    "app": "https://example.com",
    "location": "https://example.com"
  }
}

Merge a change request in the primary content of a space.

post

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

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'
{
  "result": "merge",
  "revision": "text"
}

Update a change-request with changes from primary content.

post

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

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'
{
  "result": "update",
  "revision": "text"
}

Get the latest content revision for a change request.

get

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

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
metadataboolean

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean

If false is passed, content will not be computed

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "id": "text",
  "createdAt": "2025-02-18T02:53:35.811Z",
  "git": {
    "oid": "text",
    "message": "text",
    "createdByGitBook": true,
    "url": "text",
    "ref": "text"
  },
  "object": "revision",
  "pages": [
    {
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "icon": "gear",
      "createdAt": "2025-02-18T02:53:35.811Z",
      "updatedAt": "2025-02-18T02:53:35.811Z",
      "markdown": "text",
      "description": "text",
      "git": {
        "oid": "text",
        "path": "text"
      },
      "layout": {
        "coverSize": "hero",
        "cover": true,
        "title": true,
        "description": true,
        "tableOfContents": true,
        "outline": true,
        "pagination": true
      },
      "cover": {
        "ref": {
          "file": "text",
          "kind": "file"
        },
        "yPos": 1
      },
      "kind": "sheet",
      "type": "document",
      "slug": "text",
      "path": "text",
      "documentId": "text",
      "hidden": false,
      "noIndex": false,
      "noRobotsIndex": false,
      "computed": "[Circular Reference]",
      "pages": "[Circular Reference]",
      "urls": {
        "app": "https://example.com"
      }
    }
  ],
  "files": [
    {
      "id": "text",
      "name": "text",
      "contentType": "text",
      "downloadURL": "text",
      "size": 1,
      "git": {
        "oid": "text",
        "path": "text"
      },
      "dimensions": {
        "width": 1,
        "height": 1
      }
    }
  ],
  "reusableContents": [
    {
      "id": "text",
      "title": "text",
      "document": "text",
      "git": {
        "oid": "text",
        "path": "text"
      }
    }
  ],
  "parents": [
    "text"
  ],
  "urls": {
    "app": "https://example.com",
    "published": "https://example.com",
    "public": "https://example.com"
  },
  "type": "edits"
}

List all files in a change request content

get

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

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
pagestring

Identifier of the page results to fetch.

limitnumber

The number of results per page

metadataboolean

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean

If false is passed, content will not be computed

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/files' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "name": "text",
      "contentType": "text",
      "downloadURL": "text",
      "size": 1,
      "git": {
        "oid": "text",
        "path": "text"
      },
      "dimensions": {
        "width": 1,
        "height": 1
      }
    }
  ]
}

Import content in a change request.

post

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

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
sourceenumrequired
Options: website, docx, markdown, html, zip, confluence, github-wiki, dropbox-paper, notion, quip, google-docs, open-api
urlstring urirequired

URL of the content to import.

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/import' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"source":"website","url":"https://example.com"}'
{
  "revision": "text",
  "importedResources": 1,
  "totalResources": 1
}

Get a page by its path in a change request.

get

/spaces/{spaceId}/change-requests/{changeRequestId}/content/path/{pagePath}

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

pagePathstringrequired

The path of the page in the revision.

Query parameters
formatenum

Output format for the content.

Options: document, markdown
metadataboolean

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean

If false is passed, content will not be computed

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/path/{pagePath}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2025-02-18T02:53:35.811Z",
  "updatedAt": "2025-02-18T02:53:35.811Z",
  "markdown": "text",
  "description": "text",
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "coverSize": "hero",
    "cover": true,
    "title": true,
    "description": true,
    "tableOfContents": true,
    "outline": true,
    "pagination": true
  },
  "cover": {
    "ref": {
      "file": "text",
      "kind": "file"
    },
    "yPos": 1
  },
  "kind": "sheet",
  "type": "document",
  "slug": "text",
  "path": "text",
  "documentId": "text",
  "hidden": false,
  "noIndex": false,
  "noRobotsIndex": false,
  "computed": "[Circular Reference]",
  "pages": "[Circular Reference]",
  "urls": {
    "app": "https://example.com"
  }
}

Get a page by its ID in a change request.

get

/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}

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

pageIdstringrequired

The unique id of the page

Query parameters
formatenum

Output format for the content.

Options: document, markdown
metadataboolean

If false is passed, "git" mutable metadata will not returned. Passing false can optimize performances of the lookup.

computedboolean

If false is passed, content will not be computed

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2025-02-18T02:53:35.811Z",
  "updatedAt": "2025-02-18T02:53:35.811Z",
  "markdown": "text",
  "description": "text",
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "coverSize": "hero",
    "cover": true,
    "title": true,
    "description": true,
    "tableOfContents": true,
    "outline": true,
    "pagination": true
  },
  "cover": {
    "ref": {
      "file": "text",
      "kind": "file"
    },
    "yPos": 1
  },
  "kind": "sheet",
  "type": "document",
  "slug": "text",
  "path": "text",
  "documentId": "text",
  "hidden": false,
  "noIndex": false,
  "noRobotsIndex": false,
  "computed": "[Circular Reference]",
  "pages": "[Circular Reference]",
  "urls": {
    "app": "https://example.com"
  }
}

Import external content into a page of a change-request by its ID.

post

/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}/import

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

pageIdstringrequired

The unique id of the page

Body
sourceenumrequired
Options: website, docx, markdown, html, zip, confluence, github-wiki, dropbox-paper, notion, quip, google-docs, open-api
urlstring urirequired

URL of the content to import.

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}/import' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"source":"website","url":"https://example.com"}'
{
  "revision": "text",
  "importedResources": 1,
  "totalResources": 1
}

Last updated

Was this helpful?