List documentation issues GitBook has found on a site

Lists the quality issues GitBook's AI has identified on a site by comparing its content against real usage and external sources — content gaps, outdated or incorrect content, and broken or outbound links. Use this when asked to find, audit, or fix problems in a site's docs. Only findings with status "open" need work; "candidate" ones have not been confirmed yet. A "broken-link" finding is fixed by a redirect rather than a content edit: pass its brokenLinkAction to createSiteRedirect. Fix the rest by opening a change request with its siteFindingId set, so merging the change request resolves it.

Available in MCP

get

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

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

topicstringOptional

Filter findings by associated site topic ID.

questionstringOptional

Filter findings that reference the given site question ID as evidence.

statusstring · enumOptional

Status of a site finding.

• candidate is a finding that has been raised but not yet confirmed. Typically these are not shown to users.
• open is a finding that has been surfaced to users and is still under investigation.
• done is a finding that has been resolved and is no longer under investigation.
• canceled is a finding that has been canceled and is no longer under investigation.

Possible values:

urlstringOptional

Filter link findings whose URL contains this text: the broken path of a broken-link finding, or the checked URL of an outbound-link-error one. Findings of any other type never match, so this narrows the list to link findings on its own.

severitystring · enumOptional

Estimated end-user severity of a site finding.

Possible values:

hasChangeRequestsbooleanOptional

Filter findings that have at least one associated change request.

updatedAfterstring · date-timeOptional

Only return findings last updated at or after this date.

updatedBeforestring · date-timeOptional

Only return findings last updated before this date.

orderBystring · enumOptional

The field to sort site findings by. updatedAt returns the most recently updated findings first. severity returns the most severe findings first. sources returns the findings with the most linked sources (questions plus records) first. suggestedFix is for link findings: those that come with a fix (a suggested redirect, or an outbound link to correct) come before broken URLs the audit found no page for, most severe first within each group. Other finding types sort with the second group. Defaults to 'updatedAt'.

Default: updatedAtPossible values:

Responses

200

OK

application/json

countnumberOptional

Total count of objects in the list

get/orgs/{organizationId}/sites/{siteId}/findings

GET /v1/orgs/{organizationId}/sites/{siteId}/findings HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site-finding",
      "id": "text",
      "scan": "text",
      "topic": null,
      "title": "text",
      "changeRequests": 1,
      "pages": 1,
      "records": 1,
      "questions": 1,
      "status": "candidate",
      "type": "content-outdated",
      "severity": "low",
      "description": {
        "object": "document",
        "data": {},
        "nodes": [
          {
            "object": "block",
            "type": "paragraph",
            "data": {},
            "nodes": [
              {
                "object": "text",
                "leaves": [
                  {
                    "object": "leaf",
                    "text": "Hello world",
                    "marks": []
                  }
                ]
              }
            ]
          }
        ]
      },
      "autoFixable": true,
      "autoResolution": "drafted",
      "brokenLinkAction": {
        "source": "text",
        "captureWildcard": true,
        "destination": {
          "kind": "path",
          "spaceId": "text",
          "path": "text"
        }
      },
      "outboundLink": {
        "url": "https://example.com",
        "host": "text",
        "status": "pending",
        "failureKind": "client-error",
        "httpStatus": 1,
        "checkedAt": "2026-01-01T00:00:00.000Z"
      },
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "urls": {
        "location": "https://example.com"
      }
    }
  ]
}