Onyx API documentation.

#Introduction

The API serves exactly what the site shows — the public dataset, nothing privileged. There is no write API: scores are produced by the review desk and published; callers read. Responses are UTF-8 JSON. All timestamps are ISO-8601 UTC. All identifiers are stable slugs, never numeric IDs.

curl https://api.onyx.dev/v1/projects?limit=3 \
  -H "Authorization: Bearer onyx_pk_····"

#Authentication

Pass your key in the Authorization header on every request. Keys are prefixed by tier: onyx_pk_ (free), onyx_pro_, onyx_ent_. Keys in query strings are rejected with 401 key_in_url — they end up in logs, and we'd rather fail loudly than leak quietly.

Authorization: Bearer onyx_pro_4f8a····e21c

#Pagination

List endpoints are cursor-paginated. Pass limit (max 100) and follow next_cursor until it is null. Cursors are stable across score updates — a paginating client never sees a project twice or misses one because ranks shifted mid-walk.

{
  "data": [ … ],
  "next_cursor": "eyJyYW5rIjoyNH0",
  "total": 2418
}

#Rate limits

Limits are per key, per rolling 24 hours: 1,000 (Free), 100,000 (Pro), unmetered (Enterprise). Every response carries the remaining budget; exceeding it returns 429 with a Retry-After header. Limits gate volume only — no tier ever sees different data.

X-RateLimit-Limit: 100000
X-RateLimit-Remaining: 99871
X-RateLimit-Reset: 2026-07-12T00:00:00Z

#Errors

Errors are JSON with a stable machine code and a human sentence. The code is the contract; the message may improve without notice.

#Verifying signatures

Every response body is signed with the Onyx publishing key (Ed25519). The signature covers the raw body bytes plus the Date header — so a stored payload can prove, later, what we published and when. The public key is pinned at /disclosures and served from DNS.

const ok = crypto.verify("ed25519", body,
  ONYX_PUBLIC_KEY, Buffer.from(res.headers["x-onyx-signature"], "base64"));
// ok === true → this is a real Onyx score

The ratings directory. Sorted by rank by default. Every filter the site's directory has is a query parameter here.

The full rating object — everything on the project page. Fields a project chose not to provide are null, never omitted: absence is data here, and the shape is stable regardless.

Score time series. Each point carries the methodology version it was scored under — framework changes re-label history, they never silently re-score it.

{ "date": "2026-06-14", "score": 94, "tier": "certified",
  "methodology": "v3.2", "event": "scheduled_review" }

All public cases, newest first. The case shape matches the public ledger: project, before/after score, action type, dated key facts, the project's response (or documented non-response), evidence links, reviewer of record, case ID.

The App Store directory — every reviewed-and-listed app. Detail at /v1/apps/{slug} returns the full listing: review record, permissions, on-chain usage (Onyx-indexed), version history, and wallet-verified review summary. Developer-supplied fields follow the platform rule — null when not provided, never omitted, never penalized.

Marketplace providers — audit firms, security teams, legal counsel. Detail at /v1/providers/{slug} adds service lines with published pricing, the Onyx-measured response/delivery record, sample work, and client reviews. Pricing and team data are provider-supplied and therefore nullable.

The framework as config: criteria, weights, tier thresholds and minimums, plus the diff against the prior version. latest resolves to the current version — v3.2 today.

The entire public dataset as gzipped JSONL, regenerated daily at 00:30 UTC — and immediately after any correction. The manifest carries a signed checksum per file; verify before you ingest.

{ "generated": "2026-07-11T00:30:04Z",
  "files": [ { "name": "projects.jsonl.gz", "sha256": "9f2c····", "rows": 2418 } ],
  "signature": "base64····" }

Websocket feed of publication events — score changes, new and resolved cases, tier moves, corrections — emitted at the moment they go public. The same events are available as signed webhooks. Nothing streams before it publishes: subscribers get speed, not foresight.

{ "type": "score_change", "slug": "emberswap",
  "from": 71, "to": 42, "case": "ONX-2026-0114",
  "published": "2026-07-08T14:02:11Z" }