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

JavaScriptCurlPython

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

200default

{
  "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-11-21T07:25:27.485Z",
      "updatedAt": "2024-11-21T07:25:27.485Z",
      "revision": "text",
      "revisionInitial": "text",
      "revisionMergedAncestor": "text",
      "revisionMerged": "text",
      "comments": 0,
      "outdated": false,
      "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.

revisionInitial*string

ID of the initial revision in the space from which the change request was created.

revisionMergedAncestorstring

ID of the latest revision when updating from main space content.

revisionMergedstring

When merged, ID of the revision resulting from the merge.

comments*number

Count of opened comments on the change request.

outdated*boolean

If true, the change request is not up-to-date with latest changes in the main content.

urls*object

URLs associated with the object

Request

JavaScriptCurlPython

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

201default

{
  "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-11-21T07:25:27.485Z",
  "updatedAt": "2024-11-21T07:25:27.485Z",
  "revision": "text",
  "revisionInitial": "text",
  "revisionMergedAncestor": "text",
  "revisionMerged": "text",
  "comments": 0,
  "outdated": false,
  "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

JavaScriptCurlPython

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

200default

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

JavaScriptCurlPython

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

200default

{
  "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)RevisionTypeComputed (all of)

Request

JavaScriptCurlPython

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

200default

{
  "object": "revision",
  "id": "text",
  "parents": [
    "text"
  ],
  "pages": [
    {
      "id": "text",
      "title": "text",
      "emoji": "🎉",
      "icon": "gear",
      "createdAt": "2024-11-21T07:25:27.485Z",
      "updatedAt": "2024-11-21T07:25:27.485Z",
      "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
      },
      "hidden": false,
      "noIndex": false,
      "noRobotsIndex": false,
      "computed": {
        "integration": "text",
        "source": "text",
        "props": {},
        "dependsOn": [
          {
            "kind": "space",
            "space": "text"
          }
        ]
      }
    }
  ],
  "files": [
    {
      "id": "text",
      "name": "text",
      "contentType": "text",
      "downloadURL": "text",
      "size": 0,
      "dimensions": {
        "width": 0,
        "height": 0
      },
      "git": {
        "oid": "text",
        "path": "text"
      }
    }
  ],
  "reusableContents": [
    {
      "id": "text",
      "title": "text",
      "document": "text",
      "git": {
        "oid": "text",
        "path": "text"
      }
    }
  ],
  "createdAt": "2024-11-21T07:25:27.485Z",
  "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

JavaScriptCurlPython

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

200default

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

JavaScriptCurlPython

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

201default

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

JavaScriptCurlPython

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

200default

{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2024-11-21T07:25:27.485Z",
  "updatedAt": "2024-11-21T07:25:27.485Z",
  "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
  },
  "hidden": false,
  "noIndex": false,
  "noRobotsIndex": false,
  "computed": {
    "integration": "text",
    "source": "text",
    "props": {},
    "dependsOn": [
      {
        "kind": "space",
        "space": "text"
      }
    ]
  }
}

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)RevisionPageComputed (all of)

Request

JavaScriptCurlPython

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

200default

{
  "id": "text",
  "title": "text",
  "emoji": "🎉",
  "icon": "gear",
  "createdAt": "2024-11-21T07:25:27.485Z",
  "updatedAt": "2024-11-21T07:25:27.485Z",
  "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
  },
  "hidden": false,
  "noIndex": false,
  "noRobotsIndex": false,
  "computed": {
    "integration": "text",
    "source": "text",
    "props": {},
    "dependsOn": [
      {
        "kind": "space",
        "space": "text"
      }
    ]
  }
}

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

JavaScriptCurlPython

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

201default

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