API reference — Documentation

The QuantumLedger 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://quantumledger.ben.gy/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 is a no-op.

cURL

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

Response

{
  "run_id": "01J...",
  "run_hash": "b3f1...e9",
  "deduplicated": false
}

Runs

GET/api/v1/runs

List runs in your workspace, most recent first.

cURL

curl https://quantumledger.ben.gy/api/v1/runs \
  -H "Authorization: Bearer $QL_TOKEN"

Response

[
  { "run_id": "01J...", "backend": "ibm/ibm_kyiv", "shots": 4096, "status": "completed" }
]

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://quantumledger.ben.gy/api/v1/runs/01J... \
  -H "Authorization: Bearer $QL_TOKEN"

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://quantumledger.ben.gy/api/v1/runs/01J.../reproduce \
  -H "Authorization: Bearer $QL_TOKEN" \
  -d '{"days": 90, "profile": "bad_day"}'

Response

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

Result cards

GET/api/v1/cards/{slug}

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

cURL

curl https://quantumledger.ben.gy/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://quantumledger.ben.gy/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/quantumledger-jwks.json

Public JWKS for verifying attestation signatures yourself.

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://quantumledger.ben.gy/api/v1/attestations/01J.../verify

Response

{
  "valid": true,
  "revoked": false,
  "evidence_root": "9c2a...f0"
}

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/register

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://quantumledger.ben.gy/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