REST reference

The REST API lives at https://v12.sh/api/v2 and acts on the workspace your token reads; Authentication and permissions covers API keys, OAuth and scopes. The OpenAPI 3.1 document is public, needs no token and may be cached for five minutes: https://v12.sh/api/v2/openapi.json.

Requests

• {repository} in a path is two segments, owner/name: /repositories/acme/api/findings.
• repository and at go in the query string on every GET that takes them, and on both PATCH operations.
• Query lists are comma-separated: status=open,fixed.
• Other POST and PATCH fields go in a JSON body with Content-Type: application/json; any other type returns 415.
• Bodies are limited to 1 MiB; a larger one returns 413.

Errors

Every error response has the same body. details is optional, and requestId matches the X-Request-Id response header; include it when you ask for help.

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid.",
    "details": { "issues": [{ "path": "limit", "message": "Too big: expected number to be <=100" }] }
  },
  "requestId": "e3fbc6dc-1c5e-4b2d-b998-e820319d6cf7"
}

platform_unavailable (503) means V12's findings service answered 429, 502, 503 or 504, or did not answer. When the service said when to retry, the response carries Retry-After and the same seconds in details.retryAfterSeconds. A 500 from that service reaches you as internal_error (500).

Me

Get the token identity

GET /me · operationId getMe · Scopes: user:read · MCP tool get_me

The user, organization and scopes behind this credential, plus the organization credit balance when the user may view billing.

Returns 200 with user, organization, token, credits. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

Members

List organization members

GET /members · operationId listMembers · Scopes: user:read · MCP tool list_members

Members of the token organization, sorted by username, then id. Use a member id, email or username to assign findings.

Returns 200 with nextCursor, items. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

Focuses

List focuses

GET /focuses · operationId listFocuses · Scopes: repos:read · MCP tool list_focuses

Organization-wide focus documents that steer runs and Autopilot rules.

Returns 200 with nextCursor, items. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

Get a focus

GET /focuses/{focus} · operationId getFocus · Scopes: repos:read · MCP tool get_focus

One focus by slug, including the instructions its runs follow.

Returns 200 with slug, title, emoji, revision, webUrl, instructions. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

Repositories

List repositories

GET /repositories · operationId listRepositories · Scopes: repos:read · MCP tool list_repositories

Repositories registered in the organization, sorted by full name, with their GitHub access and mirror state.

Returns 200 with nextCursor, items. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

Get a repository

GET /repositories/{owner}/{repo} · operationId getRepository · Scopes: repos:read · REST only

One registered repository by "owner/name".

Returns 200 with id, fullName, defaultBranch, access, mirror, webUrl. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

List branches, pull requests and tags

GET /repositories/{owner}/{repo}/refs · operationId listRefs · Scopes: repos:read · MCP tool list_refs

Refs V12 has mirrored for a repository, with whether each head was reviewed. Not paginated; narrow the list with q.

Returns 200 with defaultBranch, branches, pullRequests, tags, asOf, nextCursor. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

Findings

List a repository's findings at a position

GET /repositories/{owner}/{repo}/findings · operationId listRepositoryFindings · Scopes: findings:read · MCP tool list_repository_findings

The repository inbox at one commit: every finding with its code state there. Without at, the default branch head. The response pins the evaluated commit in position.at; later pages stay on it.

Returns 200 with nextCursor, items, repository, position, reviewCoverage, counts, total, asOf. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

List organization findings

GET /findings · operationId listFindings · Scopes: findings:read · MCP tool list_findings

Findings across every registered repository at its default branch head, newest first.

Returns 200 with nextCursor, items, counts, total, asOf, unavailableRepositories. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

Change findings

PATCH /findings · operationId updateFindings · Scopes: findings:write · MCP tool update_findings

Apply one change to up to 100 findings: status (with reason), severity, assignee, or dismissal (with reason). open, fixed and false-positive are recorded per commit, at the default branch head unless repository/at say otherwise. Findings already in the requested state are skipped.

Returns 200 with findings, asOf. Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (Errors).

Get a finding

GET /findings/{finding} · operationId getFinding · Scopes: findings:read · MCP tool get_finding

