Developer docs

Withheld Public API

REST endpoints for embedding exposure scans, triggering opt-out requests, and pulling status into your own product. Bearer-token authenticated; mint a key from your dashboard.

Getting started

Sign in and open Dashboard › API keys.
Create a key with the scopes you need (read for status, write for mutations). Save the cleartext token immediately — it is shown only once.
Send it as Authorization: Bearer wk_... on every request to /api/v1/*.

Conventions

Successful responses use a { data, meta } envelope.
Errors use { error: { message } } with the right HTTP status.
401 = bad/missing token, 403 = missing scope, 429 = rate limit (honour Retry-After), 400 = validation, 404 = not found.
Rate limit defaults to 60 req/min per key. Hitting the cap arms a one-minute lockout.

OpenAPI

The machine-readable spec lives at /api/v1/openapi.json. Point your SDK generator (openapi-typescript, oapi-codegen, …) at it.

Examples

Run an exposure scan

Returns the count of brokers we cover in the requested regions. Counts against your read scope and per-key rate limit.

curl -X POST https://withheld.io/api/v1/exposure-scan \
  -H "Authorization: Bearer wk_..." \
  -H "Content-Type: application/json" \
  -d '{"jurisdictions": ["EU", "UK"]}'

List your profiles

Returns id + label + jurisdictions only. PII is intentionally never echoed by the list endpoint.

curl https://withheld.io/api/v1/profiles \
  -H "Authorization: Bearer wk_..."

Trigger an opt-out request

Creates a queued opt-out for one {profile_id, broker_id} pair. Requires write scope and an active mandate.

curl -X POST https://withheld.io/api/v1/requests \
  -H "Authorization: Bearer wk_..." \
  -H "Content-Type: application/json" \
  -d '{"profile_id": "<uuid>", "broker_id": "<uuid>"}'

Poll request status

Returns the request, its broker, and the full event timeline. Use the status field to drive your UI.

curl https://withheld.io/api/v1/requests/<id> \
  -H "Authorization: Bearer wk_..."

Download a removal certificate

Returns a PDF when the request is in verified_removed. Otherwise 400.

curl https://withheld.io/api/v1/requests/<id>/certificate \
  -H "Authorization: Bearer wk_..." \
  -o certificate.pdf