Turns and approvals

Follow a session live, answer its approvals and questions, queue and redirect messages, run your own commands. Paths are relative to /api/v1.

GET /sessions/{sessionId}/events

The live event stream of a session (server-sent events): every message, tool call, approval and state change as it happens.

On reconnection the browser sends Last-Event-ID and the stream resumes after that sequence number. The events are described on the Events page of this reference.

Path

sessionId

The session.

Answers An event stream (text/event-stream).

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/cancel

Stop a running session.

Path

sessionId

The session.

Body

None: the body is empty.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/stop

Stop the session’s current turn.

The body may be empty; with { redirectId } it also cancels a redirection in flight.

Path

sessionId

The session.

Body

redirectId

The redirection to cancel (a UUID).

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/redirect

Redirect the running turn with a new message: the agent takes it into account without starting over.

Path

sessionId

The session.

Body

messaggiorequired

The message.

redirectId

An id for this redirection (a UUID), to cancel it with …/stop.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/shell

Run a command of yours in the session’s folder (a ! command in the chat); it is recorded in the process ledger.

Path

sessionId

The session.

Body

comandorequired

The command.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/dove-girano-i-comandi

Choose where the session’s commands run on Windows: WSL 2 or Windows itself.

Path

sessionId

The session.

Body

dove

wsl2, windows, or null for the default.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/comandi-nella-conversazione

Choose whether your ! commands and their output enter the model’s conversation (off by default).

Path

sessionId

The session.

Body

acceso

true to include them.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/impostazioni-comandi

Read the two command settings of a session: where commands run, and whether they enter the conversation.

Path

sessionId

The session.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/approve

Answer an approval request of the agent (with the “On request” permission): allow or deny that one action.

The request id is required: there is never an answer “to the last pending request”.

Path

sessionId

The session.

Body

requestIdrequired

The request.

approvatorequired

true to allow, false to deny.

ambito

Not yet described.

rispostoDa

Not yet described.

automazioneModificata

Not yet described.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/question

Answer a question the agent asked you.

Path

sessionId

The session.

Body

requestIdrequired

The question.

statusrequired

answered, skipped, cancelled or expired.

answers

With answered only: the answers, by question.

rispostoDa

Not yet described.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/plan-decision

Decide on a plan the agent proposed: proceed, proceed accepting its changes, start a clean conversation with it, or keep planning.

The body must be application/json and come from this TALOS window (or carry the token from a client that is not a browser): proceeding raises the session’s permission. The answer is sent once the decision is on disk; the same decision again is idempotent.

Path

sessionId

The session.

Body

requestIdrequired

The plan request.

decisionerequired

procedi-con-conferma, procedi-accetta-modifiche, conversazione-pulita or continua-a-pianificare.

hashrequired

The plan’s fingerprint, sha256: and 64 hexadecimal digits.

feedback

With continua-a-pianificare only: what to change (up to 4,000 characters).

Answers The JSON envelope.

Errors3

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
PAYLOAD_LIMIT	413	The body is larger than the server accepts: shorten it, or put the text in a file and attach it.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/queue

The messages waiting in the session’s queue, sent after the current turn.

Path

sessionId

The session.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/queue

Queue a message to send after the current turn.

Path

sessionId

The session.

Body

messaggiorequired

The message.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/queue/annulla

Remove a queued message, or empty the queue.

Path

sessionId

The session.

Body

id

One message to remove; without it, the whole queue.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/queue/invia

Send a queued message now: during a turn it enters as a correction, otherwise it resumes the session.

Path

sessionId

The session.

Body

idrequired

The queued message.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.