Apply a batch of content changes to a change request

Applies an ordered array of content changes (up to 50) to the change request atomically, creating a single new revision. Changes are applied sequentially; if any single change is invalid the entire batch is rejected and no revision is created. Use this to create, update, move, or delete pages within a change request before merging to live. This is the primary way to programmatically author content in a change request.

When page content is provided as markdown, links to other pages are resolved against the change request's current page tree. You can link a page by:

• Page ID — /pages/<pageId> (also /pages/<pageId>#anchor).
• Page slug path — /pages/<slug> for a top-level page, or /pages/<parent-slug>/<slug> for a nested page (e.g. /pages/guides/getting-started).
• Markdown file path — the path the page would have in Git: /pages/<slug>.md for a page, or /pages/<slug>/README.md for a page that has child pages. The space's root page is /pages/README.md.
• Relative markdown link — resolved against the page being edited, e.g. ./sibling.md, ../other.md, or ../README.md (the parent page). Folder-style links without an extension (e.g. ./section) resolve to that folder's page.

External URLs (https://…) are kept as-is. A link that does not match any page in the change request is left as plain text rather than causing the request to fail.

Available in MCP

post

Authorizations

useroauth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

changeRequestIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

Body

application/json

Responses

200

The change request has been updated

application/json

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

mergedAtstring · date-timeOptional

Date at which the change request was merged. Only present when the change request has been merged.

spacestringRequired

ID of the space in which the change request was created.

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.

404

The change request could not be found.

application/json

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

HTTPcURLJavaScriptPython

POST /v1/spaces/{spaceId}/change-requests/{changeRequestId}/content HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 174

{
  "changes": [
    {
      "operation": "update_page",
      "page": "page_id",
      "document": {
        "markdown": "# Hello World\n\nThis is a markdown document linking to [another page](/pages/page_id).\n"
      }
    }
  ]
}

{
  "object": "change-request",
  "id": "text",
  "number": 1,
  "status": "draft",
  "subject": "text",
  "description": {
    "object": "document",
    "data": {},
    "nodes": [
      {
        "object": "block",
        "type": "paragraph",
        "data": {},
        "nodes": [
          {
            "object": "text",
            "leaves": [
              {
                "object": "leaf",
                "text": "Hello world",
                "marks": []
              }
            ]
          }
        ]
      }
    ]
  },
  "createdBy": {
    "object": "user",
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "urls": {
      "location": "https://example.com"
    }
  },
  "createdAt": "2026-07-21T23:17:53.983Z",
  "updatedAt": "2026-07-21T23:17:53.983Z",
  "mergedBy": {
    "object": "user",
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "urls": {
      "location": "https://example.com"
    }
  },
  "mergedAt": "2026-07-21T23:17:53.983Z",
  "space": "text",
  "revision": "text",
  "revisionInitial": "text",
  "revisionMergedAncestor": "text",
  "revisionMerged": "text",
  "comments": 1,
  "siteTopic": {
    "site": "text",
    "topic": "text",
    "finding": "text"
  },
  "outdated": true,
  "links": [
    {
      "ref": {
        "kind": "url",
        "url": "text"
      },
      "title": "text",
      "expanded": {
        "kind": "external-ticket",
        "provider": "jira",
        "state": "connected",
        "key": "text",
        "url": "https://example.com",
        "status": {
          "id": "text",
          "name": "text"
        },
        "summary": "text"
      }
    }
  ],
  "urls": {
    "app": "https://example.com",
    "location": "https://example.com"
  }
}