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. personal is true for a personal workspace. slug is the workspace's address: every other REST path starts with https://v12.sh/api/v2/orgs/<slug>, and its pages in the app start with v12.sh/acme/….
  • token: kind is pat for an API key and oauth for a token an app got by signing in. scopes lists what the key may do.
  • credits: the workspace's credit balance and 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's main fields:

  • 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: 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

On this page