API quickstart
Create an API key and make your first REST calls.
Create an API key, then use it over REST to read who you are and list your workspace's open findings.
Create a key
In the app, switch to the workspace the key should read. A key reads only the workspace that is active when you create it.
Open Settings → Developer and click Create key.
Enter a 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.
For the dialog in detail, see Create an API key. For what each scope allows, see Scopes.
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: the person who created the key.organization: the workspace the key reads.personalistruefor a personal workspace.slugis the workspace's address: every other REST path starts withhttps://v12.sh/, and its pages in the app start withapi/ v2/ orgs/ <slug> v12.sh/acme/….token:kindispatfor an API key andoauthfor a token an app got by signing in.scopeslists what the key may do.credits: the workspace's credit balance and monthly spending limit, in cents. It isnullunless 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's main fields:
items: the findings. Each has anumber, a displaykeysuch asF-42, atitle,severity,status, and awebUrlsuch ashttps://v12.sh/that opens it in the app. Address a finding by its key or its number:acme/ findings/ 42 /orgs/.$V12_ORG/ findings/ F-42 nextCursor: send it back ascursorfor the next page. It isnullon the last page. See Pagination.counts: findings per status and severity, before your filters.total: findings that match your filters, across all pages.
Keep the key safe
- Store 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, or when you change or reset your password, which revokes all your keys. Revoke keys you no longer use.
- To change a key's secret, see Replace a key. To use it in a pipeline, see Use in CI.
Next
- 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.