Sessions

Operations of the Interactive Session API. Paths are relative to your deployment's API host.

GET /api/agent-session-api/sessions

List sessions with pagination and filters

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions

Create an isolated Session from one exact or release-channel LaunchDefinition revision

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json CreateSessionDto

GET /api/agent-session-api/sessions/domain-launch-access

Whether the caller may launch a session for a domain object: the same edit-relation verdict the launch fence enforces, answered without launching. A PDP outage is a 503, never a false.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/agent-session-api/sessions/model-classes

List the "smartness" (modelLane) levels a session can be set to for the current org — model-lane keys. An OPEN, contributed vocabulary: the set is whatever this organisation’s installed biomes declared, so a consumer must not treat it as a closed enum. The frontend maps each raw key to a friendly label. The levels are read from llm-registry-api, which owns the vocabulary; a registry outage is a 503 here rather than a short list.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/terminate-by-pipeline-run/{pipelineRunId}

Terminate all non-terminal sessions tied to a pipeline run. Service-to-service only (enforced by the delegation the route requires): releases the OpenCode workers held by agent sessions spawned inside a run the user has just halted. Human callers terminate individual sessions instead.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/agent-session-api/sessions/{id}

Get session detail

Authentication: bearer token (Authorization: Bearer <token>)

DELETE /api/agent-session-api/sessions/{id}

Terminate and archive a session. Requires management of this session: its owner, or an admin of the organization that owns it (org-owned sessions only). Invited participants and editors may not.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/archive

Archive session — deletes the MinIO snapshot and the xema/session/<id> branches on each DELIVERABLE repo, releases any active worker, and transitions the row to status=archived. Idempotent: a call against an already-archived session returns the prior archivedAt without re-running cleanup. Distinct from /pause: pause preserves state for resume; archive throws it away. Requires management of this session: its owner, or an admin of the organization that owns it (org-owned sessions only). Invited participants and editors may not.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/agent-session-api/sessions/{id}/artifacts

List the tangible deliverable outputs this session produced — the files the in-session agent wrote to its /workspace/deliverables/ slot (governed by the session's deliverableSpecRef). Each entry carries the file body INLINED in content (the workspace lives only on the ephemeral worker pod, so there is no durable URL). Returns an empty list when the session has produced no deliverable yet; fails fast (503) when the worker is unreachable or paused.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/agent-session-api/sessions/{id}/attachments

List session attachments

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/attachments/upload-init

Initiate a direct-to-blob upload for a file attachment. Returns a short-lived presigned URL the browser uses to PUT the bytes straight to object storage; session-api never sees the buffer.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json InitAttachmentUploadDto

DELETE /api/agent-session-api/sessions/{id}/attachments/{attachmentId}

Remove attachment from session

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/attachments/{attachmentId}/upload-complete

Finalise a SAS upload. Verifies the blob landed in storage, flips the attachment to ready, and projects the file into the live workspace via the workspace-proxy SAS-pull endpoint so the agent sees it immediately.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/build-image

Start a Kaniko-based container-image build for the session's primary repo HEAD. Dispatches buildContainerImageWorkflow on the agent-session worker. Idempotent per (sessionId, sha): a duplicate call returns the existing run id. Only standard interactive sessions can build — pipeline + sandbox sessions are rejected.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json StartBuildImageDto

GET /api/agent-session-api/sessions/{id}/build-image/{workflowId}

Describe a previously-started build-image workflow. The FE polls this to flip the button between Building… / Completed / Failed.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/compact

Trigger conversation compaction on one thread (the default thread when none is named). Auto-resumes paused sessions. The runtime summarizes the conversation with the session's own model and reports it; Session.contextWindowSnapshot is reset to zeros and the FE chip drops via SSE without polling. Auto-compact still runs inside the runtime on overflow independently of this endpoint.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json CompactSessionDto

GET /api/agent-session-api/sessions/{id}/events/stream

Live SSE stream of session events — backlog from afterSequence, then live tail. Same wire shape as /timeline; reuse a single mapper on the FE.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/agent-session-api/sessions/{id}/files

Browse workspace file tree (scoped proxy with security boundary)

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/agent-session-api/sessions/{id}/files/{filePath}

Read file content from workspace (scoped proxy, deny list enforced, 1MB limit)

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/fork

Fork an existing session. Creates a new session that inherits the parent's profile, model, repository and branch strategy, then provisions a fresh worker — no chat history is copied. Use this to explore a parallel direction without disturbing the parent.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json ForkSessionDto

POST /api/agent-session-api/sessions/{id}/git/branch

Create or switch git branch. Requires turnState=idle.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json CreateBranchDto

POST /api/agent-session-api/sessions/{id}/git/commit

Commit changes. Author=user, co-author=agent. Requires turnState=idle.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json CommitDto

GET /api/agent-session-api/sessions/{id}/git/commits

Get commit history for session branch

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/agent-session-api/sessions/{id}/git/diff

Get git diff (staged or unstaged). When path is provided, the diff is scoped to that single file — used by the UI to render a per-file diff viewer on top of the changed-files panel.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/agent-session-api/sessions/{id}/git/merge-check

Check if the session branch can merge cleanly into the target branch. Uses git merge-tree (no workspace mutation).

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/git/push

Push to remote. Requires turnState=idle.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/agent-session-api/sessions/{id}/git/status

Get git status (modified, staged, branch)

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/agent-session-api/sessions/{id}/lockfile

Get the pinned AppLockfile minted at session create time . Returns 404 for sessions created before the lockfile column was introduced.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/pause

Pause session — snapshot to MinIO, release worker. Requires turnState=idle.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/question/{interactionId}/reject

Reject/dismiss a question posed by the agent during a turn. The dismissal is recorded and delivered asynchronously.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/question/{interactionId}/reply

Reply to a question posed by the agent during a turn. The reply is recorded and delivered asynchronously; the answer names the continuation that carries it.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json ReplyToQuestionDto

POST /api/agent-session-api/sessions/{id}/resume

Resume paused session — acquire worker, restore snapshot. Pass agentSlugOverride to recover a session whose primary agent was removed.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json ResumeSessionDto

GET /api/agent-session-api/sessions/{id}/tool-usage

Per-session MCP tool-usage counters. Returns one row per (mcpServiceSlug, command) tuple, sorted by count desc, read from mcp-gateway-api which owns them. Counters carry a sliding 30-day TTL. If the owning service cannot answer, the response is an empty list plus a typed warning rather than an error — the read is debug-grade and never blocks the UI. An empty list WITHOUT a warning means the session recorded no tool calls.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/agent-session-api/sessions/{id}/usage

Get session token usage and budget status

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/agent-session-api/sessions/{id}/working-files

List the session's working files, each with the object it is bound to. This is how a client finds the file bound to its object: nobody needs to know a slug. Until the kernel working-file binding names its own object (P2), object is the session's domain object, so a resync re-materializes every bidirectional file of the session, not only the one for that object.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/working-files/{slug}/resync

Re-materialize the worker's working file from the object's owner after a patch decision (accept / reject), so a discarded hunk's text actually leaves the worker file. A session with no live worker returns resynced: false: its file re-materializes on resume. Until the kernel working-file binding names its own object (P2), object is the session's domain object, so a resync re-materializes every bidirectional file of the session, not only the one for that object.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/agent-session-api/sessions/{id}/working-files/{slug}/user-edits

Stream a user's edit of a bound working file. The new base content is 3-way merged against the agent's working copy by the object's owner: the user edit folds into the accepted base, non-colliding agent suggestions survive, and agent hunks on the same lines are marked STALE (the user always wins). No turn gate.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json WorkingFileUserEditDto