Apply an action to a finding

Applies one of the actions a finding lists, with the site permission it gives: resolve, dismiss or reopen it, act on a broken link's redirect, or reject the change request GitBook drafted for an outbound link. Returns 409 when the finding doesn't allow the action now.

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

siteFindingIdstringRequired

The unique id of the site finding

Body
actionstring · enumRequired

An action that moves a finding to another state. A finding's actions lists the ones it allows.

  • approve makes the redirect GitBook drafted for a broken link live, which resolves the finding. A change request GitBook drafted for an outbound link is approved by merging it.
  • reject deletes the redirect GitBook drafted for a broken link; the finding stays open and GitBook won't draft a fix for it again. For an outbound link, it archives the change request GitBook drafted (awaitingChangeRequest) and unlinks every link it fixes. They are open again, marked undone, and GitBook won't draft a fix for them again.
  • create-redirect creates a redirect for a broken link's path with createSiteRedirect, prefilled with the suggestion; it resolves the finding.
  • mark-resolved resolves it. A broken link resolved this way has no redirect: visitors still get a 404.
  • reopen reopens a resolved finding. For a broken link, it deletes the live redirect at its path; for a fix GitBook applied, this undoes the fix and GitBook won't fix the link again.
  • ignore dismisses it.
  • restore reopens a dismissed finding.
Possible values:
Responses
200

Action applied

application/json
objectstring · enumRequiredPossible values:
idstringRequired

The ID of the finding

scanstringRequired

The site scan ID associated with the finding

topicstring · nullableRequired

The site topic ID associated with the finding. It is null for findings that are not associated with a current topic in the site.

titlestring · max: 256Required

Short finding title

changeRequestsnumberRequired

Number of change requests linked to the finding

pagesnumberRequired

Number of pages linked to the finding

recordsnumberRequired

Number of records linked to the finding

questionsnumberRequired

Number of questions linked to the finding

statusstring · enumRequired

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:
typestring · enumRequired

Classification of a site finding:

  • Outdated content: The content was correct but is no longer up to date with external context and may be misleading or incorrect.
  • Incorrect content: The content is factually wrong or misleading, leading users astray regardless of whether it was ever correct.
  • Content gap: The content is missing important information that should be present to answer user questions effectively.
  • Broken link: A URL on the site returns a 404, and can be resolved by creating a redirect or a new page.
  • Outbound link error: An external URL used by the site's content fails to resolve, and can be fixed by replacing or removing the link.
  • Other: Any other type of finding not covered by the above categories.
Possible values:
severitystring · enumRequired

Estimated end-user severity of a site finding.

Possible values:
autoFixablebooleanRequired

Whether an AI agent should be able to fix this finding directly

autoResolutionstring · enum · nullableRequired

What GitBook did on its own to resolve the finding. Null when it never acted on the finding.

Possible values:
statestring · enumOptional

Where a link finding stands, from its status and what GitBook did with it.

  • open needs a fix.
  • awaiting-approval has a fix GitBook drafted, waiting to be approved or rejected: a redirect at a broken-link finding's path, or an unmerged change request for an outbound-link-error finding (awaitingChangeRequest).
  • resolved was fixed or closed: servingRedirect says whether a live redirect serves its path.
  • ignored was dismissed.
Possible values:
createdAtstring · date-timeRequired
updatedAtstring · date-timeRequired
post/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/actions
POST /v1/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/actions HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "action": "approve"
}
200

Action applied

{
  "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",
  "state": "open",
  "servingRedirect": {
    "redirect": "text",
    "wildcard": true,
    "createdByAgent": true
  },
  "awaitingChangeRequest": {
    "space": "text",
    "changeRequest": "text",
    "findings": 1
  },
  "actions": [
    {
      "action": "approve",
      "permission": "edit"
    }
  ],
  "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"
  }
}

Last updated

Was this helpful?

Powered by GitBook