Change Requests

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

Last updated 8 days ago

Was this helpful?

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

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "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-15T16:21:38.870Z",
      "updatedAt": "2025-02-15T16:21:38.870Z",
      "id": "text",
      "number": 1,
      "revision": "text",
      "revisionInitial": "text",
      "revisionMergedAncestor": "text",
      "revisionMerged": "text",
      "comments": 1,
      "outdated": true,
      "object": "change-request",
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com"
      }
    }
  ]
}

List of the space's change requests

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

application/json

cURL

JavaScript

Python

HTTP

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'

201

default

{
  "status": "draft",
  "subject": "text",
  "createdBy": {
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "object": "user",
    "urls": {
      "location": "https://example.com"
    }
  },
  "createdAt": "2025-02-15T16:21:38.870Z",
  "updatedAt": "2025-02-15T16:21:38.870Z",
  "id": "text",
  "number": 1,
  "revision": "text",
  "revisionInitial": "text",
  "revisionMergedAncestor": "text",
  "revisionMerged": "text",
  "comments": 1,
  "outdated": true,
  "object": "change-request",
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com"
  }
}

Change Request Created

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

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/merge' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "revision": "text",
  "result": "merge"
}

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

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/update' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "revision": "text",
  "result": "update"
}

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

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "id": "text",
  "createdAt": "2025-02-15T16:21:38.870Z",
  "git": {
    "oid": "text",
    "message": "text",
    "createdByGitBook": true,
    "url": "text",
    "ref": "text"
  },
  "object": "revision",
  "pages": [
    {
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "icon": "gear",
      "createdAt": "2025-02-15T16:21:38.870Z",
      "updatedAt": "2025-02-15T16:21:38.870Z",
      "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]",
      "urls": {
        "app": "https://example.com"
      },
      "pages": "[Circular Reference]"
    }
  ],
  "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

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/files' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

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

application/json

cURL

JavaScript

Python

HTTP

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

201

default

{
  "revision": "text",
  "importedResources": 1,
  "totalResources": 1
}

Content imported in a new revision

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

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/path/{pagePath}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2025-02-15T16:21:38.870Z",
  "updatedAt": "2025-02-15T16:21:38.870Z",
  "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]",
  "urls": {
    "app": "https://example.com"
  },
  "pages": "[Circular Reference]"
}

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

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2025-02-15T16:21:38.870Z",
  "updatedAt": "2025-02-15T16:21:38.870Z",
  "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]",
  "urls": {
    "app": "https://example.com"
  },
  "pages": "[Circular Reference]"
}

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

application/json

cURL

JavaScript

Python

HTTP

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

201

default

{
  "revision": "text",
  "importedResources": 1,
  "totalResources": 1
}

Content imported in a new revision