Create a new change request in a space

Creates a new change request, which is a draft working copy of the space's content — similar to a Git branch or pull request. Use this before making content edits to avoid modifying the live published content directly. Optionally supply a subject and a template to pre-populate the change request with content. Once created, use the change-request content endpoints to read and modify pages within the draft, then merge it when ready. Pass siteFindingIds to link the documentation findings this change request fixes. Outbound broken links are resolved by the outbound checker, rather than by merging.

Available in MCP

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

A unique entity identifier

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

Body

subjectstringOptional

Subject of the change request

siteFindingIdstringOptionalDeprecated

The site finding this change request fixes. Use siteFindingIds instead. The finding's site must contain this space.

siteFindingIdsstring[] · max: 25Optional

Site findings this change request fixes. Each finding's site must contain this space, and the caller must have edit permission on each site. Takes precedence over siteFindingId when both are supplied.

Other propertiesanyOptional

Responses

201

Change Request Created

application/json

post/spaces/{spaceId}/change-requests

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

{
  "subject": "text",
  "template": {
    "id": "text",
    "params": {
      "contentRefs": {
        "ANY_ADDITIONAL_PROPERTY": {
          "kind": "file",
          "file": "text",
          "space": "text"
        }
      }
    }
  },
  "description": {
    "object": "document",
    "data": {},
    "nodes": [
      {
        "object": "block",
        "type": "paragraph",
        "data": {},
        "nodes": [
          {
            "object": "text",
            "leaves": [
              {
                "object": "leaf",
                "text": "Hello world",
                "marks": []
              }
            ]
          }
        ]
      }
    ]
  },
  "siteFindingIds": [
    "text"
  ],
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

201

Change Request Created

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