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.
A unique entity identifier
^[a-zA-Z0-9_-]+$The unique id of the site
The unique id of the site finding
An action that moves a finding to another state. A finding's actions lists the ones it allows.
approvemakes 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.rejectdeletes 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, markedundone, and GitBook won't draft a fix for them again.create-redirectcreates a redirect for a broken link's path withcreateSiteRedirect, prefilled with the suggestion; it resolves the finding.mark-resolvedresolves it. A broken link resolved this way has no redirect: visitors still get a 404.reopenreopens 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.ignoredismisses it.restorereopens a dismissed finding.
Action applied
The ID of the finding
The site scan ID associated with the finding
The site topic ID associated with the finding. It is null for findings that are not associated with a current topic in the site.
Short finding title
Number of change requests linked to the finding
Number of pages linked to the finding
Number of records linked to the finding
Number of questions linked to the finding
Status of a site finding.
candidateis a finding that has been raised but not yet confirmed. Typically these are not shown to users.openis a finding that has been surfaced to users and is still under investigation.doneis a finding that has been resolved and is no longer under investigation.canceledis a finding that has been canceled and is no longer under investigation.
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.
Estimated end-user severity of a site finding.
Whether an AI agent should be able to fix this finding directly
What GitBook did on its own to resolve the finding. Null when it never acted on the finding.
Where a link finding stands, from its status and what GitBook did with it.
openneeds a fix.awaiting-approvalhas a fix GitBook drafted, waiting to be approved or rejected: a redirect at abroken-linkfinding's path, or an unmerged change request for anoutbound-link-errorfinding (awaitingChangeRequest).resolvedwas fixed or closed:servingRedirectsays whether a live redirect serves its path.ignoredwas dismissed.
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"
}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?