Getting started
Authentication
Every REST request authenticates with a Bearer API key. Sandbox keys are free and deterministic; live keys run real scrapes and unlock after email verification.
Bearer API keys
Send your key in the Authorization header on every request. Keys are opaque random strings with a human-readable prefix — stay_live_… for production and stay_test_… for the sandbox.
GET /v1/search?location=Split,HR HTTP/1.1
Host: api.stayingapi.com
Authorization: Bearer stay_live_8sFq2nM4kP9wZ1vR7tYx0aBcDeFgHiJk
Accept: application/jsonA request with no header, a malformed header, or an unknown/revoked key returns 401 authentication_error — never billed. Auth is checked before validation, billing, or any upstream work.
Sandbox vs live keys
| stay_test_… (sandbox) | stay_live_… (live) | |
|---|---|---|
| Backing data | Deterministic fixtures (unified schema) | Real fan-out to live upstream sources |
| Credits | Always 0 (sandbox allotment only) | Charged per the credit tiers |
| Rate limit | Applies (sandbox plan limits) | Applies (the key's plan limits) |
| Data schema & error shapes | Identical to live | Identical to sandbox |
| Response transport | Synchronous 200 | 202 + jobId → poll /v1/jobs (cache hits are synchronous) |
| Cursor pagination | meta.pagination populated | Populated on synchronous results; null on async-returned jobs |
| Email verification | Not required | Required before live credit is usable |
The data schema, error taxonomy and meta block are identical across sandbox and live, so the shapes you code against never change. What differs is the transport: a live scrape is asynchronous — it returns a 202 with a jobId you poll, with the payload arriving at data.result. Raw-REST code should handle that path; the SDK auto-polls it away, so SDK code built on a test key runs unchanged on a live key.
The email-verification gate
stay_test_ keys and the deterministic sandbox still work fully — so you can build and test end-to-end before verifying. This is a free-tier abuse control, not a wall in front of evaluation.Creating, rotating & revoking keys
Manage keys from the dashboard:
- Create & label as many keys as you need, choosing the sandbox or live environment per key.
- Shown once. A new key’s secret is displayed a single time on creation — it is stored only as a SHA-256 hash and is never logged or recoverable. Copy it then.
- Rotate / revoke at any time; a revoked key immediately returns
401 revoked_api_key. - Every key belongs to one account and inherits that account’s plan — which sets the credit balance it draws from and its per-key rate-limit bucket.
One balance, two surfaces