Update a change request's subject, description, or status

Updates the metadata of a change request. Use this to rename a change request, add context before requesting a review, or change the workflow status without merging. To update page content within the change request, use the content endpoint instead. Set siteFindingIds to replace the documentation findings linked to the change request. Outbound broken links are resolved by the outbound checker, rather than by merging.

Available in MCP

patch

Authorizations

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_-]+$

Header parameters

preferstring · enumOptional

Control whether a successful response includes the updated resource representation.

Possible values:

Body

subjectstring · max: 100Optional

Subject of the change request

statusstring · enumOptionalPossible values:

siteFindingIdstring · nullableOptionalDeprecated

The site finding this change request fixes. Use siteFindingIds instead. The finding's site must contain this space. Replaces the whole set of linked findings with this finding. Pass null to unlink all findings.

siteFindingIdsstring[] · max: 25 · nullableOptional

Replaces the linked site findings. Each finding's site must contain this space, and the caller must have edit permission on each site. Pass null or an empty list to unlink all findings. Omit to keep the current links. Takes precedence over siteFindingId when both are supplied.

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.

204

Change request updated without returning its representation

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

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

{
  "subject": "text",
  "description": {
    "object": "document",
    "data": {},
    "nodes": [
      {
        "object": "block",
        "type": "paragraph",
        "data": {},
        "nodes": [
          {
            "object": "text",
            "leaves": [
              {
                "object": "leaf",
                "text": "Hello world",
                "marks": []
              }
            ]
          }
        ]
      }
    ]
  },
  "links": [
    {
      "id": "text",
      "ref": {
        "kind": "url",
        "url": "text"
      },
      "title": "text"
    }
  ],
  "status": "draft",
  "siteFindingIds": [
    "text"
  ]
}

{
  "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-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "mergedBy": {
    "object": "user",
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "urls": {
      "location": "https://example.com"
    }
  },
  "mergedAt": "2026-01-01T00:00:00.000Z",
  "space": "text",
  "revision": "text",
  "revisionInitial": "text",
  "revisionMergedAncestor": "text",
  "revisionMerged": "text",
  "comments": 1,
  "changeCounts": {
    "pages": {
      "added": 1,
      "modified": 1,
      "deleted": 1
    },
    "library": {
      "added": 1,
      "modified": 1,
      "deleted": 1
    },
    "blocks": {
      "added": 1,
      "modified": 1,
      "deleted": 1
    },
    "blocksOmittedReason": "too-many-pages"
  },
  "siteTopic": {
    "site": "text",
    "topic": "text"
  },
  "siteFindings": [
    {
      "site": "text",
      "finding": "text"
    }
  ],
  "styleguide": {
    "site": "text",
    "run": "text",
    "changedPages": 1,
    "checkedAt": "2026-01-01T00:00:00.000Z"
  },
  "outdated": true,
  "imports": [
    {
      "object": "import-run",
      "id": "text",
      "startedAt": "2026-01-01T00:00:00.000Z",
      "completedAt": "2026-01-01T00:00:00.000Z",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "status": "pending",
      "reason": "text",
      "source": {
        "type": "website",
        "url": "https://example.com"
      },
      "target": {
        "space": "text",
        "changeRequest": "text",
        "page": "text"
      },
      "site": "text",
      "createdBy": "text",
      "urls": {
        "location": "https://example.com"
      },
      "pages": [
        {
          "id": "text",
          "sourceURL": "text",
          "type": "page",
          "status": "complete"
        }
      ]
    }
  ],
  "links": [
    {
      "id": "text",
      "ref": {
        "kind": "url",
        "url": "text"
      },
      "title": "text",
      "isSyncing": true,
      "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"
  }
}