REST reference

The REST API lives under https://v12.sh/api/v2/orgs/<org>, where <org> is the slug of the workspace your token reads. Only GET https://v12.sh/api/v2/me and the OpenAPI document sit outside it. Addresses explains slugs and how to name findings, runs and repositories. 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.

None required in an operation's scopes means any valid token can call it, as with GET /me; it does not remove the token requirement.

Requests

• Paths below are relative to https://v12.sh/api/v2. {org} is organization.slug from GET /me; another workspace's slug gets 404 not_found.
• {repository} is two path segments, owner/name: its slug or full name, as in /orgs/acme/repositories/acme/api/findings.
• {finding} is a finding key, such as F-42, or its number, 42. {run} is the run's number in the workspace. {link} is a guest link's number in that run.
• repository and at go in the query string on every GET that takes them, and on the two finding PATCH operations. A comment's POST takes them in its JSON body.
• Query lists are comma-separated: status=open,fixed. A repeated list parameter adds its values, so status=open&status=fixed means the same; repeating a single-value parameter, such as limit, returns 400 invalid_request.
• 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 this body. details is optional. 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"
}

Me

Get the token identity

GET /me · operationId getMe · Scopes: None required · MCP tool get_me

The user, organization and scopes behind this credential, plus the organization credit balance when the user may view billing. Any valid token may read it; organization.slug addresses every other endpoint.

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

Members

List organization members

GET /orgs/{org}/members · operationId listMembers · Scopes: user:read · MCP tool list_members

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

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

Steers

List Steers

GET /orgs/{org}/steers · operationId listSteers · Scopes: repos:read · MCP tool list_steers

Organization-wide Steer documents that guide runs and Autopilot rules. Lists active Steers by default; archived: true lists only archived Steers.

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

Create a Steer

POST /orgs/{org}/steers · operationId createSteer · Scopes: steers:write · MCP tool create_steer

Create an organization Steer with a title, emoji and instructions. The returned slug is its stable address. Repeating this request creates another Steer; it does not attach to Autopilot rules.

Returns 201 with slug, title, emoji, archivedAt, webUrl, instructions. Errors: 400, 401, 403, 404, 405, 409, 413, 415, 429, 500, 503 (Errors).

Get a Steer

GET /orgs/{org}/steers/{steer} · operationId getSteer · Scopes: repos:read · MCP tool get_steer

One active or archived Steer by slug, including its instructions and archive status. Archived Steers remain readable for historical references.

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

Edit a Steer

PATCH /orgs/{org}/steers/{steer} · operationId updateSteer · Scopes: steers:write · MCP tool update_steer

Update the supplied fields of an active Steer, preserving omitted fields and its slug. Runs already started keep the instructions they started with. Restore an archived Steer before editing it.

Returns 200 with slug, title, emoji, archivedAt, webUrl, instructions. Errors: 400, 401, 403, 404, 405, 409, 413, 415, 429, 500, 503 (Errors).

Archive a Steer

DELETE /orgs/{org}/steers/{steer} · operationId archiveSteer · Scopes: steers:write · MCP tool archive_steer

Archive a Steer and detach it from every Autopilot rule. Rules keep their active or paused state; a rule with no remaining Steers uses its default review. New runs refuse the Steer, while finding tags and queued, running and completed run snapshots remain intact. Repeating archive is safe.

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

Restore a Steer

POST /orgs/{org}/steers/{steer}/restore · operationId restoreSteer · Scopes: steers:write · MCP tool restore_steer

Make an archived Steer available for edits and new runs again, keeping its slug. Former Autopilot attachments are not restored; add them again separately. Repeating restore is safe.

Returns 200 with slug, title, emoji, archivedAt, webUrl, instructions. Errors: 400, 401, 403, 404, 405, 409, 413, 415, 429, 500, 503 (Errors).

Repositories

List repositories

GET /orgs/{org}/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, 405, 409, 429, 500, 503 (Errors).

Add a repository

POST /orgs/{org}/repositories · operationId addRepository · Scopes: repos:write · MCP tool add_repository

