API reference — Documentation

The Provenova REST API. All responses are JSON. Authenticate with an API key as a bearer token — create one under Settings → API keys:

Shell

export QL_TOKEN=ql_live_...
curl https://provenova.net/api/v1/me -H "Authorization: Bearer $QL_TOKEN"

Ingest

POST/api/v1/ingest/runs

Ingest a run bundle from the SDK. Idempotent by run_hash — re-sending the same run returns "status": "exists" with the original run_id.

cURL

curl -X POST https://provenova.net/api/v1/ingest/runs \
  -H "Authorization: Bearer $QL_TOKEN" \
  -H "Content-Type: application/json" \
  --data @run.qlprov.json

Response

{
  "status": "created",
  "run_id": "01J...",
  "run_hash": "b3f1...e9",
  "hash_matched_client": true
}

Runs

GET/api/v1/runs

List runs in your workspace, most recent first.

cURL

curl https://provenova.net/api/v1/runs \
  -H "Authorization: Bearer $QL_TOKEN"

Response

[
  { "id": "01J...", "project": "bell-demo", "vendor": "ibm", "backend": "ibm_kyiv", "shots": 4096, "status": "completed", "run_hash": "b3f1...e9", "created_at": "2026-07-03T12:00:00+00:00" }
]

GET/api/v1/runs/{run_id}

Fetch the full provenance document (qlprov/run/1.0) for a run. Verifies its own hash offline.

cURL

curl https://provenova.net/api/v1/runs/01J... \
  -H "Authorization: Bearer $QL_TOKEN"

POST/api/v1/runs/{run_id}/card/mint-doi

Mint doi

POST/api/v1/runs/{run_id}/card/publish

Publish a run as a public, citable Result Card with provenance and badges.

POST/api/v1/runs/{run_id}/card/unpublish

Unpublish

GET/api/v1/runs/{run_id}/report

Run report

POST/api/v1/runs/{run_id}/reproduce

Re-run the stored circuit against a drifted device state and score the result.

cURL

curl -X POST "https://provenova.net/api/v1/runs/01J.../reproduce?days=90&profile=bad_day" \
  -H "Authorization: Bearer $QL_TOKEN"

Response

{
  "reproduced_run_id": "01K...",
  "verdict": "drifted",
  "reproducibility_score": 0.947,
  "report": { ... }
}

Result cards

GET/api/v1/cards/{slug}

Public Result Card metadata as JSON (no auth required).

cURL

curl https://provenova.net/api/v1/cards/ghz-3-ibm-kyiv

GET/api/v1/cards/{slug}/citation

Ready-made citation for a card in BibTeX, CSL-JSON or RIS (?format=bibtex|csl|ris).

GET/api/v1/cards/{slug}/embed

Card embed

POST/api/v1/cards/{slug}/reproductions

Submit reproduction

Badges

GET/badge/{slug}/{badge_type}.json

Badge json

GET/badge/{slug}/{badge_type}.svg

Badge svg

Corpus & leaderboard

GET/api/v1/backends/{provider}/{backend_id}/trend

Device trend

GET/api/v1/leaderboard

Cross-vendor hardware ranking by a calibration metric (?metric=median_2q_error|...).

cURL

curl https://provenova.net/api/v1/leaderboard?metric=median_2q_error

Compliance

GET/api/v1/frameworks

List frameworks

GET/api/v1/frameworks/{fw_id}

Get framework

POST/api/v1/workspaces/{ws_id}/attestations

Issue an Ed25519-signed attestation over the collected evidence for a framework.

GET/api/v1/workspaces/{ws_id}/compliance

Status

POST/api/v1/workspaces/{ws_id}/compliance/evaluate

Evaluate every enabled framework against the workspace's runs. Safe to call repeatedly.

POST/api/v1/workspaces/{ws_id}/frameworks/{fw_id}/enable

Enable

GET/api/v1/workspaces/{ws_id}/gaps

Gaps

Attestations

GET/.well-known/provenova-jwks.json

Public JWKS for verifying attestation signatures yourself.

GET/.well-known/quantumledger-jwks.json

Jwks

GET/.well-known/security.txt

Security txt

POST/api/v1/attestations/{att_id}/revoke

Revoke

GET/api/v1/attestations/{att_id}/verify

Verify an attestation's signature and evidence root (public — no auth).

cURL

curl https://provenova.net/api/v1/attestations/01J.../verify

Response

{
  "attestation_id": "01J...",
  "kid": "ql-att-...",
  "evidence_root": "9c2a...f0",
  "valid": true,
  "checks": { "signature": true, "expired": false, "revoked": false, "tampered": false },
  "reason": null
}

Trust center

GET/api/v1/trust/{org_slug}

Trust center

Auth & accounts

POST/api/v1/auth/login

POST/api/v1/auth/logout

Logout

POST/api/v1/auth/logout-all

Logout all

POST/api/v1/auth/register

POST/api/v1/auth/request-email-verification

Request email verification

POST/api/v1/auth/verify-email

Verify email

GET/api/v1/me

The authenticated principal: account, org, workspace, effective plan and features.

cURL

curl https://provenova.net/api/v1/me -H "Authorization: Bearer $QL_TOKEN"

POST/api/v1/orgs/{org_id}/api-keys

Create api key

Health

GET/api/v1/health

Health