A session is one isolated browser, dedicated to you for its lifetime and destroyed on release.
No cookies, profile, or disk state is ever reused between sessions.
Base URL: https://api.tilion.dev
Create a session
A successful create returns 201 Created.
Body
All fields are optional, and an empty body gives you an ephemeral, headless browser in the
nearest region. Every option is documented in Session configuration.
Keep ttl and idle_timeout tight. A session bills for as long as it exists, and a long
idle_timeout will hold a browser open long after your job finished.
Response
connect_url is only ever populated here and on /connect. See
Connecting a browser.
Idempotency
Send an Idempotency-Key header to make a retried create safe:
A repeat with the same key returns the original session instead of creating a second one.
Idempotency keys are currently supported on session create only.
Errors
Get a session
connect_url is always null here. This is expected. Use /connect to obtain one.
The endpoint returns 404 if the session does not exist, is not yours, or has already ended.
List sessions
The endpoint returns an array of the same shape, for your account only. connect_url is null
on every entry.
Mint a connect URL
The token expires in 300 seconds and is scoped to this session. Mint one immediately before you
attach; do not cache it.
The endpoint returns 403 if raw CDP is not enabled for your key, and 409 if the session has
no live browser.
Release a session
A successful release returns 204 No Content.
The endpoint returns 404 if the session is already gone, which you can safely treat as success. The response is
sent as soon as the release is accepted, so a GET immediately afterwards may still briefly show
the session.
Always release in a finally block. Sessions bill until released.
Drive a session over HTTP
If you only need one navigation, you can skip CDP.
The body takes url only.
Concurrent drive calls on one session are serialised, so a second call waits for the first.
Session states
