API quickstart

Create an API key, then use it to read who you are and list your open findings over REST.

Create a key

In the app, switch to the workspace you want the key to read. A key belongs to the workspace that is active when you create it, and it reads only that workspace.

Open Settings → Developer and click Create key.

Enter a key name, tick View findings, and click Create.

Copy the key, which starts with v12p_. The dialog warns: "This secret is shown once. Copy it now." Then click Done.

Create an API key covers the dialog, and Scopes explains what each scope allows.

Call the API

Put the key in V12_API_TOKEN and ask the API who you are. Any valid key may make this call, whatever its scopes:

export V12_API_TOKEN=v12p_…   # from your secret store, never committed
curl -s -H "Authorization: Bearer $V12_API_TOKEN" https://v12.sh/api/v2/me

{
  "user": { "username": "you", "email": "[email protected]" },
  "organization": { "slug": "acme", "name": "Acme", "personal": false },
  "token": { "kind": "pat", "scopes": ["findings:read"] },
  "credits": { "balanceCents": 0, "monthlyCapCents": null }
}

user is the person who created the key.
organization is the workspace the key reads; personal is true for a personal workspace. Its slug is the workspace's address: every other REST path starts with https://v12.sh/api/v2/orgs/<slug>. It is also the first part of the workspace's pages in the app, v12.sh/acme/….
token.kind is pat for an API key and oauth for a token an app got by signing in. token.scopes lists what the key may do.
credits holds the workspace's credit balance and its monthly spending limit, in cents. It is null unless your role lets you see billing.

Then put the slug in V12_ORG and list the five newest open findings across the workspace's repositories:

export V12_ORG=acme   # organization.slug from /me
curl -s -H "Authorization: Bearer $V12_API_TOKEN" "https://v12.sh/api/v2/orgs/$V12_ORG/findings?status=open&limit=5"

The response has four parts you will use most:

items: the findings. Each has a number, a display key such as F-42, a title, severity, status, and a webUrl such as https://v12.sh/acme/findings/42 that opens it in the app. Address a finding by its key or its number: /orgs/$V12_ORG/findings/F-42.
nextCursor: send it back as cursor for the next page; it is null on the last page. See Pagination.
counts: how many findings are in each status and severity, before your filters and without dismissed findings.
total: how many findings match your filters, across all pages.

Keep the key safe

Keep the key in a secret manager or a CI secret, never in code or a repository.
A key made in Settings has no expiry. It stops working when you revoke it, and when you change or reset your password, which revokes all your keys. Revoke keys you no longer use.
To change a key's secret, follow Replace a key. To use it in a pipeline, see Use in CI.

Recipes: triage the inbox and start a run within a price limit.
Connect an MCP client: give an AI assistant the same access.
REST reference: every endpoint, its parameters and its errors.

API quickstart

Create a key

Call the API

Keep the key safe

Next

On this page