Add a GitHub repository to this organization. Members can add public repositories; private repositories must be granted by the workspace GitHub connection and added by an owner. Repeating an add returns the existing registration. A "v12/<name>" names a repository V12 hosts, never one on GitHub: it returns that registration, or not_found. This does not start a run.

Returns 200, 201 with added, tracking, repository. Errors: 400, 401, 403, 404, 405, 409, 413, 415, 429, 500, 503 (Errors).

Get a repository

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

One registered repository by its slug or full name ("owner/name").

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

List branches, pull requests and tags

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

Branches, pull requests and tags V12 has mirrored for a repository, with whether each head was reviewed. Each list stops at limit (default 100, max 200): truncated says which may hold more and branchCount counts every matching branch. Not paginated; narrow with q. mirror is the repository's sync state.

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

Create a hosted repository

POST /orgs/{org}/repositories/hosted · operationId createHostedRepository · Scopes: repos:write · MCP tool create_hosted_repository

Create an empty Git repository that V12 hosts. It answers to "v12/<name>", and to the slug in the response. Push code to it with a URL from create_push_credential, the default branch first: V12 does not enforce that, but until it exists, finding reads and full reviews at the default position answer 409 position_unavailable. V12 imports each push. Only owners may create one. A name already in use, or whose "v12/<name>" is another repository's slug, is a conflict. This does not start a run.

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

Get a push URL for a hosted repository

POST /orgs/{org}/repositories/{owner}/{repo}/push-credentials · operationId createPushCredential · Scopes: repos:write · MCP tool create_push_credential

A Git remote URL that can push to one branch of a repository V12 hosts, valid for one hour. Push with `git -c credential.helper= push <url> HEAD:<branch>`: the empty helper keeps Git from saving the credential. The URL is the credential; treat it as a secret. Only owners may get one, and GitHub repositories have none. V12 does not make you push the default branch first, but until it exists, finding reads and full reviews at the default position, and branch changes without since, answer 409 position_unavailable.

Returns 201 with branch, url, expiresAt. Errors: 400, 401, 403, 404, 405, 409, 413, 415, 429, 500, 503 (Errors).

Findings

List a repository's findings at a position

GET /orgs/{org}/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. Highest finding number first; counts are before filters, total after.

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

List organization findings

GET /orgs/{org}/findings · operationId listFindings · Scopes: findings:read · MCP tool list_findings

Findings across every registered repository at its default branch head, highest finding number first (numbers grow as findings are created; firstObservedAt can be older). counts covers every finding before filters; total counts the filtered result. unavailableRepositories lists the slugs of repositories whose default branch V12 cannot read; list_repository_findings on one says why.

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

Change findings

PATCH /orgs/{org}/findings · operationId updateFindings · Scopes: findings:write · MCP tool update_findings

Apply one change to up to 100 findings: status, severity, or assignee. fixed and open are recorded at a commit (the default branch head unless repository/at say otherwise) and carry forward to later commits while the affected files are unchanged; false-positive marks the finding's reports and shows at every commit that has them; investigating and wont-fix apply everywhere. repository and at also locate findings that exist only off the default branch, such as ones a change review reported (send each position.at that list_run_findings reports with its repository): for investigating, wont-fix, severity and assignee they only locate the findings, and the change still applies everywhere. Findings already in the requested state are left unchanged and listed in skipped.

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

Get a finding

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

