Change Requests

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

GET a list of Change Requests in a space

List change requests for a space.

GEThttps://api.gitbook.com/v1/spaces/{spaceId}/change-requests

Authorization

user

Path parameters

spaceId*string

The unique id of the space

Query parameters

Response

200default

List of the space's change requests

Body

application/json

nextobject

countnumber

Total count of objects in the list

items*array of ChangeRequest (object)

Request

JavaScriptCurl

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/change-requests', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

{
  "next": {
    "page": "text"
  },
  "count": 0,
  "items": [
    {
      "object": "change-request",
      "id": "text",
      "number": 0,
      "status": "draft",
      "subject": "text",
      "createdBy": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      },
      "createdAt": "2024-04-24T23:52:53.721Z",
      "updatedAt": "2024-04-24T23:52:53.721Z",
      "revision": "text",
      "urls": {
        "app": "https://example.com",
        "location": "https://example.com"
      }
    }
  ]
}

POST a new Change Request in a space

Create a new change request for a space.

POSThttps://api.gitbook.com/v1/spaces/{spaceId}/change-requests

Authorization

user

Path parameters

spaceId*string

The unique id of the space

Body

application/json

subjectstring

Subject of the change-request

Response

201default

Change Request Created

Headers

Body

application/json

object*enum

Type of Object, always equals to "change-request"

change-request

id*string

Unique identifier for the change request

number*number

Incremental identifier of the change request

status*ChangeRequestStatus (enum)

draftopenarchivedmerged

subject*ChangeRequestSubject (string)

Subject of the change request

createdBy*User (object)

createdAt*Timestamp (string (date-time))

updatedAt*Timestamp (string (date-time))

revision*string

ID of the active revision in the change request.

urls*object

URLs associated with the object

Request

JavaScriptCurl

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/change-requests', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "object": "change-request",
  "id": "text",
  "number": 0,
  "status": "draft",
  "subject": "text",
  "createdBy": {
    "object": "user",
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "urls": {
      "location": "https://example.com"
    }
  },
  "createdAt": "2024-04-24T23:52:53.721Z",
  "updatedAt": "2024-04-24T23:52:53.721Z",
  "revision": "text",
  "urls": {
    "app": "https://example.com",
    "location": "https://example.com"
  }
}

POST a merge for a specific Change Request

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

POSThttps://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/merge

Authorization

user

Path parameters

spaceId*string

The unique id of the space

changeRequestId*string

The unique ID of the change request or its number identifier in the space

Response

200default

OK

Body

application/json

revision*string

ID of the resulting revision

result*enum

mergeconflicts

Request

JavaScriptCurl

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/merge', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

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

POST updates to Change Request with primary content

Update a change-request with changes from primary content.

POSThttps://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/update

Authorization

user

Path parameters

spaceId*string

The unique id of the space

changeRequestId*string

The unique ID of the change request or its number identifier in the space

Response

200default

OK

Body

application/json

revision*string

ID of the resulting revision

result*enum

updateconflicts

Request

JavaScriptCurl

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/update', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

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

GET content in a Change Request

Get the latest content revision for a change request.

GEThttps://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content

Authorization

user

Path parameters

spaceId*string

The unique id of the space

changeRequestId*string

The unique ID of the change request or its number identifier in the space

Query parameters

Response

200default

OK

Body

application/json

Revision (one of)

RevisionTypeEdits (all of)RevisionTypeMerge (all of)RevisionTypeRollback (all of)RevisionTypeUpdate (all of)

Request

JavaScriptCurl

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

{
  "object": "revision",
  "id": "text",
  "parents": [
    "text"
  ],
  "pages": [
    {
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "createdAt": "2024-04-24T23:52:53.721Z",
      "updatedAt": "2024-04-24T23:52:53.721Z",
      "markdown": "text",
      "type": "document",
      "urls": {
        "app": "https://example.com"
      },
      "slug": "text",
      "path": "text",
      "description": "text",
      "documentId": "text",
      "pages": [],
      "git": {
        "oid": "text",
        "path": "text"
      },
      "layout": {
        "cover": false,
        "coverSize": "hero",
        "title": false,
        "description": false,
        "tableOfContents": false,
        "outline": false,
        "pagination": false
      },
      "cover": {
        "ref": {
          "kind": "file",
          "file": "text"
        },
        "yPos": 0
      }
    }
  ],
  "files": [
    {
      "id": "text",
      "name": "text",
      "contentType": "text",
      "downloadURL": "text",
      "size": 0,
      "dimensions": {
        "width": 0,
        "height": 0
      },
      "git": {
        "oid": "text",
        "path": "text"
      }
    }
  ],
  "createdAt": "2024-04-24T23:52:53.721Z",
  "git": {
    "oid": "text",
    "message": "text",
    "createdByGitBook": false,
    "url": "text",
    "ref": "text"
  },
  "urls": {
    "app": "https://example.com",
    "published": "https://example.com",
    "public": "https://example.com"
  },
  "type": "edits"
}

