Sessions

Start, list, fork, resume and configure sessions; their history, metrics and attachments. Paths are relative to /api/v1.

POST /sessions/{sessionId}/compaction/{compactionId}/undo

Undo an automatic compaction of the conversation: the full history comes back.

The compaction id is the timestamp of its record (the one the compaction event carries).

Path

sessionId

The session.

compactionId

The compaction: the instant it was recorded (from the talos.compattazione event).

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 /chat-images

Upload an image to attach to a message (JSON with the image data, up to 7 MB).

Body

Answers The bytes themselves (a file or an image), not JSON.

Errors1

Code	Status	Meaning
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}/chat-files

Upload a file into the session’s project folder, to attach to a message.

The body is the file itself (application/octet-stream); its name travels URL-encoded in the x-talos-file-name header. Only from this TALOS window.

Path

sessionId

The session.

Body

None: the body is empty.

Headers

x-talos-file-name

Answers The JSON envelope.

Errors1

Code	Status	Meaning
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 /chat-images/{imageHash}

Read an uploaded image back, by the SHA-256 of its bytes.

Path

imageHash

The image: its SHA-256 (64 hexadecimal digits).

Answers The bytes themselves (a file or an image), not JSON.

Errors1

Code	Status	Meaning
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 /tasks

List the task templates a new session can start from.

Answers The JSON envelope.

Errors1

Code	Status	Meaning
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

List the sessions (an empty list when none has started).

Answers The JSON envelope.

Errors1

Code	Status	Meaning
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

Start a session from a task template, with the model, the permissions and the mode it runs with.

taskId is required. With provider: "local", runtimeId and modelId are required too.

Body

taskIdrequired

The task template to start from: an id from GET /api/v1/tasks.

modello

The model, as OpenRouter names it (vendor/model-name), or <provider>:<model> for a provider’s own endpoint; default: the server’s.

modelloPlanner

The model that writes plans, in the same form as modello.

reasoning

Reasoning for models that support it: { effort?, summary? }, effort one of max, xhigh, high, medium, low, minimal, none; summary one of auto, concise, detailed.

client

desktop (default) or mobile: a session started from the phone.

permessi

What the session may do on its own: Read only, Workspace write (default), On request or Full access. See Permissions.

permessiPerAttrezzo

Per-tool exceptions to permessi: an object from tool (scrivi, file_edit, prova, shell, document_create, generate_image) to sempre (always), chiedi (ask) or nega (deny).

modalitaOperativa

normale (default) or piano: in Plan mode the session plans first and changes nothing until you approve the plan.

provider

cloud (default) or local: a model that runs on this computer.

runtimeId

With provider: "local": the local engine.

modelId

With provider: "local": the installed model.

fallbackConsent

With provider: "local": true to allow continuing on a cloud model when the local engine fails.

fallbackProviders

Up to 8 providers to continue with when the main one fails: [{ provider, model }], each model declared able to use tools.

linguaInterfaccia

Not yet described.

Answers The JSON envelope.

Errors4

Code	Status	Meaning
MODEL_ID_INVALID	400	The model name is not one this server recognizes (expected vendor/model-name).
PERMISSIONS_INVALID	400	The permissions are not among those allowed.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.
REASONING_INVALID	400	The reasoning level is not one of those allowed.

Any operation can also answer the common errors.

POST /assistenza

Ask the built-in help a question: it answers from the help pages that ship with TALOS.

Body

domandarequired

The question (1 character up to the limit the server sets).

Answers The JSON envelope.

Errors1

Code	Status	Meaning
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/custom

Start a free session on a folder: an assignment in your words, with an optional command that proves the work.

Exactly one of cartellaId, cartellaLibera or workspaceLaunchId names the folder; consegna is required. The other fields are those of POST /api/v1/sessions. Answers { sessionId }.

Body

cartellaId

The folder, as an id from GET /api/v1/projects.

cartellaLibera

The folder, as an absolute path.

workspaceLaunchId

The folder handed over by the launcher (POST /api/v1/workspace-launches).

consegnarequired

The assignment, in your words.

comandoProva

The command that proves the work is done (default npm test).

modello

The model, as OpenRouter names it (vendor/model-name), or <provider>:<model> for a provider’s own endpoint; default: the server’s.

modelloPlanner

The model that writes plans, in the same form as modello.

reasoning

Reasoning for models that support it: { effort?, summary? }, effort one of max, xhigh, high, medium, low, minimal, none; summary one of auto, concise, detailed.

client

desktop (default) or mobile: a session started from the phone.

permessi

What the session may do on its own: Read only, Workspace write (default), On request or Full access. See Permissions.

permessiPerAttrezzo

Per-tool exceptions to permessi: an object from tool (scrivi, file_edit, prova, shell, document_create, generate_image) to sempre (always), chiedi (ask) or nega (deny).

modalitaOperativa

normale (default) or piano: in Plan mode the session plans first and changes nothing until you approve the plan.

fallbackProviders

Up to 8 providers to continue with when the main one fails: [{ provider, model }], each model declared able to use tools.

