Start a style guide check run for a site

Starts a style guide check: GitBook Agent reviews the given spaces against the site's style guide and proposes fixes. A space with no check open gets a new draft change request marked as belonging to the returned run; one whose check is still open has it taken over instead, so it stays marked with the run that opened it. Fails if the site has no style guide.

Available in MCP

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

Body

spacesstring[] · min: 1 · max: 3Required

IDs of the site's spaces to check. Each must be an editable content space of the site, and not the style guide itself.

Responses

201

Style guide check run started

application/json

404

Not Found

application/json

post/orgs/{organizationId}/sites/{siteId}/styleguide/runs

POST /v1/orgs/{organizationId}/sites/{siteId}/styleguide/runs HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "spaces": [
    "text"
  ]
}

{
  "run": {
    "object": "styleguide-run",
    "id": "text",
    "site": "text",
    "styleguide": "text",
    "spaces": [
      "text"
    ],
    "createdAt": "2026-01-01T00:00:00.000Z",
    "createdBy": {
      "object": "user",
      "id": "text",
      "displayName": "text",
      "email": "text",
      "photoURL": "text",
      "urls": {
        "location": "https://example.com"
      }
    }
  },
  "changeRequests": [
    {
      "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"
      }
    }
  ]
}