Report findings on trails

A plugin registered with findings:write can publish findings on a trail: comments tied to a line, a range, a file or the whole change, each with an optional severity and confidence. For example, a security scanner starts a review when a trail opens or updates, publishes what it found, and resolves each finding once a later push fixes it. Findings appear on the trail’s diff next to the code they’re about.

Trail findings are experimental. Field names may change before the contract is final.

What you need

findings:write, on your plugin’s installation token. Ask Entire to add it when you register your plugin. It also lets you read findings, but grants no repository read or push access.
contents:read, to read the code you’re reviewing and receive trail events. The token you write findings with doesn’t need it.
An access token scoped to the repository for writing findings. Mint it with this body:
{"repository_id": "repo_01M3...", "permissions": {"findings": "write"}}

Send every call below to the repository’s api_base_url, under /api/v1, with the access token as bearer token. Trails must be enabled on the repository.

Start a review

Findings belong to a review. Start one for the commit you analyzed:

POST /api/v1/repos/{repo_id}/trails/{number}/reviews
Content-Type: application/json
Idempotency-Key: scan-4f2a9c1e

{"head_sha": "4f2a9c1e..."}

Every body field is optional. head_sha and base_sha are full 40-character SHAs; the trail’s current head and base fill whichever you omit. Pass the head_sha you analyzed so your findings attach to that code, even if someone pushes while you work. A 201 returns the review:

{"review_id": "01K...", "trail_id": "...", "repo_id": "repo_01M3...", "code_version_id": "...", "base_sha": "...", "head_sha": "4f2a9c1e...", "limits": {"max_comments_per_batch": 100}, ...}

Store review_id. Only your installation can publish to that review or change its findings.

Publish findings

Publish your findings on the review, with an optional summary:

POST /api/v1/repos/{repo_id}/trails/{number}/reviews/{review_id}/comments
Content-Type: application/json
Idempotency-Key: scan-4f2a9c1e-publish

{
  "summary": "1 high-severity issue in 12 files scanned.",
  "comments": [{
    "client_id": "sql-injection:api/users.go:42",
    "body": "User input reaches this query unescaped. Use a parameterized query.",
    "severity": "high",
    "confidence": 0.9,
    "location": {
      "granularity": "line",
      "file_path": "api/users.go",
      "start_line": 42,
      "selected_text": "db.Query(\"SELECT * FROM users WHERE id = \" + id)"
    }
  }]
}

The whole request applies or none of it does. It also marks the review complete, so publish everything you found for that commit in one request. To report no findings, send an empty comments array, with a summary if you like.

Field	Required	Notes
`comments`	No	Up to 100 findings.
`summary`	No	Your review’s overall summary, in Markdown. `null` clears it.
`client_id`	Yes	Your stable ID for the finding, unique in the request, up to 255 characters.
`body`	No	The finding, in Markdown, up to 65,536 characters.
`severity`	No	`high`, `medium` or `low`.
`confidence`	No	A number from 0 to 1.
`status`	No	`open` (the default), `resolved` or `dismissed`.
`status_reason`	No	Why the finding was resolved or dismissed, up to 4,096 characters.
`location`	Yes	Where the finding applies. See below.
`suggested_change`	No	A proposed fix. `change_type` is `unified_diff`, `file_replacement`, `json_patch` or `manual_instruction`.

location.granularity decides what else location needs:

`granularity`	Also requires
`line`	`file_path`, `start_line` (from 1) and `selected_text`, the text on that line.
`range`	The same, plus `end_line`, no less than `start_line`.
`file`	`file_path`.
`whole_change`	Nothing.

start_column, end_column, nearby_text and language are optional. selected_text and nearby_text help keep a finding attached to its code as the trail changes. The response has the completed review and one result per finding, in request order:

{"review": {"id": "01K...", "summary": "...", "completed_at": "2026-11-09T10:04:00Z", ...}, "results": [{"client_id": "sql-injection:api/users.go:42", "status": "created", "comment": {"id": "01K...", "status": "open", ...}}]}

Store each comment.id with its client_id. You need the ID to resolve the finding later.

Retry safely

Send an Idempotency-Key header with both requests. Retrying with the same key and body returns the first response rather than starting a second review or publishing twice. client_id protects each finding as well. Publishing a client_id the review already has, with the same payload, returns it with status existing instead of creating a duplicate. The same client_id with a different payload fails the request.

Keep findings current

Update a finding when its state changes, such as when a later push fixes it:

PATCH /api/v1/repos/{repo_id}/trails/{number}/reviews/{review_id}/comments/{comment_id}
Content-Type: application/json

{"status": "resolved", "status_reason": "Fixed in 9b7d3e0: the query is now parameterized."}

Send only the fields you’re changing: body, severity, confidence, status or status_reason. Moving a finding to resolved or dismissed requires a non-empty status_reason. Set status back to open to reopen it. When someone pushes new code, start a new review for the new head rather than adding to an earlier one. A finding tied to code that has since changed can become stale. It keeps its status, but lists of current findings leave it out.

Read findings

List the trail’s findings with GET /api/v1/repos/{repo_id}/trails/{number}/reviews/comments. The list includes other reviewers’ findings, so match on your stored review_id to find yours. By default it returns current findings that aren’t dismissed. Filter with ?status=, ?severity= and ?stale=current|stale|any. While the response has a next_cursor, pass it back as ?cursor= for the next page.

Findings and merge gates

Findings your plugin publishes don’t count toward a trail’s Agent review gate, whatever their severity, and never block a merge. To block a merge on your results, also report checks, which needs checks:write. Your plugin’s check gate blocks merging by default; see the plugin gate rules and Review and require checks.

What findings:write doesn’t cover

Changing findings on a review another installation or a person started. Those return 404.
Approving a trail, or posting trail comments, which need other permissions.

Errors

Errors are application/problem+json. For errors when minting the token, see Access repositories.

Status and detail	Meaning
`403 no publish access to repo`	Starting a review or publishing findings without `findings:write` on this repository. The same answer covers a repository that doesn’t exist.
`403 no findings write access to repo`	Updating a finding without `findings:write`.
`404 repository not found`	Trails aren’t enabled on the repository.
`404 Review not found`	The review doesn’t belong to this trail, or another installation or a person started it.
`404 Review comment not found`	The finding doesn’t exist on this review, or it’s on a review you didn’t start.
`409 review comments batch failed atomically`	A finding couldn’t be stored, such as a reused `client_id` with a different payload. Nothing in the request was saved.
`409 Idempotency-Key already used with a different request body`	Use a new key for a different request.
`409 request in flight, retry shortly`	A request with the same `Idempotency-Key` is still running. Retry it unchanged.
`409 Change comparison moved while starting the review; retry`	Someone pushed while you started the review. Retry.
`400`	A field is invalid or a `location` is missing a required field. The `detail` names which.

Start

Build

Integrate

Report findings on trails

What you need

Start a review

Publish findings

Retry safely

Keep findings current

Read findings

Findings and merge gates

What findings:write doesn’t cover

Errors

​What you need

​Start a review

​Publish findings

​Retry safely

​Keep findings current

​Read findings

​Findings and merge gates

​What findings:write doesn’t cover

​Errors

What you need

Start a review

Publish findings

Retry safely

Keep findings current

Read findings

Findings and merge gates

What findings:write doesn’t cover

Errors