List all shell sessions for an organisation

GET

/api/sessions

Return all shell sessions for the organisation, newest first.

All filters are optional. Pagination is identical to the per-device endpoint. Requires org viewer access.

Authorizations

• HTTPBearer

Parameters

Query Parameters

organization_id

required

string format: uuid

page

integer

default: 1 >= 1

per_page

integer

default: 20 >= 1 <= 100

device_id

Any of:

string

string format: uuid

null

null

Filter by device

tier

Any of:

string

string

null

null

Filter by tier (standard/elevated/breakglass)

status

Any of:

string

string

null

null

Filter by status

user_id

Any of:

string

string format: uuid

null

null

Filter by opener user_id

since

Any of:

string

string format: date-time

null

null

Filter: sessions created at or after this ISO-8601 timestamp

until

Any of:

string

string format: date-time

null

null

Filter: sessions created before or at this ISO-8601 timestamp

Responses

200

Successful Response

Paginated list of session records.

object

items

required

Array<object>

Public representation of a shell session.

Secret / sensitive fields (client_ip, user_agent, recording_uri, recording_sha256) are intentionally EXCLUDED from this schema.

WebSocket connection fields (ws_url, ws_token, ws_expires_at) are populated only when the gateway is configured and the session was opened via POST /devices/{id}/sessions. They are None in list/get responses and in dev environments where the gateway is not running.

ws_token is included so the browser can supply it as a WebSocket subprotocol (Sec-WebSocket-Protocol) when opening ws_url — never appended to the URL query string, so it does not land in proxy access logs (GAP-FE-007). It is short-lived (~60 s) and single-use; do NOT persist it.

object

created_at

required

string format: date-time

device_id

required

string format: uuid

ended_at

required

Any of:

string

string format: date-time

null

null

exit_reason

required

Any of:

string

string

null

null

id

required

string format: uuid

justification

required

Any of:

string

string

null

null

organization_id

required

string format: uuid

recording

boolean

started_at

required

Any of:

string

string format: date-time

null

null

status

required

string

tier

required

string

user_id

required

Any of:

string

string format: uuid

null

null

ws_expires_at

Any of:

string

string format: date-time

null

null

ws_token

Any of:

string

string

null

null

ws_url

Any of:

string

string

null

null

page

required

integer

per_page

required

integer

total

required

integer

422

Validation Error

object

detail

Array<object>

object

loc

required

Array

msg

required

string

type

required

string