Contexts

A Context is a persistent container for browser state, storing cookies, localStorage, sessionStorage, and other data. By associating multiple Sessions with the same Context, you can reuse state across Sessions without re-logging in.

Create a Context

POST /v1/contexts
X-API-Key: <api_key>

{
  "name": "my-context"  // optional, for identification
}

# Returns
{
  "id": "ctx_xxxx",
  "name": "my-context",
  "createdAt": "2024-01-01T00:00:00Z"
}

List Contexts

GET /v1/contexts
X-API-Key: <api_key>

# Returns
[
  {
    "id": "ctx_xxxx",
    "name": "my-context",
    "createdAt": "2024-01-01T00:00:00Z"
  }
]

Get a Context

GET /v1/contexts/:id
X-API-Key: <api_key>

Delete a Context

DELETE /v1/contexts/:id
X-API-Key: <api_key>

# Returns 204 No Content

Note: When a Context is deleted, associated Sessions are not stopped, but their context_id will be set to NULL.

Context Snapshots

When a Session bound to a Context is stopped, the system automatically packages the browser state as a snapshot (tar.gz) and saves it, while also exporting cookies via CDP to contexts.cookies. The next Session using the same Context will automatically restore the previous state.

Context Cookies (Read / Write)

In addition to S3 snapshots, cookies can be read and written independently, making it easy to export from a local browser and write directly to a Context for automatic injection on the next session creation.

Read Cookies

GET /v1/contexts/:id/cookies?domain=.example.com
X-API-Key: <api_key>

# Returns
{
  "contextId": "ctx_xxxx",
  "exportedAt": "2026-06-05T10:00:00Z",
  "count": 2,
  "cookies": [ ... ]
}

Write Cookies

PUT /v1/contexts/:id/cookies
X-API-Key: <api_key>
Content-Type: application/json

{
  "cookies": [
    { "name": "token", "value": "...", "domain": ".example.com", "path": "/", "secure": true, "httpOnly": true }
  ]
}

# Returns { "contextId": "ctx_xxxx", "count": 1, "storedAt": "..." }

Note: Requires contexts:read / contexts:write permissions. Once written, no manual CDP injection is needed — sessions bound to this Context will auto-merge cookies on creation.

Typical Usage Scenario

// 1. Create Context
const ctx = await client.contexts.create({ name: 'my-account' });

// 2. First Session: log in to website
const session1 = await client.sessions.create({ contextId: ctx.id });
// ... log in with Puppeteer ...
await client.sessions.stop(session1.id); // auto-save login state

// 3. Next Session: access with saved login state
const session2 = await client.sessions.create({ contextId: ctx.id });
// ... no need to re-login, cookies restored ...
await client.sessions.stop(session2.id);

Snapshot Storage Path

Snapshots are stored locally on the server:

/tmp/browser-forest/profiles/.snapshots/{contextId}.tar.gz