Create a persisted browser session

Creates a session: a sealed cookie jar and web-storage snapshot, pinned to 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 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 is an advanced option and may be refused with 400.
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).
engine is optional (fetch, js or browser): omit it and the session's rendering is chosen for you. Scrapes with the session run on that tier, so a js session refuses actions, block_resources, a screenshot and a PDF (400 ERR::REQUEST::CAPABILITY_UNSUPPORTED).

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

Optional. The rendering tier to bind the session to (fetch, js or browser); omit it and one is chosen for you. A tier the deployment does not offer is 503 ERR::ENGINE::UNAVAILABLE.

Value in

"fetch"
"js"
"browser"

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?|

Browser fingerprint pin, stored verbatim. Advanced option; a non-empty object is refused with 400 where the session's rendering cannot apply it. 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 '{    "ttl_seconds": 7200,    "sticky_key": "acct-4812"  }'

{  "id": "01J9ZQ4M7R3T8VX2K5N6P0B1CD",  "project_id": "01J9Y0000000000000000PROJ1",  "status": "active",  "sticky_key": "acct-4812",  "proxy": {    "tier": "datacenter"  },  "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`