GET files in a Change Request

List all files in a change request content

GEThttps://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/files

Authorization

user

Path parameters

spaceId*string

The unique id of the space

changeRequestId*string

The unique ID of the change request or its number identifier in the space

Query parameters

Response

200default

OK

Body

application/json

nextobject

countnumber

Total count of objects in the list

items*array of RevisionFile (object)

Request

JavaScriptCurl

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/files', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

{
  "next": {
    "page": "text"
  },
  "count": 0,
  "items": [
    {
      "id": "text",
      "name": "text",
      "contentType": "text",
      "downloadURL": "text",
      "size": 0,
      "dimensions": {
        "width": 0,
        "height": 0
      },
      "git": {
        "oid": "text",
        "path": "text"
      }
    }
  ]
}

POST content to a Change Request

Import content in a change request.

POSThttps://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/import

Authorization

user

Path parameters

spaceId*string

The unique id of the space

changeRequestId*string

The unique ID of the change request or its number identifier in the space

Body

application/json

url*string

URL of the content to import.

source*ImportContentSource (enum)

websitedocxmarkdownhtmlzipconfluencegithub-wikidropbox-papernotionquipgoogle-docsopen-api

Response

201default

Content imported in a new revision

Headers

Body

application/json

revision*string

ID of the newly created revision.

importedResources*number

How many resources were imported

totalResources*number

How many resources were processed

Request

JavaScriptCurl

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/import', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "url": "text",
      "source": "website"
    }),
});
const data = await response.json();

Response

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

GET a page in a Change Request by it's path

Get a page by its path in a change request.

GEThttps://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/path/{pagePath}

Authorization

user

Path parameters

spaceId*string

The unique id of the space

changeRequestId*string

The unique ID of the change request or its number identifier in the space

pagePath*string

The path of the page in the revision.

Query parameters

Response

200default

OK

Body

application/json

one of

RevisionPageDocument (all of)RevisionPageGroup (all of)

Request

JavaScriptCurl

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/path/{pagePath}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "createdAt": "2024-04-24T23:52:53.721Z",
  "updatedAt": "2024-04-24T23:52:53.721Z",
  "markdown": "text",
  "type": "document",
  "urls": {
    "app": "https://example.com"
  },
  "slug": "text",
  "path": "text",
  "description": "text",
  "documentId": "text",
  "pages": [],
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "cover": false,
    "coverSize": "hero",
    "title": false,
    "description": false,
    "tableOfContents": false,
    "outline": false,
    "pagination": false
  },
  "cover": {
    "ref": {
      "kind": "file",
      "file": "text"
    },
    "yPos": 0
  }
}

GET a page in a Change Request by it's ID

Get a page by its ID in a change request.

GEThttps://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}

Authorization

user

Path parameters

spaceId*string

The unique id of the space

changeRequestId*string

The unique ID of the change request or its number identifier in the space

pageId*string

The unique id of the page

Query parameters

Response

200default

OK

Body

application/json

RevisionPage (one of)

RevisionPageDocument (all of)RevisionPageGroup (all of)RevisionPageLink (all of)

Request

JavaScriptCurl

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "createdAt": "2024-04-24T23:52:53.721Z",
  "updatedAt": "2024-04-24T23:52:53.721Z",
  "markdown": "text",
  "type": "document",
  "urls": {
    "app": "https://example.com"
  },
  "slug": "text",
  "path": "text",
  "description": "text",
  "documentId": "text",
  "pages": [],
  "git": {
    "oid": "text",
    "path": "text"
  },
  "layout": {
    "cover": false,
    "coverSize": "hero",
    "title": false,
    "description": false,
    "tableOfContents": false,
    "outline": false,
    "pagination": false
  },
  "cover": {
    "ref": {
      "kind": "file",
      "file": "text"
    },
    "yPos": 0
  }
}

POST external content to a page in a Change Request by it's ID

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

POSThttps://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}/import

Authorization

user

Path parameters

spaceId*string

The unique id of the space

changeRequestId*string

The unique ID of the change request or its number identifier in the space

pageId*string

The unique id of the page

Body

application/json

url*string

URL of the content to import.

source*ImportContentSource (enum)

websitedocxmarkdownhtmlzipconfluencegithub-wikidropbox-papernotionquipgoogle-docsopen-api

Response

201default

Content imported in a new revision

Headers

Body

application/json

revision*string

ID of the newly created revision.

importedResources*number

How many resources were imported

totalResources*number

How many resources were processed

Request

JavaScriptCurl

const response = await fetch('https://api.gitbook.com/v1/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}/import', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "url": "text",
      "source": "website"
    }),
});
const data = await response.json();

Response

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