REST API

Create a key under Settings → API keys. The plaintext key is shown once and cannot be recovered afterwards; only its prefix is stored in a readable form. Send it as a bearer token on every request.

curl https://api.namescope.dev/v1/usage \
  -H "Authorization: Bearer ns_live_..."

Every key carries a set of scopes. A request that needs a scope the key does not have is refused with 403, so a key you hand to a read-only integration cannot start a paid scan.

Every scan is paid for with credits, whether you start it here or in the web app. A scan costs the sum of the modules it runs: 100 credits with all five default modules, and less when you leave one out. Your plan grants a credit allowance each month; unspent credits roll over.

The charge is written before any work is queued, so a scan that cannot be paid for never runs and never leaves a row behind. If queueing fails after the charge, the credits are refunded automatically.

• Balance too low → 429 with a problem body explaining the shortfall
• Plan without API access → 402 and an upgrade URL
• Credit spending switched off for the workspace → 403

POST /v1/scans queues a scan and answers 202 straight away. Scanning is asynchronous: the response carries a scanId, not the result.

curl -X POST https://api.namescope.dev/v1/scans \
  -H "Authorization: Bearer ns_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tion studios",
    "regions": ["TR", "EM", "US"],
    "niceClasses": [9, 41],
    "tlds": ["com", "io"],
    "modules": ["trademark", "domain", "social"]
  }'

{ "scanId": "scn_...", "totalJobs": 12, "creditsSpent": 100, "balance": 1900 }

Poll GET /v1/scans/{id} until status is completed or completed_partial. A typical scan finishes in under a minute; poll about once a second and widen the interval as you wait, so a long scan does not eat your rate limit.

curl https://api.namescope.dev/v1/scans/scn_... \
  -H "Authorization: Bearer ns_live_..."

Each entry in checks is one source answering about one target, with its own verdict, the sourceUrl it was read from and the fetchedAt timestamp. The summary object appears once the scan finishes and carries the score, the risk band and the trademark tally.

Four lookup endpoints describe what a scan request may contain. They need the reference:read scope and cost nothing.

Errors are RFC 9457 problem documents sent as application/problem+json. The type field identifies the failure, detail explains it, and some carry extras such as upgradeUrl.

{
  "type": "https://namescope.dev/errors/quota-exceeded",
  "title": "Quota exceeded",
  "status": 429,
  "detail": "Not enough credits (balance 0, need 100). Top up or switch off a module to continue."
}

Rate limits are counted per key over a sliding minute and reported on every response, so you can back off before being refused.

x-ratelimit-limit: 60
x-ratelimit-remaining: 58
x-ratelimit-reset: 41

The full machine-readable description is served at /v1/openapi.json. It needs no authentication, so you can generate a client from it before you have a key.