Work sessions

Endpoint: /api/work-sessions/sessions/

Create a bounded session for a person or a token, follow its approval status, and read its activity. A service token cannot create a work session: a person creates one assigned to that token with assigned_service_token. Service-token automation does not require a work session.

Access#

A Superuser can view and manage every session. Otherwise, the assigned user, the owner of the assigned personal token, or the owner of the assigned service token’s application can manage it. A server or cluster owner or manager can view sessions involving their servers or clusters; their timeline, recordings and live snapshot contain only activity on those targets.

Personal API tokens need the corresponding work_session scope and the owner’s permission on the session. Creating through a personal API token sets requester_type to agent. An agent cannot use the websh or kube_exec presets. Service-token reads are limited by session visibility, token scopes and the audit window.

Approval and rejection work only from the web console. Personal tokens, service tokens, CLI and MCP requests receive 403 permission_denied. Revocation is Superuser-only; a personal token can revoke only when its owner is a Superuser. Cancellation is limited to the creator or a Superuser, not the assignee merely because they are assigned. Tokens with granular scopes cannot call cancel, live snapshot or recommendation acknowledgment.

Routes#

All routes below begin with /api/work-sessions/sessions/. {id} is the work session UUID.

DELETE is unsupported and returns 405. Scheduled sessions activate on their own; activate is only needed to start an approved session early.

Status flow#

Completed, expired, revoked, rejected and cancelled sessions cannot be modified. Ending a session also cancels pending modifications and closes its live connections. With a duration, expires_at stays null until activation, then becomes started_at + duration.

Create a session#

POST /api/work-sessions/sessions/

Choose either servers or clusters, exactly one assignee, and either duration or expires_at. A non-Superuser may assign only to themselves, their own personal token, or a service token of an application they own. The default maximum session duration is four hours. request_channel and declared_agent are read-only.

Each sudo policy has non-empty commands (each up to 512 characters), optional users, allow_bypass_mfa (default false, allowing the session approval to take the place of MFA for sudo), reason (up to 1,024 characters) and optional valid_until. A non-Superuser may name only the assigned user in users. Changes to sudo policies where the session approval takes the place of MFA can require approval or be refused with the errors below.

For example, use a personal token with work_session:create to request an agent command session for its owner to use from a signed-in CLI or MCP session. The personal token cannot run commands in it: personal tokens cannot be issued command execution scopes.

curl -X POST "https://your-workspace.us1.alpacon.io/api/work-sessions/sessions/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
  -H "Content-Type: application/json" \
  -d '{"description":"Check disk space before deployment","requester_type":"agent","scopes":["command"],"servers":["7e3984de-49ab-4cc6-bcdf-21fbd35858b8"],"duration":"01:00:00"}'

Every successful create returns 201, including when approval is required. In that case the session has status: "pending" and an approval_request_id. Poll the detail route until its status changes; a successful HTTP response does not mean the session is ready to use.

curl "https://your-workspace.us1.alpacon.io/api/work-sessions/sessions/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""

The polling token needs work_session:read. On the Free plan, delegation that would prevent the creator from reading the resulting session returns 402 workspace_plan_update_required.

Update or extend#

PATCH /api/work-sessions/sessions/{id}/
PUT /api/work-sessions/sessions/{id}/
POST /api/work-sessions/sessions/{id}/extend/

For a pending session, update title, description, scopes, servers, clusters, target_account_username, starts_at or expires_at. The change applies directly and the approval request is reassessed. The assignee cannot change, and a declared account cannot be cleared.

For an approved or active session, update title, description, scopes, servers, target_account_username or sudo_policies. Send the complete desired sudo policy list; existing entries can include their id. Removals and restrictions apply immediately, as does a title change from the web console. Changes requiring approval include description changes, added scopes or servers, wider sudo policies and account changes. Only one modification request can be pending.

An update returns 200 when applied directly, or 202 with the full session when a modification is pending. Its pending_modification_request has this shape:

{
  "id": "9b52a7c4-13de-48f6-a01b-7f3e5d982c44",
  "changes": {},
  "added_at": "2026-10-24T10:00:00Z",
  "can_cancel": true
}

To extend a session, send a later expires_at and a non-blank reason of up to 2,048 characters. It must be approved or active, its start time must have arrived, and it must not have expired. The new expiry must remain within the workspace’s maximum duration measured from now.

{
  "expires_at": "2026-10-24T12:00:00Z",
  "reason": "Finish deployment verification"
}

An extension returns 200 when applied directly or 202 with the full session when approval is needed. Only one extension request can be pending. Its pending_extension_request is:

{
  "id": "9b52a7c4-13de-48f6-a01b-7f3e5d982c44",
  "requested_expires_at": "2026-10-24T12:00:00Z",
  "expires_at": "2026-10-24T11:00:00Z",
  "reason": "Finish deployment verification",
  "added_at": "2026-10-24T10:00:00Z"
}

Here expires_at is the request deadline, bounded by the session’s current expiry. Read the detail response’s can_extend, extend_blocked_reason, max_extendable_to, extension_request_deadline and extension_ends_with_session before requesting an extension. These hints are null in list responses.

For approval-related changes on this page, only updates and extensions return 202; creation returns 201 even when pending. Analysis uses 202 separately to acknowledge asynchronous work.

