Contexts

A context stores browser state (cookies and localStorage) so that logins carry over from one session to the next. Without one, every session starts with a clean browser and your agent has to sign in again.

Create a context

POST/v1/contexts

curl -X POST https://api.staging.boxline.dev/v1/contexts \
  -H "x-api-key: $BOXLINE_API_KEY"

The response contains the context’s id (plus sizeBytes, createdAt and updatedAt). Store the ID with the account or user it belongs to.

Start a session with a context

Pass it as context when you create a session. With persist: true, the browser state is saved back to the context when the session ends, so new logins are kept:

curl -X POST https://api.staging.boxline.dev/v1/sessions \
  -H "x-api-key: $BOXLINE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"browser": true, "context": {"id": "<context-id>", "persist": true}}'

Leave persist off (the default) to start from the saved state without changing it, for example when several runs should all begin from the same login.

A typical flow

1. Create a context for an account your agent works with.
2. Start a session with { id, persist: true } and sign in, either from your automation or by hand in the live view.
3. Release the session. Its cookies and localStorage are saved.
4. Start later sessions with the same context. They begin signed in, so your agent can go straight to work.

Inspect and delete

GET/v1/contexts/:id returns the context with inUseBy, the ID of the session using it or null. DELETE/v1/contexts/:id deletes it; this fails with 409 while a running session uses it. In the SDK: client.contexts.create(), get(id) and delete(id).

With Playwright

Saved state is applied to the browser’s default context. Use browser.contexts()[0] rather than creating a new one, otherwise your pages will not see the saved login.