Every request parameter and every response field, generated from the live server schema.
Create a key per project on the API page and send it as a bearer token. Keys start with ns_live_, are shown once, and can be revoked at any time. Each key carries scopes - read, reveal, contacts - and an endpoint that needs a scope the key lacks returns 403 insufficient_scope.
curl "https://nosite.app/v1/leads?country=Egypt&contact=phone&limit=5" \
-H "Authorization: Bearer ns_live_…"Every success is { data, meta }. data is the object or list you asked for; meta carries paging, credits and the current rate-limit budget. Every error, whatever the status, is { error: { code, message } } - branch on code, never on the message text.
| Status | code | Meaning |
|---|---|---|
| 401 | invalid_key | Missing, malformed, or revoked key. |
| 403 | insufficient_scope | The key lacks the scope this endpoint needs. |
| 404 | not_found / not_revealed | No such lead, or you have not revealed it. |
| 402 | insufficient_credits | Your account has no credits left. Nothing is charged. |
| 402 | daily_cap_reached | This key's daily credit cap would be exceeded. Nothing is charged. |
| 409 | claimed_by_other | Another account holds an exclusive claim on this lead. |
| 429 | rate_limited / account_rate_limited | Too many requests for the key, or across your account. Honour Retry-After. |
| 400 | bad_cursor / bad_since / no_fields | A parameter or body was unusable - the message says which. |
| 422 | - | A parameter had the wrong type (standard validation error). |
Limits protect the service and are set by NoSite: 60 requests/minute per key and 120/minute across all keys on your account. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds), also mirrored in meta.rate; a 429 adds Retry-After.
Credits are shared by your whole account. Paid calls are marked 1 cr above. POST /v1/leads/{lead_id}/reveal costs 1 credit the first time, free forever after for the same lead, so retries are safe. POST /v1/leads/{lead_id}/media-pack also costs 1 credit per lead, but is charged only once the ZIP exists - a scrape that fails or finds nothing is free - and rebuilding or re-downloading a pack you own is free. Each key has a daily credit cap you set when creating it - a reveal that would exceed it returns 402 daily_cap_reached and charges nothing. Exclusive claims are not available through the API.
GET /v1/leads is cursor-paged: pass meta.next_cursor back as cursor until it is null. Pages are ordered newest-first by created_at and stay stable while new leads land. GET /v1/me/contacts is offset-paged (limit, offset, meta.total) and supports since for incremental syncs. Page size is 1-100 everywhere.