Endpoint reference

/api/badge/[humanId]

Render a live SVG of the "Verified by Provably" trustmark for a verified human id. The endpoint performs a single indexed lookup against the Verification.humanId column with status = "verified" — no auth, no rate limit, no token. The hit branch carries the partner's "platform" as label; the no-hit branch is the placeholder SVG.

Path parameter

humanId is a server-minted UUID stored on Verification.humanId. Regex-validated server-side (1-200 chars matching [A-Za-z0-9-]) — anything outside that shape completes the lookup as the placeholder branch (a 200 SVG), never a 4xx. DB errors fall through to the placeholder; no-leak wins over availability.

Theme switch

Append ?theme=dark for the inverted palette (background, border, text). No `theme` query param defaults to light. The theme is a palette-only switch — the SVG markup and accessibility names do not change between branches.

No humanId in markup

humanId is the row key but the success-branch SVG never echoes it back. No alt text, no <a xlink:href> decoration, no visible text. The click surface always points at the static /explorer route so a partner embed can't leak humanIds into partner-side analytics.

Request

GET
/api/badge/[humanId]

Path: humanId (1-200 chars, [A-Za-z0-9-]). Query: ?theme=light|dark (optional). No headers — the response is image/svg+xml with `Cache-Control: public, max-age=60` on the verified branch and `no-store` on the placeholder.

Body / parameters

GET /api/badge/7f9e1c4a-2b5d-4a0f-9e2c-9e1f1d2c8a4b?theme=light

Response

200 (verified | unknown), 4xx (never)

Verified branch: teal "VERIFIED BY · PROVABLY" badge, optional <platform> label, click surface points at /explorer. Placeholder branch: grayscale "UNKNOWN ID" badge, neutral palette. Both carry aria-label / <title>. NO humanId serialized in either branch.

Try it

Copy-paste curl

Paste the snippet into a terminal or the embedded sandbox panel below. The sandbox runs against the same /api/docs/<endpoint> handler so the wire shape on this page matches the response the evaluator returns.

curl

curl -s https://provably-2.polsia.app/api/badge/7f9e1c4a-2b5d-4a0f-9e2c-9e1f1d2c8a4b?theme=light \
  -H "accept: image/svg+xml" | head -c 200

Response

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 220 36" data-provably="verified">
  <!-- "VERIFIED BY" upper-eyebrow -->
  <!-- teal #0d857e dot -->
  <!-- "PROVABLY" body + optional <platform> label -->
</svg>
Try it

Embedded sandbox

Fire a same-origin call against /api/docs/badge and read the canonical wire shape back. No external tools, no auth — the docs surface is public.

1–200 chars matching [A-Za-z0-9-]

Awaiting call. Send a request to render the wire shape back.

Ready to integrate the real endpoint?

Request a sandbox API key →