Approval and other actions#

Approve and reject through the web console as an eligible approver. A policy can prevent the requester from approving their own request. If fresh MFA presence is required, these routes return 400 auth_mfa_required without a source field.

Approval accepts optional adjusted_scopes (non-empty valid presets), adjusted_servers (up to 100 UUIDs, only narrowing), adjusted_target_account_username (non-blank, only narrowing), and either adjusted_duration (positive whole seconds) or adjusted_expires_at (future). Optional recommendations is an array of objects containing id, text, severity (low, medium, high), source (ai_suggested, ai_edited, admin_added) and auto_checkable (boolean). sudo_auto_approve: true is refused; sudo_risk_ceiling is accepted but has no effect.

An approver without visibility of the session receives 404 here and must use POST /api/approvals/approvals/{id}/approve/ for the approval request instead.

Approval returns the session when settled. If more votes are needed, it returns 200 with:

{"status":"pending","approvals_received":1,"approvals_required":2}

Reject and cancel return the session. Cancel requires a pending session. Complete requires an active session and starts analysis. Revoke requires an approved or active session. Activate requires an approved, unexpired session and also succeeds if it is already active.

POST {id}/acknowledge-recommendations/ is idempotent and returns {"recommendations_acknowledged_at":"2026-10-24T10:00:00Z"}. Only the assigned person can acknowledge.

POST {id}/analyze/ requires completed, expired or revoked. It returns 202 {"status":"accepted","work_session":"SESSION_ID"}, or 200 with status: "already_exists". ?force=true retries a stuck pending or processing analysis once it is old enough to retry. This route requires a paid plan.

List and read sessions#

GET /api/work-sessions/sessions/
GET /api/work-sessions/sessions/{id}/

Unknown statuses, channels or presets return 400 invalid_input.

{"count":0,"current":1,"next":null,"previous":null,"last":1,"results":[]}

results contains session objects. next and previous are integer page numbers or null.

Session fields#

Timeline and recordings#

These routes use their own cursor formats, not the integer pagination above.

Timeline#

GET /api/work-sessions/sessions/{id}/timeline/
GET /api/work-sessions/sessions/{id}/timeline/?cursor=&page_size=100

Without cursor, the response is {"results":[...]} for the whole session. include_records defaults to true; 0, false or no turns recording inclusion off. Embedded recordings are limited to 2 MiB per response and 128 KiB per Websh session. The Free plan returns only the opening of each recording. page_size has no effect in this form.

Include cursor, even empty, to select forward cursor pagination:

{"next":"OPAQUE_CURSOR","results":[]}

Pass the returned value as cursor for the next request; stop when next is null. There is no count or previous. page_size defaults to 100 and must be an integer from 1 to 500; invalid or out-of-range values return 400 invalid_input. A cursor from a different workspace, session or access scope returns 400 api_invalid_cursor.

Items share type, timestamp, id and server_id. Types are command, websh_session, tunnel_session, websh_record, ftp_session, file_upload, file_download, sudo_grant and kube_request. They are chronological; ties follow that type order. Commands contain masked_output_summary (up to 200 characters) and output_truncated. Cursor pages contain no recording bytes; websh_session items include record_chunks_total so you can fetch chunks separately.

Recording chunks#

GET /api/work-sessions/sessions/{id}/records/?session={websh_session_id}

session is a required Websh session UUID belonging to this work session. Tunnel sessions are not accepted. A paid plan is required.

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [{"added_at":"2026-10-24T10:00:00Z","record":"masked terminal output"}]
}

next and previous are opaque cursors or null. Send the chosen cursor in cursor; cursor=last starts at the last page. page_size defaults to 8 and is capped at 16. Invalid values use the default, and larger values are clamped. Each response also stops at 2 MiB, so a page may contain fewer chunks; continue with next. Expired cursors return 400 api_cursor_expired; invalid cursors return 400 api_invalid_cursor. If history search is unavailable, the route returns 503 api_search_unavailable.

Live snapshot#

GET /api/work-sessions/sessions/{id}/live_snapshot/

Use a signed-in session with view permission. since accepts an ISO 8601 datetime with an offset. limit defaults to 200 and is capped at 200; a non-integer returns 400 invalid_input. The response contains work_session, last_seq, snapshot_taken_at, status_history, commands, websh_sessions, sudo_grants and ftp_events.

Planning helpers#

The account helpers refuse service tokens. A non-Superuser can name only themselves in assigned_user. Personal tokens need both the route’s work_session scope and proc:read. Scope suggestions return 400 work_session_ai_unavailable when AI is unavailable.

Audit window and plans#

The audit window is 7 days on Free, 120 days on Essentials and 365 days on Enterprise. List results omit older sessions. Free also limits the list to your own sessions. On Essentials and Enterprise, you can read organization-wide history within your normal visibility; service tokens have organization audit scope within their own visibility and the plan’s window.

For detail, timeline, recordings and live snapshot, a Free-plan request for another person’s session returns 404 api_not_found. An otherwise accessible session outside the audit window returns 402 workspace_plan_update_required. Recordings and analysis require a paid plan even inside the window.

Errors#

See the API reference for authentication and error envelopes.