linguaInterfaccia

Not yet described.

immagini

Images to attach to the first message: references returned by POST /api/v1/chat-images.

Answers The JSON envelope.

Errors4

Code	Status	Meaning
MODEL_ID_INVALID	400	The model name is not one this server recognizes (expected vendor/model-name).
PERMISSIONS_INVALID	400	The permissions are not among those allowed.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.
REASONING_INVALID	400	The reasoning level is not one of those allowed.

Any operation can also answer the common errors.

GET /artifacts/{artifactId}

An HTML artifact the agent wrote, served sandboxed so its scripts can never reach the app’s own storage.

Path

artifactId

The artifact.

Answers The bytes themselves (a file or an image), not JSON.

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}/export

Export a whole session: its messages and events, as one JSON document.

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.

GET /sessions/{sessionId}/processes

The process ledger of a session: every command it ran (by the agent’s shell and prova tools or by you), with origin, start, duration and outcome, and the stall guard (silence, loops).

Read only; the guard signals, and POST …/stop is what stops. A session with no events yet answers processi: null with motivo: "non-registrato", never an empty list: “not recorded” and “no processes” are different facts.

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.

GET /sessions/{sessionId}/metrics

The measures of a session: its turns, prompt-cache use, time to first token, how it closed, time spent reasoning, and whether a restart interrupted it.

A session with no events yet answers registrato: false with a motivo, never zeros: “not measured” and “zero” are different facts.

Path

sessionId

The session.

Query

eta

Not yet described.

Answers The JSON envelope.

Errors1

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.

Any operation can also answer the common errors.

DELETE /sessions/{sessionId}/messages/{messageId}

Remove a message from the conversation. Refused with 409 while the session is still running.

Path

sessionId

The session.

messageId

The message.

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.

GET /sessions/{sessionId}/children

The sub-agents a session started: its real children, with their state.

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.

GET /sessions/{sessionId}/agent-timeline

The timeline of the agents of a session: who did what, in order.

Path

sessionId

The session.

Query

after

Only entries after this sequence number.

through

Only entries up to this sequence number.

limit

How many entries.

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}/rename

Rename a session.

Path

sessionId

The session.

Body

nomerequired

The new name.

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}/delete

Delete a session, and the workflow runs of its conversation with it. A session still running, or with a run not finished, is refused first.

Path

sessionId

The session.

Body

None: the body is empty.

Answers The JSON envelope.

Errors3

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.
WORKFLOW_RUN_NOT_FINISHED	409	A workflow of this conversation is still running: cancel it first.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/fork

Fork a session: a new session that starts from the same conversation.

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}/resume

Resume a session: without a body, it resumes an interrupted turn; with a message, it is the next turn of the chat.

Path

sessionId

The session.

Body

messaggio

A new message (a non-empty string).

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}/settings

Change a session’s preferences: model, planner model, reasoning, permissions, fallback providers or mode (at least one).

Path

sessionId

The session.

Body

modello

The model, as OpenRouter names it (vendor/model-name), or <provider>:<model> for a provider’s own endpoint; default: the server’s.

modelloPlanner

The model that writes plans, in the same form as modello.

reasoning

Reasoning for models that support it: { effort?, summary? }, effort one of max, xhigh, high, medium, low, minimal, none; summary one of auto, concise, detailed.

permessi

What the session may do on its own: Read only, Workspace write (default), On request or Full access. See Permissions.

permessiPerAttrezzo

Per-tool exceptions to permessi: an object from tool (scrivi, file_edit, prova, shell, document_create, generate_image) to sempre (always), chiedi (ask) or nega (deny).

unisciPermessiPerAttrezzo

Not yet described.

rispettaNega

Not yet described.

fallbackProviders

Up to 8 providers to continue with when the main one fails: [{ provider, model }], each model declared able to use tools.

modalitaOperativa

normale or piano (plan first). The former workflow mode is retired (MODE_WORKFLOW_RETIRED).

linguaInterfaccia

Not yet described.

Answers The JSON envelope.

Errors5

Code	Status	Meaning
MODEL_ID_INVALID	400	The model name is not one this server recognizes (expected vendor/model-name).
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
PERMISSIONS_INVALID	400	The permissions are not among those allowed.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.
REASONING_INVALID	400	The reasoning level is not one of those allowed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/compact

Compact the conversation now: older turns are summarized so the context has room again.

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}/migliora-prompt

Improve a prompt before sending it: the session’s model (local or cloud) rewrites it as a clearer brief, without sending it.

Path

sessionId

The session.

Body

promptrequired

The text to improve (up to 12,000 characters).

profondita

How far to go: concisa (concise), equilibrata (balanced, default) or estesa (extended).

Answers The JSON envelope.

Errors4

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
PROVIDER_RUNTIME_UNAVAILABLE	503	The provider’s preferences could not be saved: check the Doctor.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.
RUNTIME_NOT_AVAILABLE	503	The local runtime is not available.

Any operation can also answer the common errors.