One finding with its reports, analysis, evidence, activity and comments. With at, code state and status are read at that commit.

Returns 200 with id, key, title, severity, status, investigating, decision, duplicateOf, dismissed, assignee, focus, firstObservedAt, reportCount, sources, runs, repositories, webUrl, description, reports, evidence, activity, related, asOf. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

Change a finding

PATCH /findings/{finding} · operationId updateFinding · Scopes: findings:write · REST only

Apply one change to a finding: status (with reason), severity, assignee, or dismissal. A change that would not alter the finding is skipped.

Returns 200 with findings, asOf. Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (Errors).

Comment on a finding

POST /findings/{finding}/comments · operationId commentOnFinding · Scopes: findings:write · MCP tool comment_on_finding

Add a comment, or a reply to one, to a finding.

Returns 201 with comment. Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (Errors).

Runs

List runs

GET /runs · operationId listRuns · Scopes: runs:read · MCP tool list_runs

Runs of the organization, newest first.

Returns 200 with nextCursor, items. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

Start a run

POST /runs · operationId startRun · Scopes: runs:write · MCP tool start_run

Start a paid run. Send the quote from estimate_run and a maxPriceCents the user approved; the run is refused when its price exceeds it. A repeated Idempotency-Key (REST) or requestId (MCP) returns the run it started.

Returns 200, 201 with run, priceCents. Errors: 400, 401, 402, 403, 404, 409, 413, 415, 429, 503 (Errors).

Get a run

GET /runs/{run} · operationId getRun · Scopes: runs:read · MCP tool get_run

One run with its stages, progress, cost and finding import state. A failed or partial import says why in import.reason and on the inbox stage.

Returns 200 with id, title, state, phase, terminal, createdAt, startedAt, endedAt, repository, ref, sha, extraRepositories, retryOf, trigger, costCents, findings, error, webUrl, kind, cancellationRequested, focuses, change, repositories, stage, stages, import, publicUrl, pullRequestCommentUrl. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

List a run's findings

GET /runs/{run}/findings · operationId listRunFindings · Scopes: runs:read, findings:read · MCP tool list_run_findings

Findings a completed run added to the inbox. Empty until import.state is "imported" or "partial"; a partial import lists only the findings that reached the inbox, and import.reason says why the rest did not.

Returns 200 with nextCursor, items, import, asOf. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

Estimate a run

POST /runs/estimate · operationId estimateRun · Scopes: runs:write · MCP tool estimate_run

Price a full review (at) or a change review (change) without starting it. Returns a quote to pass to start_run within 15 minutes.

Returns 200 with kind, priceCents, balanceCents, targets, focusRevisions, change, quote, expiresAt. Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (Errors).

Cancel a run

POST /runs/{run}/cancel · operationId cancelRun · Scopes: runs:manage · MCP tool cancel_run

Cancel a queued or running run. A run that has already started stops at its next checkpoint (result "cancelling").

Returns 200 with run, result. Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (Errors).

Documents

Request a document upload slot

POST /documents/uploads · operationId requestDocumentUpload · Scopes: runs:write · MCP tool request_document_upload

Get a URL to PUT a file to (up to 50 MiB, valid 10 minutes), then call create_document with the slot id.

Returns 201 with upload. Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (Errors).

Create a context document

POST /documents · operationId createDocument · Scopes: runs:write · MCP tool create_document

Add a context document runs can read: an uploaded file ({ upload }) or a text note ({ note }). Identical content returns the existing document.

Returns 201 with document. Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503 (Errors).

List context documents

GET /documents · operationId listDocuments · Scopes: runs:read · MCP tool list_documents

Context documents of the organization, optionally those used with a repository.

Returns 200 with nextCursor, items. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

Get a context document

GET /documents/{document} · operationId getDocument · Scopes: runs:read · REST only

One context document by id.

Returns 200 with document. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).

Archive a context document

DELETE /documents/{document} · operationId archiveDocument · Scopes: runs:write · MCP tool archive_document

Archive a document so new runs stop using it. Only its creator or an owner may archive it.

Returns 200 with document. Errors: 400, 401, 403, 404, 409, 429, 503 (Errors).