Skip to main content
Project sessions manage long-lived browser containers, their cookies, and spawned resources.

​
List & create

​
GET /:project/api/sessions

  • Query – limit & offset.
  • Response – each entry contains { id, name, description, image, args, screen, status } plus metadata obtained from CloudSessionManager.

​
PUT /:project/api/sessions

  • Body
{
  "name": "Chrome bot",
  "description": "Keeps a Chrome window for scraping",
  "screen": { "width": 1440, "height": 900 },
  "args": "",
  "image": "google-chrome",
  "cookies": [],
  "proxy": {
    "protocol": "http",
    "hostname": "proxy.internal",
    "port": 3128,
    "username": "bot",
    "password": "secret"
  }
}
  • Behavior – validates cookies with assertCookie, normalizes proxy settings, and persists the session. Returns the new session ID.

​
Inspect, update, delete

​
GET /.../sessions/{sessionId}

Requires read permission for the session. Returns core metadata plus:
  • cookies when you also have cookies.read.
  • resources: enumerates active resources, each with URLs and status when you have permission to read the underlying session resource.

​
PATCH /.../sessions/{sessionId}

Accepts any combination of cookies, screen, name, description, args, image, or proxy. Fields are validated before calling CloudSessionManager.update.

​
DELETE /.../sessions/{sessionId}

Ensures write permission then removes the session entirely.

​
Starting sessions & working with resources

EndpointDescription
POST /.../sessions/{sessionId}/startStarts a new browser resource. Response contains { id, ...info, vncUrl, remoteUrl, status }.
GET /.../sessions/{sessionId}/{resourceId}Returns metadata and URLs for a specific resource.
GET /.../sessions/{sessionId}/{resourceId}/captureStreams captured cookies (requires both resource read and cookies read permissions).
GET /.../sessions/{sessionId}/{resourceId}/logsSupports SSE or paged JSON logs, filtered by offset/limit.
POST /.../sessions/{sessionId}/{resourceId}/stopStops the resource container.
Logs originate from the coordinator and include structured data such as { context, severity, message, area, object }. Permissions are enforced per resource ID, so sharing a session with another team only grants them access to the exact resources they are authorized to read or execute.