One finding with its reports (each report's analysis, proof of concept and fix are in reports[].analysis), evidence and activity. Comments are activity entries of kind "comment"; their id is the replyTo for comment_on_finding. A false-positive change shows in status, not in activity. With at, code state and status are read at that commit. Send a returned position.at with its repositories[i].repository; without repository, inference reports repository_required if several registered repositories hold the finding at that position. A finding on no default branch answers not_found unless you send at.

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

Change a finding

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

Apply one change to a finding: status, severity, or assignee. repository and at locate a finding that exists only off the default branch, such as one a change review reported: for investigating, wont-fix, severity and assignee they only locate it, and the change still applies everywhere. A change that would not alter the finding leaves it unchanged and lists it in skipped.

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

Comment on a finding

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

Add a comment, or a reply to one, to a finding. A finding that exists only off the default branch, such as one a change review reported, needs repository and at (a position.at that list_run_findings reports); the comment belongs to the finding everywhere.

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

Runs

List runs

GET /orgs/{org}/runs · operationId listRuns · Scopes: runs:read · MCP tool list_runs

Runs of the organization, newest first. state filters raw states (failed alone misses compilation_failed and analysis_failed); phase filters the phase each run reports. With phase, a page can hold fewer than limit items: keep following nextCursor.

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

Start a run

POST /orgs/{org}/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 original response with replayed: true. A replay, or a start refused before billing (an invalid or expired quote, its repository, a price above maxPriceCents, its documents), spends nothing from the start limit; a start that reaches billing counts even when it is refused there, as when its quoted change or commit has moved (quote_stale). Without a quote, the estimate the start makes counts toward the estimate limit.

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

Get a run

GET /orgs/{org}/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. import.count counts the run's reports; a report can join an existing finding, whose status (for example a won't-fix decision) then applies.

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

List a run's findings

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

Findings a completed run added to the inbox, positioned at each repository's analyzed commit; send position.at together with its repositories[i].repository for positioned reads. Without repository, inference reports repository_required if several registered repositories hold the finding at that position. Status and codeState describe that commit, not today's default head. 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. A finding can predate the run: runs lists every run that reported it.

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

Estimate a run

POST /orgs/{org}/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. targets[].paths (or change.paths) lists up to 500 in-scope paths.

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

Cancel a run

POST /orgs/{org}/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, 405, 409, 413, 415, 429, 500, 503 (Errors).

List guest links

GET /orgs/{org}/runs/{run}/links · operationId listRunLinks · Scopes: runs:share · MCP tool list_run_links

A run's guest links, newest first, with their number, role, state and guest count. A link's number addresses it within the run. The full URL is never listed; urlPrefix helps recognise a link.

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

Create a guest link

POST /orgs/{org}/runs/{run}/links · operationId createRunLink · Scopes: runs:share, findings:read · MCP tool create_run_link

Create a link that opens this run to people outside the organization, without an account. Links are numbered 1, 2, 3… within the run, and a number is never reused. The API returns the full URL only in this response; owners can copy a live link again from the run's Share dialog. Works on any run but a draft, including one still running or with no findings.

Returns 201 with link, url. Errors: 400, 401, 403, 404, 405, 409, 413, 415, 429, 500, 503 (Errors).

Change a guest link

PATCH /orgs/{org}/runs/{run}/links/{link} · operationId updateRunLink · Scopes: runs:share, findings:read · MCP tool update_run_link

Change a link's role, label or expiry (days from now), by run number and link number. A new expiry revives an expired link, within the live-link cap. A revoked link cannot change.

Returns 200 with link. Errors: 400, 401, 403, 404, 405, 409, 413, 415, 429, 500, 503 (Errors).

Revoke a guest link

DELETE /orgs/{org}/runs/{run}/links/{link} · operationId revokeRunLink · Scopes: runs:share · MCP tool revoke_run_link

End a link now, by run number and link number; anyone using it loses access at their next request. Revoking twice returns the same link.

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

Documents

Request a document upload slot

POST /orgs/{org}/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. Types: PDF, Markdown, text, JSON, DOCX, CSV.

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

Create a context document

POST /orgs/{org}/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 with its original title (created: false); if that document was archived, this restores it (restored: true). An upload slot works once.

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

List context documents

GET /orgs/{org}/documents · operationId listDocuments · Scopes: runs:read · MCP tool list_documents

Context documents of the organization, newest first. Archived documents are left out unless archived: true, which lists them beside the active ones. With repository, documents used by earlier runs on that repository come first and have recommended: true; it ranks, it does not filter.

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

Get a context document

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

One context document by id.

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

Archive a context document

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

Archive a document so new runs refuse it (estimate_run and start_run answer conflict). Creating identical content again restores it. Only its creator or an owner may archive it.

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