Create a persisted browser session

Creates a session: a sealed cookie jar and web-storage snapshot, pinned to one engine and one exit intent, that you reuse by passing its `id` as `session_id` on `/v1/scrape`.

Requires scope: sessions

Creates a session: a sealed cookie jar and web-storage snapshot, pinned to one engine and one exit intent, that you reuse by passing its id as session_id on /v1/scrape.

Pitfalls:

Every field is optional. An empty body (Content-Length 0) means "all defaults"; {} also works. Unknown fields are refused with 400.
Sessions are single-writer. While a render holds the lease, a second scrape on the same session, and release/delete without force=true, get 409 ERR::SESSION::BUSY with a Retry-After. Serialise work per session, or create one session per concurrent worker.
rotate_ip and sticky_key are mutually exclusive (400 ERR::REQUEST::INCOMPATIBLE_FLAGS). Omitting both pins the exit: sticky_key is derived from the session id.
ttl_seconds above the organization's maximum is refused (400), never clamped. It slides on use but never past hard_expires_at.
proxy_country requires premium_proxy: true. fingerprint requires engine: camoufox.
A project may hold only one active session per sticky_key (409 ERR::REQUEST::CONFLICT).
An organization may hold at most 100 live sessions (429 ERR::LIMIT::SESSIONS_EXCEEDED, Retry-After 30).
When engine is omitted, the default is the first of obscura, chromium that the deployment runs, else fetch. Check the engine in the response.
An explicit engine must be fetch or a render engine this deployment runs; otherwise 503 ERR::ENGINE::UNAVAILABLE and nothing is created. The detail lists the deployed engines.

Authorization

bearerAuth

AuthorizationBearer <token>

Authorization: Bearer <key>. Read the key from the SPICRAWL_API_KEY environment variable; never hard-code or log it. spicrawl_test_… keys can never spend live credits. Scopes: scrape, batch, sessions (granted by default), browser and read (granted deliberately). A missing scope is 403 ERR::AUTH::INSUFFICIENT_SCOPE naming the scope.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Body of POST /v1/sessions. All fields optional; unknown fields are refused with 400.

engine?string

Engine camoufox is coming soon. Engine to pin. Case-insensitive. Omitted means the first of obscura, chromium that this deployment runs, else fetch. Choose explicitly if you need a browser-only feature such as localStorage.

Value in

"fetch"
"obscura"
"chromium"
"camoufox"

ttl_seconds?integer

Sliding lifetime in seconds. Omitted or 0 means 1800, reduced to the organization maximum with a warning if that is lower. Values above the organization maximum (default 604800, i.e. 7 days) are refused with 400 naming the real maximum.

Range30 <= value

Default1800

sticky_key?string

Coming soon Pins the exit IP across the session. Letters, digits and hyphens, not starting or ending with a hyphen. Omitted means derived from the session id (still pinned). Must be unique among active sessions in the project. Cannot be combined with rotate_ip.

Match^[A-Za-z0-9][A-Za-z0-9-]{0,62}[A-Za-z0-9]$

Length2 <= length <= 64

region_pool?string

Coming soon Regional exit pool to draw from. Trimmed; longer than 64 characters is refused.

Lengthlength <= 64

rotate_ip?boolean

Coming soon Keep the cookie jar but let the exit IP change between requests. Use for many-page crawls; avoid for replayed logins, which get challenged on a moving IP. Refused together with sticky_key.

Defaultfalse

premium_proxy?boolean

Coming soon Use the residential tier instead of datacenter. Same meaning as on /v1/scrape.

Defaultfalse

proxy_country?string

Coming soon ISO 3166-1 alpha-2 exit country, case-insensitive. Requires premium_proxy: true, otherwise 400 ERR::REQUEST::INCOMPATIBLE_FLAGS.

Match^[A-Za-z]{2}$

fingerprint?|

Camoufox fingerprint pin, stored verbatim. A non-empty object with any engine other than camoufox is refused with 400. null and {} count as absent.

domain_scores?

Seed per-domain health, keyed by lowercase registrable domain (e.g. example.com). Scores must be non-negative. Above 64 entries, the least useful (unblocked, lowest score, oldest) are evicted rather than refused.

session_context?

Initial cookies and storage, e.g. an existing login or the session_context from a previous GET /v1/sessions/{id}/context. Serialised size limit 1 MiB (413). Omitted means an empty context.

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/v1/sessions" \  -H "Content-Type: application/json" \  -d '{    "engine": "chromium",    "ttl_seconds": 7200,    "premium_proxy": true,    "proxy_country": "de",    "sticky_key": "acct-4812"  }'

{  "id": "01J9ZQ4M7R3T8VX2K5N6P0B1CD",  "project_id": "01J9Y0000000000000000PROJ1",  "engine": "chromium",  "status": "active",  "sticky_key": "acct-4812",  "proxy": {    "tier": "residential",    "country": "de"  },  "created_at": "2026-09-22T10:00:00Z",  "last_used_at": null,  "expires_at": "2026-09-22T12:00:00Z",  "hard_expires_at": "2026-09-29T10:00:00Z",  "usage_count": 0,  "context": {    "schema_version": 1,    "cookies": 0,    "origins": 0,    "bytes": 131  }}

Create a persisted browser session

Authorization

Request Body

Response Body

201application/json

400application/problem+json

401application/problem+json

403application/problem+json

409application/problem+json

413application/problem+json

429application/problem+json

500application/problem+json

503application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`