# Sessions

Source: https://webagent-docs-staging.lookover.ai/api-reference/sessions

> Create, inspect, control and stop browser sessions.

## GET /v1/sessions

List sessions, newest first. Any of cursor, limit, state, since, until, q gives the paged reply `{ items, nextCursor? }`, else `{ sessions }`

Parameters:
- `limit` (query): integer
- `cursor` (query): string
- `state` (query): ("starting" | "live" | "paused" | "ended" | "lost")[]
- `since` (query): integer
- `until` (query): integer
- `q` (query): string

Responses: 200 `ListSessionsReply`, default `ErrorBody`

## POST /v1/sessions

Create a browser session (empty body: every default). `startUrl` opens a page before the session is live; a blocked address is 403 `navigation_blocked`

Parameters:
- `Idempotency-Key` (header): string. Retry safely: the same key and body replay the first answer.

Request body (JSON): `CreateSessionRequest`

Responses: 201 `CreateSessionResponse`, default `ErrorBody`

## GET /v1/sessions/{id}

Get a session record (with `endpoints` while it is starting, live or paused)

Parameters:
- `id` (path, required): string

Responses: 200 `GetSessionResponse`, default `ErrorBody`

## PATCH /v1/sessions/{id}

Rename a session (`{ title }`, 1..120 characters, trimmed). Any member who can see it; a title set this way is never replaced by an automatic one

Parameters:
- `id` (path, required): string

Request body (JSON): `UpdateSessionRequest`

Responses: 200 `GetSessionResponse`, default `ErrorBody`

## DELETE /v1/sessions/{id}

Stop a session

Parameters:
- `id` (path, required): string

Responses: 200 `DeleteSessionResponse`, default `ErrorBody`

## GET /v1/sessions/{id}/logs

The session's event log as paged JSON (opaque engine records)

Parameters:
- `id` (path, required): string
- `after` (query): integer
- `limit` (query): integer

Responses: 200 `SessionLogsPage`, default `ErrorBody`

## GET /v1/sessions/{id}/logs.ndjson

The session's event log (ndjson)

Parameters:
- `id` (path, required): string

Responses: 302, default `ErrorBody`

## GET /v1/sessions/{id}/recording

The session's video recording (webm)

Parameters:
- `id` (path, required): string

Responses: 302, default `ErrorBody`

## GET /v1/sessions/{id}/recording/thumbnail

The recording's last frame (jpeg)

Parameters:
- `id` (path, required): string

Responses: 302, default `ErrorBody`

## POST /v1/sessions/{id}/share

A signed share link to the live view or the recording (empty body: live, view only, 1 h)

Parameters:
- `id` (path, required): string

Request body (JSON): `CreateShareRequest`

Responses: 200 `ShareLink`, default `ErrorBody`

## DELETE /v1/sessions/{id}/share

Revoke every share link issued so far for the session; links made afterwards work (same role as creating one)

Parameters:
- `id` (path, required): string

Responses: 200 `RevokeSharesResponse`, default `ErrorBody`

## POST /v1/sessions/{id}/token

Mint a fresh session token for an open session

Parameters:
- `id` (path, required): string

Responses: 200 `SessionTokenResponse`, default `ErrorBody`

## GET /v1/share/{token}

Open a share link (no API key): live socket + share token, or the recording URL

Parameters:
- `token` (path, required): string

Responses: 200 `ShareView`, default `ErrorBody`