API reference

Basics

Prepaid credits are debited per request in units: a full scan 4, a light scan 1, a fixes preview 1. Scans run asynchronously: the POST returns a job id, poll it until status is done. Send an Idempotency-Key header to retry safely without a second charge. A failed scan refunds its units.

post/scans

Start a scan (asynchronous)

Responses: 202 Job accepted · 400 Bad request · 401 Missing, invalid or revoked key · 402 Not enough credits · 429 Rate limited

curl -X POST https://topnamed.com/api/v1/scans \
  -H "Authorization: Bearer tn_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

get/scans/{id}

Get a job and, when done, its result

Responses: 200 Job · 404 Not found

curl https://topnamed.com/api/v1/scans/JOB_ID \
  -H "Authorization: Bearer tn_live_YOUR_KEY"

post/scans/{id}/fixes

Preview grounded fixes for up to 3 gaps of a finished scan (asynchronous, 1 unit, nothing published)

Responses: 202 Job accepted · 404 Scan not found · 409 Scan not finished

curl -X POST https://topnamed.com/api/v1/scans/JOB_ID/fixes \
  -H "Authorization: Bearer tn_live_YOUR_KEY"

post/deploy-check

Builder deploy check: a light scan (1 unit) of a site that just went live

Responses: 202 Job accepted · 401 Missing or invalid key · 402 Not enough credits

curl -X POST https://topnamed.com/api/v1/deploy-check \
  -H "Authorization: Bearer tn_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

get/usage

Credit balance and this month's usage

Responses: 200 Usage

curl https://topnamed.com/api/v1/usage \
  -H "Authorization: Bearer tn_live_YOUR_KEY"