{ "openapi": "3.1.0", "info": { "title": "TALOS Desktop local API", "version": "0.1.25", "description": "The HTTP API between the TALOS Desktop window and its local server, read from the source of desktop-v0.1.25. Every path starts with /api/v1. Reference: https://talos-code.com/docs/desktop/reference/api/", "license": { "name": "AGPL-3.0-only", "identifier": "AGPL-3.0-only" } }, "servers": [ { "url": "http://127.0.0.1:{port}/api/v1", "variables": { "port": { "default": "4174", "description": "The port of the server: 4174 from the source; the app chooses one per profile." } } } ], "security": [ {}, { "talosToken": [] } ], "tags": [ { "name": "Sessions", "description": "Start, list, fork, resume and configure sessions; their history, metrics and attachments." }, { "name": "Turns and approvals", "description": "Follow a session live, answer its approvals and questions, queue and redirect messages, run your own commands." }, { "name": "Workflows", "description": "Review, approve and start workflow proposals; follow and control their runs." }, { "name": "Files and folders", "description": "The session’s folder: browse, read, search, preview and change its files; choose folders for new sessions." }, { "name": "Git and GitHub", "description": "The Git state of a session’s folder and every Git action of the review panel; GitHub pull requests through `gh`." }, { "name": "Library, notes, tasks, memory and research", "description": "The project’s own records, the same the agent’s tools read and write." }, { "name": "Tools and extensions", "description": "The agent’s tools, and the hooks, MCP servers, plugins, skills and forged tools of a project, with their trust." }, { "name": "Terminals", "description": "The real terminals of a session." }, { "name": "Models and providers", "description": "The models on offer, provider keys and addresses, OpenRouter sign-in, and the web search source." }, { "name": "Local models", "description": "Models that run on this computer: the engine, installed models, Hugging Face downloads and what fits." }, { "name": "Browser", "description": "The built-in browser: reading pages, framing local previews, and the live browser the agent drives." }, { "name": "Automations", "description": "Task templates that run on a schedule." }, { "name": "Health and diagnostics", "description": "Whether the server is up, the Doctor’s readiness report, first-run state, and shutdown." } ], "paths": { "/admin/shutdown": { "post": { "operationId": "post-admin-shutdown", "tags": [ "Health and diagnostics" ], "summary": "Shut the local server down gracefully.", "description": "Accepted only from the loopback address and only with the shutdown token in the `x-talos-shutdown-token` header; the token is compared in constant time. Answers 202 and stops on the next tick, so the answer leaves first. Without the right token: 401 and nothing stops.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "AUTH_REQUIRED: This server accepts only the TALOS window that started it (or, for shutdown, the right token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/compaction/{compactionId}/undo": { "post": { "operationId": "post-sessions-sessionid-compaction-compactionid-undo", "tags": [ "Sessions" ], "summary": "Undo an automatic compaction of the conversation: the full history comes back.", "description": "The compaction id is the timestamp of its record (the one the compaction event carries).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "compactionId", "in": "path", "required": true, "description": "The compaction: the instant it was recorded (from the `talos.compattazione` event).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/compaction-policy": { "get": { "operationId": "get-sessions-sessionid-compaction-policy", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/workflows/{workflowId}/versions/{version}": { "get": { "operationId": "get-workflows-workflowid-versions-version", "tags": [ "Workflows" ], "summary": "Read one version of a workflow proposal: its plan, budgets and approval state.", "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "The workflow proposal.", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The version of the proposal (a positive integer).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/workflows/{workflowId}/versions/{version}/approve": { "post": { "operationId": "post-workflows-workflowid-versions-version-approve", "tags": [ "Workflows" ], "summary": "Approve a version of a workflow proposal, so it can be started.", "description": "The body must be exactly `application/json`, and the request must come from this TALOS window (its Origin) or, from a client that is not a browser, carry the TALOS token. Repeating the same command id is idempotent.", "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "The workflow proposal.", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The version of the proposal (a positive integer).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "commandId": { "description": "An id you choose for this command; sending it again repeats nothing." }, "definitionHash": { "description": "The SHA-256 of the definition you reviewed; a different one is refused." } }, "required": [ "commandId", "definitionHash" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_LIMIT: The body is larger than the server accepts: shorten it, or put the text in a file and attach it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/workflows/{workflowId}/versions/{version}/revise": { "post": { "operationId": "post-workflows-workflowid-versions-version-revise", "tags": [ "Workflows" ], "summary": "Change the budgets of a workflow proposal: creates the next version, to approve again.", "description": "Same defenses as approval (exact JSON, this window or the token). Answers 201 when the new version is created; the same revision sent again finds the same version.", "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "The workflow proposal.", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The version of the proposal (a positive integer).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "definitionHash": { "description": "The SHA-256 of the version you are revising." }, "budgets": { "description": "The limits to change, any of `promptTokens`, `completionTokens`, `wallMs`, `modelRequests`, `toolCalls` and `knownCostUsd`." } }, "required": [ "definitionHash", "budgets" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_LIMIT: The body is larger than the server accepts: shorten it, or put the text in a file and attach it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/workflows/{workflowId}/versions/{version}/start": { "post": { "operationId": "post-workflows-workflowid-versions-version-start", "tags": [ "Workflows" ], "summary": "Start a run of an approved workflow version.", "description": "Same defenses as approval. Answers 202: the run is accepted and scheduled. A repeated command answers the same receipt with the `Idempotency-Replayed: true` header. In this release the runtime runs `agent` steps, read only.", "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "The workflow proposal.", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The version of the proposal (a positive integer).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "commandId": { "description": "An id you choose for this command." }, "definitionHash": { "description": "The SHA-256 of the approved definition." } }, "required": [ "commandId", "definitionHash" ] } } } }, "responses": { "202": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_LIMIT: The body is larger than the server accepts: shorten it, or put the text in a file and attach it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_RUNTIME_NOT_READY: The workflow runtime is not ready.\nWORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/workflows/{runId}/pause": { "post": { "operationId": "post-sessions-sessionid-workflows-runid-pause", "tags": [ "Workflows" ], "summary": "Pause a running workflow run of this session: steps in flight finish first.", "description": "Same defenses as approval. Answers 202; a repeated command answers the same receipt with `Idempotency-Replayed: true`.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "commandId": { "description": "An id you choose for this command." } }, "required": [ "commandId" ] } } } }, "responses": { "202": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_LIMIT: The body is larger than the server accepts: shorten it, or put the text in a file and attach it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_RUNTIME_NOT_READY: The workflow runtime is not ready.\nWORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/workflows/{runId}/resume": { "post": { "operationId": "post-sessions-sessionid-workflows-runid-resume", "tags": [ "Workflows" ], "summary": "Resume a paused workflow run of this session.", "description": "Same defenses and answer as pause.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "commandId": { "description": "An id you choose for this command." } }, "required": [ "commandId" ] } } } }, "responses": { "202": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_LIMIT: The body is larger than the server accepts: shorten it, or put the text in a file and attach it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_RUNTIME_NOT_READY: The workflow runtime is not ready.\nWORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/workflows/{runId}/cancel": { "post": { "operationId": "post-sessions-sessionid-workflows-runid-cancel", "tags": [ "Workflows" ], "summary": "Cancel a workflow run of this session.", "description": "Same defenses and answer as pause.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "commandId": { "description": "An id you choose for this command." } }, "required": [ "commandId" ] } } } }, "responses": { "202": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_LIMIT: The body is larger than the server accepts: shorten it, or put the text in a file and attach it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_RUNTIME_NOT_READY: The workflow runtime is not ready.\nWORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/workflows/{runId}/retry": { "post": { "operationId": "post-sessions-sessionid-workflows-runid-retry", "tags": [ "Workflows" ], "summary": "Retry the failed steps of a finished workflow run.", "description": "Same defenses and answer as pause. See what would run again with `retry-preview` first.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "commandId": { "description": "An id you choose for this command." } }, "required": [ "commandId" ] } } } }, "responses": { "202": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_LIMIT: The body is larger than the server accepts: shorten it, or put the text in a file and attach it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_RUNTIME_NOT_READY: The workflow runtime is not ready.\nWORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/workflows/{runId}/retry-preview": { "get": { "operationId": "get-sessions-sessionid-workflows-runid-retry-preview", "tags": [ "Workflows" ], "summary": "Preview what a retry would run again: the failed steps and what depends on them.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_RUNTIME_NOT_READY: The workflow runtime is not ready.\nWORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/workflows/{runId}/events": { "get": { "operationId": "get-sessions-sessionid-workflows-runid-events", "tags": [ "Workflows" ], "summary": "The live stream of a workflow run (server-sent events).", "description": "Opens at `?after=` the first time; on reconnection the browser sends `Last-Event-ID` and the stream resumes after it. No other query parameter is accepted.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "description": "The last sequence number already seen (from the run graph), to start after it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "An event stream.", "content": { "text/event-stream": {} } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/workflows/{workflowId}/versions/{version}/graph": { "get": { "operationId": "get-workflows-workflowid-versions-version-graph", "tags": [ "Workflows" ], "summary": "The planned graph of a workflow proposal, as an overview (read only).", "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "The workflow proposal.", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The version of the proposal (a positive integer).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/workflows/{workflowId}/versions/{version}/edges": { "get": { "operationId": "get-workflows-workflowid-versions-version-edges", "tags": [ "Workflows" ], "summary": "The edges of the planned graph of a proposal, a page at a time.", "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "The workflow proposal.", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The version of the proposal (a positive integer).", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "Where the page starts (default 0).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Edges per page, 1 to 100 (default 50).", "schema": { "type": "string" } }, { "name": "phaseId", "in": "query", "required": false, "description": "Only the edges of these groups: repeat it once per open group (up to 64).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/workflows/{workflowId}/versions/{version}/groups/{groupId}": { "get": { "operationId": "get-workflows-workflowid-versions-version-groups-groupid", "tags": [ "Workflows" ], "summary": "One group (phase) of the planned graph of a proposal, a page at a time.", "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "The workflow proposal.", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The version of the proposal (a positive integer).", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "The group (phase) of the graph.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "Where the page starts (default 0).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Steps per page, 1 to 50 (default 50).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`stato` to order the steps by state.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/workflows/{workflowId}/versions/{version}/nodes/{nodeId}": { "get": { "operationId": "get-workflows-workflowid-versions-version-nodes-nodeid", "tags": [ "Workflows" ], "summary": "One step of the planned graph of a proposal.", "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "The workflow proposal.", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The version of the proposal (a positive integer).", "schema": { "type": "string" } }, { "name": "nodeId", "in": "path", "required": true, "description": "The step.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/workflow-proposals": { "get": { "operationId": "get-sessions-sessionid-workflow-proposals", "tags": [ "Workflows" ], "summary": "List the workflow proposals of a session, a page at a time.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "Where the page starts.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many proposals per page (at most 50).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/workflows": { "get": { "operationId": "get-sessions-sessionid-workflows", "tags": [ "Workflows" ], "summary": "List the workflow runs of a session, a page at a time.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "Where the page starts (default 0).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Runs per page, 1 to 50 (default 50).", "schema": { "type": "string" } }, { "name": "stato", "in": "query", "required": false, "description": "Only runs in this state: `created`, `running`, `paused`, `needs_attention`, `succeeded`, `failed` or `cancelled`.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Only runs whose title or id contains this text (case-insensitive, up to 256 characters).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/workflows/{runId}/graph": { "get": { "operationId": "get-sessions-sessionid-workflows-runid-graph", "tags": [ "Workflows" ], "summary": "The graph of a workflow run as it stands: steps, groups and their states.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/workflows/{runId}/edges": { "get": { "operationId": "get-sessions-sessionid-workflows-runid-edges", "tags": [ "Workflows" ], "summary": "The edges of the graph of a workflow run, a page at a time.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "Where the page starts (default 0).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Edges per page, 1 to 100 (default 50).", "schema": { "type": "string" } }, { "name": "phaseId", "in": "query", "required": false, "description": "Only the edges of these groups: repeat it once per open group (up to 64).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/workflows/{runId}/history": { "get": { "operationId": "get-sessions-sessionid-workflows-runid-history", "tags": [ "Workflows" ], "summary": "The public history of the states of a workflow run, to replay it faithfully.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "Where the page starts (default 0).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Entries per page, 1 to 1000 (default 50).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/workflows/{runId}/groups/{groupId}": { "get": { "operationId": "get-sessions-sessionid-workflows-runid-groups-groupid", "tags": [ "Workflows" ], "summary": "One group (phase) of a workflow run, with its steps, a page at a time.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "The group (phase) of the graph.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "Where the page of steps starts (default 0).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Steps per page, 1 to 50 (default 50).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "`stato` to order the steps by state.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/workflows/{runId}/nodes/{nodeId}": { "get": { "operationId": "get-sessions-sessionid-workflows-runid-nodes-nodeid", "tags": [ "Workflows" ], "summary": "One step of a workflow run: its state, its attempts and a preview of its output.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } }, { "name": "nodeId", "in": "path", "required": true, "description": "The step.", "schema": { "type": "string" } }, { "name": "outputOffset", "in": "query", "required": false, "description": "Where the output preview starts, in bytes (default 0).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/process-outputs/{processOutputId}": { "get": { "operationId": "get-sessions-sessionid-process-outputs-processoutputid", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "processOutputId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } } } } }, "/sessions/{sessionId}/workflows/{runId}/nodes/{nodeId}/output": { "get": { "operationId": "get-sessions-sessionid-workflows-runid-nodes-nodeid-output", "tags": [ "Workflows" ], "summary": "The full output of a finished step, its bytes verified against the content store.", "description": "Without `resultId`, when the step has several results, the answer is their index. `format=raw` answers the bytes of one result as a download (it needs `resultId`, and takes no `offset` or `limit`). By default the whole output is served.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } }, { "name": "nodeId", "in": "path", "required": true, "description": "The step.", "schema": { "type": "string" } }, { "name": "resultId", "in": "query", "required": false, "description": "Which result of the step (a step retried has several).", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "`json` (default) or `raw` for the bytes themselves.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "Where to start, in bytes (default 0).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many bytes (default: all).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/workflows/{runId}/nodes/{nodeId}/lineage": { "get": { "operationId": "get-sessions-sessionid-workflows-runid-nodes-nodeid-lineage", "tags": [ "Workflows" ], "summary": "The lineage of a step of a run: the steps upstream or downstream of it, a page at a time.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } }, { "name": "nodeId", "in": "path", "required": true, "description": "The step.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": true, "description": "`upstream` or `downstream`.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "Where the page starts (default 0).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Steps per page, 1 to 1000 (default 50).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/workflows/{workflowId}/versions/{version}/nodes/{nodeId}/lineage": { "get": { "operationId": "get-workflows-workflowid-versions-version-nodes-nodeid-lineage", "tags": [ "Workflows" ], "summary": "The lineage of a planned step: the steps upstream or downstream of it, a page at a time.", "parameters": [ { "name": "workflowId", "in": "path", "required": true, "description": "The workflow proposal.", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The version of the proposal (a positive integer).", "schema": { "type": "string" } }, { "name": "nodeId", "in": "path", "required": true, "description": "The step.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": true, "description": "`upstream` or `downstream`.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "Where the page starts (default 0).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Steps per page, 1 to 1000 (default 50).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WORKFLOW_STORE_UNAVAILABLE: Workflows are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/chat-images": { "post": { "operationId": "post-chat-images", "tags": [ "Sessions" ], "summary": "Upload an image to attach to a message (JSON with the image data, up to 7 MB).", "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/chat-files": { "post": { "operationId": "post-sessions-sessionid-chat-files", "tags": [ "Sessions" ], "summary": "Upload a file into the session’s project folder, to attach to a message.", "description": "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.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/chat-images/{imageHash}": { "get": { "operationId": "get-chat-images-imagehash", "tags": [ "Sessions" ], "summary": "Read an uploaded image back, by the SHA-256 of its bytes.", "parameters": [ { "name": "imageHash", "in": "path", "required": true, "description": "The image: its SHA-256 (64 hexadecimal digits).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/{providerId}/models": { "get": { "operationId": "get-providers-providerid-models", "tags": [ "Models and providers" ], "summary": "The models a provider offers, asked of the provider itself (or, for a local one such as LM Studio, of the runtime that probes it), with the capabilities it declares.", "description": "Only the providers whose catalog appears in the window have this route. A capability the provider does not declare is reported as unknown, never as false.", "parameters": [ { "name": "providerId", "in": "path", "required": true, "description": "The provider (see Providers).", "schema": { "type": "string", "enum": [ "esterno", "openai", "deepseek", "kimi", "minimax", "qwen", "zai", "anthropic", "gemini", "lmstudio", "groq", "cerebras", "mistral", "together", "fireworks", "deepinfra", "novita", "nebius", "xai", "ollama-cloud", "huggingface", "zai-anthropic", "minimax-anthropic", "azure", "bedrock", "vertex" ] } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "REPORT_UNAVAILABLE: The report or service asked for is not available on this server yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/favicon": { "get": { "operationId": "get-favicon", "tags": [ "Browser" ], "summary": "The icon of a website cited as a source, fetched once by the server and cached.", "description": "The browser never contacts the cited site: it asks the local server, which fetches the icon once and keeps it. Answers the image bytes, or 204 when the site has no icon.", "parameters": [ { "name": "dominio", "in": "query", "required": false, "description": "The domain of the site (for example `example.com`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } } } } }, "/health": { "get": { "operationId": "get-health", "tags": [ "Health and diagnostics" ], "summary": "Check that the server is up: `{ \"status\": \"ok\" }`.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tasks": { "get": { "operationId": "get-tasks", "tags": [ "Sessions" ], "summary": "List the task templates a new session can start from.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/projects": { "get": { "operationId": "get-projects", "tags": [ "Files and folders" ], "summary": "List the project folders a session may open (ids and names, never absolute paths).", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/workspace-browser": { "get": { "operationId": "get-workspace-browser", "tags": [ "Files and folders" ], "summary": "Browse the folders of this computer, to choose the one a session works in.", "parameters": [ { "name": "path", "in": "query", "required": false, "description": "The folder to list (once at most); without it, the starting points.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "WORKSPACE_NOT_AVAILABLE: The folder is not available: check that it exists and that TALOS can work in it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/frequent-dirs": { "get": { "operationId": "get-frequent-dirs", "tags": [ "Files and folders" ], "summary": "Folders used often, with their absolute paths, as suggestions for a session’s folder (from the history of sessions).", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/runtime": { "get": { "operationId": "get-runtime", "tags": [ "Local models" ], "summary": "The local model runtimes: whether each one is observed on this computer, and the models it has.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/runtime/bootstrap": { "get": { "operationId": "get-runtime-bootstrap", "tags": [ "Local models" ], "summary": "The runtime at start-up, as the backend reports it (`talos.harness-ui.runtime-bootstrap.v1`): the one source the window trusts for what is running.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/local-models": { "get": { "operationId": "get-local-models", "tags": [ "Local models" ], "summary": "The GGUF models installed on this computer.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/local-models/fit-estimate": { "get": { "operationId": "get-local-models-fit-estimate", "tags": [ "Local models" ], "summary": "Estimate whether a model of a given size would fit this machine, before downloading it (nothing is loaded).", "parameters": [ { "name": "bytes", "in": "query", "required": false, "description": "The size of the model file, in bytes.", "schema": { "type": "string" } }, { "name": "contextTokens", "in": "query", "required": false, "description": "The context length to plan for, in tokens (optional).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/huggingface/search": { "get": { "operationId": "get-huggingface-search", "tags": [ "Local models" ], "summary": "Search GGUF models on Hugging Face.", "parameters": [ { "name": "query", "in": "query", "required": false, "description": "The words to search for.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many results (default 20).", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "The cursor of the next page, from the previous answer.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Order: `downloads` by default.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "`-1` (descending, default) or `1`.", "schema": { "type": "string" } }, { "name": "author", "in": "query", "required": false, "description": "Only models by this author.", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "required": false, "description": "Hub filters, repeatable (`gguf` is always applied).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/huggingface/repo": { "get": { "operationId": "get-huggingface-repo", "tags": [ "Local models" ], "summary": "One Hugging Face repository: its description and GGUF files, pinned to an exact commit.", "parameters": [ { "name": "repo", "in": "query", "required": true, "description": "the repository (`owner/name`).", "schema": { "type": "string" } }, { "name": "revision", "in": "query", "required": false, "description": "A branch or commit (default `main`), resolved to a commit before the files are listed.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/huggingface/image": { "get": { "operationId": "get-huggingface-image", "tags": [ "Local models" ], "summary": "An image of a Hugging Face model card, served through the local server.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "the address of the image.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/huggingface/downloads": { "get": { "operationId": "get-huggingface-downloads", "tags": [ "Local models" ], "summary": "The model downloads in progress or finished, with their state.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers": { "get": { "operationId": "get-providers", "tags": [ "Models and providers" ], "summary": "The model providers and whether each one is configured (never the keys).", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "PROVIDER_STORE_UNAVAILABLE: The computer’s key store is not available: check the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/openrouter/esclusi": { "post": { "operationId": "post-providers-openrouter-esclusi", "tags": [ "Models and providers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "modello": { "description": "The model, as OpenRouter names it (`vendor/model-name`), or `:` for a provider’s own endpoint; default: the server’s." }, "slug": {}, "attivo": {}, "fornitore": {}, "esclusi": {}, "diSerie": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "PROVIDER_STORE_UNAVAILABLE: The computer’s key store is not available: check the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/openrouter/esclusi/dalla-risposta": { "post": { "operationId": "post-providers-openrouter-esclusi-dalla-risposta", "tags": [ "Models and providers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "modello": { "description": "The model, as OpenRouter names it (`vendor/model-name`), or `:` for a provider’s own endpoint; default: the server’s." }, "slug": {}, "attivo": {}, "fornitore": {}, "esclusi": {}, "diSerie": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "PROVIDER_STORE_UNAVAILABLE: The computer’s key store is not available: check the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/openrouter/esclusi/di-serie": { "post": { "operationId": "post-providers-openrouter-esclusi-di-serie", "tags": [ "Models and providers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "modello": { "description": "The model, as OpenRouter names it (`vendor/model-name`), or `:` for a provider’s own endpoint; default: the server’s." }, "slug": {}, "attivo": {}, "fornitore": {}, "esclusi": {}, "diSerie": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "PROVIDER_STORE_UNAVAILABLE: The computer’s key store is not available: check the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/models": { "get": { "operationId": "get-models", "tags": [ "Models and providers" ], "summary": "The catalog of models, from every configured provider and the local engine.", "parameters": [ { "name": "forza", "in": "query", "required": false, "description": "`1` to refresh the catalog now instead of using the cached one.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "REPORT_UNAVAILABLE: The report or service asked for is not available on this server yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/model-lab/capacity": { "get": { "operationId": "get-model-lab-capacity", "tags": [ "Local models" ], "summary": "The capacity of this machine for local models: memory, graphics and what they allow.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "REPORT_UNAVAILABLE: The report or service asked for is not available on this server yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/tools": { "get": { "operationId": "get-tools", "tags": [ "Tools and extensions" ], "summary": "The tools an agent is offered before any session exists (per-tool permissions are `null` until a session chooses them).", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "REPORT_UNAVAILABLE: The report or service asked for is not available on this server yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/setup/stato": { "get": { "operationId": "get-setup-stato", "tags": [ "Health and diagnostics" ], "summary": "The state of first-run setup: what is ready and what is still missing.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "REPORT_UNAVAILABLE: The report or service asked for is not available on this server yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/doctor": { "get": { "operationId": "get-doctor", "tags": [ "Health and diagnostics" ], "summary": "Run the Doctor: the checks of this installation, with what to do for each problem.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "REPORT_UNAVAILABLE: The report or service asked for is not available on this server yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/workspace-info": { "get": { "operationId": "get-workspace-info", "tags": [ "Files and folders" ], "summary": "A portrait of a folder before a session opens it: how many files, whether it is a repository root, its branch, unsaved changes and nested repositories (the scan has a declared ceiling).", "parameters": [ { "name": "path", "in": "query", "required": true, "description": "the folder (up to 4096 characters).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/browser/incorniciabile": { "get": { "operationId": "get-browser-incorniciabile", "tags": [ "Browser" ], "summary": "Whether a page can be shown inside the Browser panel, and by which way (`via`) it should be shown, with the reason (`percheVia`).", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "the address of the page (up to 2048 characters).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/browser/proxy": { "get": { "operationId": "get-browser-proxy", "tags": [ "Browser" ], "summary": "A page of a local development server, served from TALOS’s own origin with the Browser overlay injected.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "the address of the local page (up to 2048 characters).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/browser/leggi": { "get": { "operationId": "get-browser-leggi", "tags": [ "Browser" ], "summary": "Read a web page on the server, the way the agent’s `naviga` tool reads it, so the model sees the page the person is looking at.", "description": "The server has none of the person’s cookies: of a site behind a login it reads the public version.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "the address of the page (up to 2048 characters).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/browser/vivo/chiudi": { "post": { "operationId": "post-browser-vivo-chiudi", "tags": [ "Browser" ], "summary": "Close the live page of a session.", "parameters": [ { "name": "sessione", "in": "query", "required": true, "description": "the session id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/browser/vivo/apri": { "post": { "operationId": "post-browser-vivo-apri", "tags": [ "Browser" ], "summary": "Open a page in the live browser of a session (a real Chromium page the agent can drive).", "parameters": [ { "name": "sessione", "in": "query", "required": true, "description": "the session id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "url": { "description": "The address to open (up to 2048 characters)." }, "larghezza": { "description": "Viewport width in pixels (default 1280)." }, "altezza": { "description": "Viewport height in pixels (default 800)." } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/browser/vivo/gesto": { "post": { "operationId": "post-browser-vivo-gesto", "tags": [ "Browser" ], "summary": "Send a gesture of the person to the live browser: a click, a key or the wheel, in page coordinates.", "parameters": [ { "name": "sessione", "in": "query", "required": true, "description": "the session id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "tipo": { "description": "`clic`, `tasto` or `rotella`." }, "x": { "description": "For `clic` and `rotella`: the horizontal position in the page." }, "y": { "description": "For `clic` and `rotella`: the vertical position in the page." }, "tasto": { "description": "For `clic`: `sinistro` (default) or another mouse button." }, "doppio": { "description": "For `clic`: `true` for a double click." }, "chiave": { "description": "For `tasto`: the key." }, "testo": { "description": "For `tasto`: the text it types." }, "dx": { "description": "For `rotella`: horizontal scroll." }, "dy": { "description": "For `rotella`: vertical scroll." }, "modificatori": { "description": "The modifier keys held, as a bit mask (default 0)." } }, "required": [ "tipo" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/browser/vivo/descrivi": { "post": { "operationId": "post-browser-vivo-descrivi", "tags": [ "Browser" ], "summary": "Describe the element of the live page at a point, so the agent knows what the person is pointing at.", "parameters": [ { "name": "sessione", "in": "query", "required": true, "description": "the session id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "x": { "description": "Horizontal position in the page." }, "y": { "description": "Vertical position in the page." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/browser/vivo/misura": { "post": { "operationId": "post-browser-vivo-misura", "tags": [ "Browser" ], "summary": "Resize the live page to the panel the person is looking at (the viewport changes; the page does not reload).", "parameters": [ { "name": "sessione", "in": "query", "required": true, "description": "the session id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "larghezza": { "description": "Width in pixels." }, "altezza": { "description": "Height in pixels." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/browser/vivo/schermo": { "get": { "operationId": "get-browser-vivo-schermo", "tags": [ "Browser" ], "summary": "The screen of the live browser, streamed: one frame per server-sent event (`dati`, `metadati`, `numero`, `url`).", "description": "Closing the stream stops the transmission. A problem after the stream has started arrives as an event with `errore` and `codice`, then the stream closes.", "parameters": [ { "name": "sessione", "in": "query", "required": true, "description": "the session id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "An event stream.", "content": { "text/event-stream": {} } } } } }, "/browser/vivo/stato": { "get": { "operationId": "get-browser-vivo-stato", "tags": [ "Browser" ], "summary": "The state of the live browser: which sessions have a page open.", "parameters": [ { "name": "sessione", "in": "query", "required": true, "description": "the session id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/search-source": { "get": { "operationId": "get-search-source", "tags": [ "Models and providers" ], "summary": "The web search sources and which one is active (never the keys).", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "SEARCH_STORE_UNAVAILABLE: The search key store is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "post-search-source", "tags": [ "Models and providers" ], "summary": "Choose the web search source.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "source": { "description": "The source." }, "endpoint": { "description": "Its address, for a source you host." } }, "required": [ "source" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "SEARCH_NOT_READY: The search source is not ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "SEARCH_STORE_UNAVAILABLE: The search key store is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/wsl": { "get": { "operationId": "get-wsl", "tags": [ "Health and diagnostics" ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WSL_STORE_UNAVAILABLE: ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "post-wsl", "tags": [ "Health and diagnostics" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "usaUtenteNormale": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "WSL_STORE_UNAVAILABLE: ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions": { "get": { "operationId": "get-sessions", "tags": [ "Sessions" ], "summary": "List the sessions (an empty list when none has started).", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "post-sessions", "tags": [ "Sessions" ], "summary": "Start a session from a task template, with the model, the permissions and the mode it runs with.", "description": "`taskId` is required. With `provider: \"local\"`, `runtimeId` and `modelId` are required too.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "taskId": { "description": "The task template to start from: an id from `GET /api/v1/tasks`." }, "modello": { "description": "The model, as OpenRouter names it (`vendor/model-name`), or `:` for a provider’s own endpoint; default: the server’s." }, "modelloPlanner": { "description": "The model that writes plans, in the same form as `modello`." }, "reasoning": { "description": "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": { "description": "`desktop` (default) or `mobile`: a session started from the phone." }, "permessi": { "description": "What the session may do on its own: `Read only`, `Workspace write` (default), `On request` or `Full access`. See Permissions." }, "permessiPerAttrezzo": { "description": "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": { "description": "`normale` (default) or `piano`: in Plan mode the session plans first and changes nothing until you approve the plan." }, "provider": { "description": "`cloud` (default) or `local`: a model that runs on this computer." }, "runtimeId": { "description": "With `provider: \"local\"`: the local engine." }, "modelId": { "description": "With `provider: \"local\"`: the installed model." }, "fallbackConsent": { "description": "With `provider: \"local\"`: `true` to allow continuing on a cloud model when the local engine fails." }, "fallbackProviders": { "description": "Up to 8 providers to continue with when the main one fails: `[{ provider, model }]`, each model declared able to use tools." }, "linguaInterfaccia": {} }, "required": [ "taskId" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "MODEL_ID_INVALID: The model name is not one this server recognizes (expected `vendor/model-name`).\nPERMISSIONS_INVALID: The permissions are not among those allowed.\nQUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.\nREASONING_INVALID: The reasoning level is not one of those allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/assistenza": { "post": { "operationId": "post-assistenza", "tags": [ "Sessions" ], "summary": "Ask the built-in help a question: it answers from the help pages that ship with TALOS.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "domanda": { "description": "The question (1 character up to the limit the server sets)." } }, "required": [ "domanda" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/automations": { "get": { "operationId": "get-automations", "tags": [ "Automations" ], "summary": "List the automations: tasks that run on a schedule.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "post-automations", "tags": [ "Automations" ], "summary": "Create an automation: a task template that runs every so many minutes, with an optional daily limit and model.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "istruzioni": {}, "modello": { "description": "The model it runs with, as `vendor/model-name`." }, "coordinazione": {}, "ripeti": {}, "pianificazione": {}, "taskId": { "description": "The task template to start from: an id from `GET /api/v1/tasks`." }, "nome": { "description": "A name for the automation." }, "intervalloMinuti": { "description": "How often it runs, in minutes." }, "limiteAlGiorno": { "description": "The most runs per day." } }, "required": [ "taskId", "intervalloMinuti" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "AUTOMATION_ORIGIN_FORBIDDEN: ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/workspace-launches": { "post": { "operationId": "post-workspace-launches", "tags": [ "Files and folders" ], "summary": "Hand a folder to TALOS from outside the window (the launcher), to start a session on it; answers a launch id.", "description": "Used by the TALOS launcher; it carries its token in the `x-talos-launcher-token` header.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "percorso": { "description": "The folder, as an absolute path." } }, "required": [ "percorso" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/workspace-browser/folders": { "post": { "operationId": "post-workspace-browser-folders", "tags": [ "Files and folders" ], "summary": "Create a folder while choosing where a session works.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "parentPath": { "description": "The folder to create it in." }, "name": { "description": "The new folder’s name." } }, "required": [ "parentPath", "name" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "WORKSPACE_NOT_AVAILABLE: The folder is not available: check that it exists and that TALOS can work in it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/runtime/load": { "post": { "operationId": "post-runtime-load", "tags": [ "Local models" ], "summary": "Load a model into a local runtime.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "runtimeId": { "description": "The runtime." }, "modelId": { "description": "The model to load." }, "contextLength": { "description": "The context length to load it with, in tokens." } }, "required": [ "runtimeId", "modelId" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/runtime/unload": { "post": { "operationId": "post-runtime-unload", "tags": [ "Local models" ], "summary": "Free the memory of a local runtime: stops it, and with it the model it holds.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "runtimeId": { "description": "The runtime." }, "modelId": { "description": "Optional and ignored: unloading stops the runtime." } }, "required": [ "runtimeId" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/local-models/import": { "post": { "operationId": "post-local-models-import", "tags": [ "Local models" ], "summary": "Import a GGUF file from this computer into the model library.", "description": "The body is the file itself (`application/octet-stream`). Headers: `x-talos-model-id` (the id to give it), `x-talos-model-filename`, `x-talos-model-bytes` (the exact size) and, optionally, `x-talos-model-name`.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "LOCAL_IMPORT_INVALID: Check the GGUF file chosen and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/huggingface/download": { "post": { "operationId": "post-huggingface-download", "tags": [ "Local models" ], "summary": "Download a GGUF model from Hugging Face, pinned to an exact commit and checked file by file.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "description": "The id the model gets in the library." }, "repo": { "description": "The repository (`owner/name`)." }, "revision": { "description": "The commit, 40 to 64 hexadecimal digits." }, "files": { "description": "The files, each `{ path, bytes, sha256 }`." }, "bytes": { "description": "The total size in bytes." }, "path": { "description": "The main file." }, "license": { "description": "The license of the model." } }, "required": [ "id", "repo", "revision", "files", "bytes", "path", "license" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/custom": { "post": { "operationId": "post-sessions-custom", "tags": [ "Sessions" ], "summary": "Start a free session on a folder: an assignment in your words, with an optional command that proves the work.", "description": "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 }`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "cartellaId": { "description": "The folder, as an id from `GET /api/v1/projects`." }, "cartellaLibera": { "description": "The folder, as an absolute path." }, "workspaceLaunchId": { "description": "The folder handed over by the launcher (`POST /api/v1/workspace-launches`)." }, "consegna": { "description": "The assignment, in your words." }, "comandoProva": { "description": "The command that proves the work is done (default `npm test`)." }, "modello": { "description": "The model, as OpenRouter names it (`vendor/model-name`), or `:` for a provider’s own endpoint; default: the server’s." }, "modelloPlanner": { "description": "The model that writes plans, in the same form as `modello`." }, "reasoning": { "description": "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": { "description": "`desktop` (default) or `mobile`: a session started from the phone." }, "permessi": { "description": "What the session may do on its own: `Read only`, `Workspace write` (default), `On request` or `Full access`. See Permissions." }, "permessiPerAttrezzo": { "description": "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": { "description": "`normale` (default) or `piano`: in Plan mode the session plans first and changes nothing until you approve the plan." }, "fallbackProviders": { "description": "Up to 8 providers to continue with when the main one fails: `[{ provider, model }]`, each model declared able to use tools." }, "linguaInterfaccia": {}, "immagini": { "description": "Images to attach to the first message: references returned by `POST /api/v1/chat-images`." } }, "required": [ "consegna" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "MODEL_ID_INVALID: The model name is not one this server recognizes (expected `vendor/model-name`).\nPERMISSIONS_INVALID: The permissions are not among those allowed.\nQUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.\nREASONING_INVALID: The reasoning level is not one of those allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/workspace-launches/{launchId}": { "get": { "operationId": "get-workspace-launches-launchid", "tags": [ "Files and folders" ], "summary": "Read a pending launch: the folder it carries, to confirm before the session starts.", "parameters": [ { "name": "launchId", "in": "path", "required": true, "description": "The launch.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/local-models/{modelId}/fit": { "get": { "operationId": "get-local-models-modelid-fit", "tags": [ "Local models" ], "summary": "Whether an installed model fits this machine, and with which settings: measured from the file, the machine and a probe of the runtime, never a real load.", "parameters": [ { "name": "modelId", "in": "path", "required": true, "description": "The installed model.", "schema": { "type": "string" } }, { "name": "profile", "in": "query", "required": false, "description": "The profile to measure for.", "schema": { "type": "string" } }, { "name": "contextTokens", "in": "query", "required": false, "description": "The context length to plan for, in tokens (a positive integer).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "FIT_INVALID: The parameters of the check are not valid.\nQUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/doctor/{reference}": { "get": { "operationId": "get-doctor-reference", "tags": [ "Health and diagnostics" ], "summary": "The detail of a problem the Doctor recorded, by the reference shown on screen (`doctor-` and 12 hexadecimal digits).", "parameters": [ { "name": "reference", "in": "path", "required": true, "description": "The Doctor reference an error answered with (`doctorReference`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/projects/{projectId}/tree": { "get": { "operationId": "get-projects-projectid-tree", "tags": [ "Files and folders" ], "summary": "Preview the files of a project folder before a session opens it.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "The project folder.", "schema": { "type": "string" } }, { "name": "percorso", "in": "query", "required": false, "description": "A subfolder, relative to the project (default: its root).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/artifacts/{artifactId}": { "get": { "operationId": "get-artifacts-artifactid", "tags": [ "Sessions" ], "summary": "An HTML artifact the agent wrote, served sandboxed so its scripts can never reach the app’s own storage.", "parameters": [ { "name": "artifactId", "in": "path", "required": true, "description": "The artifact.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/{providerId}/runtime": { "get": { "operationId": "get-providers-providerid-runtime", "tags": [ "Models and providers" ], "summary": "The runtime settings of one provider: its address and limits.", "parameters": [ { "name": "providerId", "in": "path", "required": true, "description": "The provider (see Providers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "PROVIDER_STORE_UNAVAILABLE: The computer’s key store is not available: check the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "post-providers-providerid-runtime", "tags": [ "Models and providers" ], "summary": "Set a provider’s address, timeout and, for cloud providers, its list of models.", "description": "For a local provider `endpoint` and `timeoutSeconds` are required; for a cloud provider every field is optional; for the external agent (`esterno`) the body is `{ agente }`.", "parameters": [ { "name": "providerId", "in": "path", "required": true, "description": "The provider (see Providers).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "endpoint": { "description": "The address of the provider." }, "timeoutSeconds": { "description": "The timeout, in seconds." }, "modelli": { "description": "Cloud providers: the models to offer." }, "agente": { "description": "The external agent only: its command and settings." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "PROVIDER_STORE_UNAVAILABLE: The computer’s key store is not available: check the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/events": { "get": { "operationId": "get-sessions-sessionid-events", "tags": [ "Turns and approvals" ], "summary": "The live event stream of a session (server-sent events): every message, tool call, approval and state change as it happens.", "description": "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.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "An event stream.", "content": { "text/event-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/export": { "get": { "operationId": "get-sessions-sessionid-export", "tags": [ "Sessions" ], "summary": "Export a whole session: its messages and events, as one JSON document.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tree": { "get": { "operationId": "get-sessions-sessionid-tree", "tags": [ "Files and folders" ], "summary": "The files of the session’s folder, one level at a time.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "percorso", "in": "query", "required": false, "description": "A subfolder, relative to the session’s folder (default: its root).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tree/file": { "get": { "operationId": "get-sessions-sessionid-tree-file", "tags": [ "Files and folders" ], "summary": "Open a file of the session’s folder, to show it in the window.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "percorso", "in": "query", "required": true, "description": "the file, relative to the session’s folder.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tree/search": { "get": { "operationId": "get-sessions-sessionid-tree-search", "tags": [ "Files and folders" ], "summary": "Search the files of the session’s folder by name; the answer says when it was cut short, and which folders were skipped.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": true, "description": "the text to look for.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/file": { "get": { "operationId": "get-sessions-sessionid-file", "tags": [ "Files and folders" ], "summary": "Download a file of the session’s folder, as an attachment (sandboxed, never rendered by the app).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "percorso", "in": "query", "required": true, "description": "the file, relative to the session’s folder.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } } } } }, "/sessions/{sessionId}/hooks": { "get": { "operationId": "get-sessions-sessionid-hooks", "tags": [ "Tools and extensions" ], "summary": "The hooks the session’s project declares, with their real trust state.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tools": { "get": { "operationId": "get-sessions-sessionid-tools", "tags": [ "Tools and extensions" ], "summary": "The tools actually offered to the model in this session, with their permissions.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/mcp": { "get": { "operationId": "get-sessions-sessionid-mcp", "tags": [ "Tools and extensions" ], "summary": "The MCP servers the session’s project declares, with their real trust state.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/processes": { "get": { "operationId": "get-sessions-sessionid-processes", "tags": [ "Sessions" ], "summary": "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).", "description": "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.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/metrics": { "get": { "operationId": "get-sessions-sessionid-metrics", "tags": [ "Sessions" ], "summary": "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.", "description": "A session with no events yet answers `registrato: false` with a `motivo`, never zeros: “not measured” and “zero” are different facts.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "eta", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/status": { "get": { "operationId": "get-sessions-sessionid-git-status", "tags": [ "Git and GitHub" ], "summary": "The Git status of the session’s folder: staged, unstaged, untracked and conflicting files.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/branch": { "get": { "operationId": "get-sessions-sessionid-git-branch", "tags": [ "Git and GitHub" ], "summary": "The current branch of the session’s folder.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/diff": { "get": { "operationId": "get-sessions-sessionid-git-diff", "tags": [ "Git and GitHub" ], "summary": "The diff of one file, staged or not.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "percorso", "in": "query", "required": true, "description": "the file, relative to the repository.", "schema": { "type": "string" } }, { "name": "area", "in": "query", "required": true, "description": "`preparato` (staged) or `lavoro` (working tree).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/log": { "get": { "operationId": "get-sessions-sessionid-git-log", "tags": [ "Git and GitHub" ], "summary": "The history of commits of the current branch.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/branches": { "get": { "operationId": "get-sessions-sessionid-git-branches", "tags": [ "Git and GitHub" ], "summary": "The local branches.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/stashes": { "get": { "operationId": "get-sessions-sessionid-git-stashes", "tags": [ "Git and GitHub" ], "summary": "The changes set aside (stashes).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/remotes": { "get": { "operationId": "get-sessions-sessionid-git-remotes", "tags": [ "Git and GitHub" ], "summary": "The remotes of the repository: name and fetch address.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/sync": { "get": { "operationId": "get-sessions-sessionid-git-sync", "tags": [ "Git and GitHub" ], "summary": "The synchronization state of the current branch: its upstream, commits ahead and behind, the last fetch, and the remote a push goes to.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/changes": { "get": { "operationId": "get-sessions-sessionid-git-changes", "tags": [ "Git and GitHub" ], "summary": "The files a commit changed (or the files changed between two commits).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "a", "in": "query", "required": true, "description": "the commit.", "schema": { "type": "string" } }, { "name": "da", "in": "query", "required": false, "description": "The commit to compare from (default: its parent).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/changes-diff": { "get": { "operationId": "get-sessions-sessionid-git-changes-diff", "tags": [ "Git and GitHub" ], "summary": "The diff of one file in a commit (or between two commits).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "a", "in": "query", "required": true, "description": "the commit.", "schema": { "type": "string" } }, { "name": "percorso", "in": "query", "required": true, "description": "the file.", "schema": { "type": "string" } }, { "name": "da", "in": "query", "required": false, "description": "The commit to compare from (default: its parent).", "schema": { "type": "string" } }, { "name": "prima", "in": "query", "required": false, "description": "The file’s earlier path, when it was renamed.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/github/status": { "get": { "operationId": "get-github-status", "tags": [ "Git and GitHub" ], "summary": "Whether the GitHub CLI (`gh`) that TALOS uses is installed, and whether an account is connected.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/github/install": { "post": { "operationId": "post-github-install", "tags": [ "Git and GitHub" ], "summary": "Download TALOS’s own copy of the GitHub CLI (`gh`).", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GH_STORE_UNAVAILABLE: GitHub is not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/github/login": { "post": { "operationId": "post-github-login", "tags": [ "Git and GitHub" ], "summary": "Connect a GitHub account with the device flow: answers the code to enter on GitHub.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GH_STORE_UNAVAILABLE: GitHub is not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/github/login-cancel": { "post": { "operationId": "post-github-login-cancel", "tags": [ "Git and GitHub" ], "summary": "Cancel a GitHub connection in progress.", "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GH_STORE_UNAVAILABLE: GitHub is not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/github/pulls": { "get": { "operationId": "get-sessions-sessionid-github-pulls", "tags": [ "Git and GitHub" ], "summary": "The pull requests of the current branch and the open ones of the repository.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "post-sessions-sessionid-github-pulls", "tags": [ "Git and GitHub" ], "summary": "Open a pull request from the current branch, which must already be pushed (pushing has its own confirmation; this never pushes).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "titolo": { "description": "The title." }, "testo": { "description": "The description (default empty)." }, "base": { "description": "The branch to merge into." }, "bozza": { "description": "`true` to open it as a draft." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GH_STORE_UNAVAILABLE: GitHub is not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/github/pull-draft": { "get": { "operationId": "get-sessions-sessionid-github-pull-draft", "tags": [ "Git and GitHub" ], "summary": "A draft of the pull request form for the current branch: title, description and base.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "base", "in": "query", "required": false, "description": "The branch to compare with (once at most).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/github/pulls/{pullNumber}/checks": { "get": { "operationId": "get-sessions-sessionid-github-pulls-pullnumber-checks", "tags": [ "Git and GitHub" ], "summary": "The checks (CI) of a pull request.", "description": "The number is digits only, without leading zeros, at most nine.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "pullNumber", "in": "path", "required": true, "description": "The pull request number.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/skills": { "get": { "operationId": "get-sessions-sessionid-skills", "tags": [ "Tools and extensions" ], "summary": "The skills the session’s project declares.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/{resource}/batch": { "post": { "operationId": "post-sessions-sessionid-resource-batch", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Delete several items at once from the library, the notes, the tasks, the memory or the research.", "description": "`resource` is `library`, `notes`, `tasks`, `memory` or `research`. Each id is deleted through the same door as a single delete, independently: the answer lists one outcome per id, in order; there is no global rollback.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "resource", "in": "path", "required": true, "description": "The section: `library`, `notes`, `tasks`, `memory` or `research`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "azione": { "description": "`elimina` (delete)." }, "ids": { "description": "The ids, unique non-empty strings." } }, "required": [ "azione", "ids" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.\nRESEARCH_INVALID: The request is not valid for deep research.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.\nRESEARCH_NOT_FOUND: The research run no longer exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "RESEARCH_CONFLICT: The research run is not in the right state for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/library": { "get": { "operationId": "get-sessions-sessionid-library", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "The library of the session’s project: the documents saved in it.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/library/{itemId}/file": { "get": { "operationId": "get-sessions-sessionid-library-itemid-file", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Download a library item, as an attachment.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "description": "The Library file.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/library/{itemId}/anteprima": { "get": { "operationId": "get-sessions-sessionid-library-itemid-anteprima", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Preview a library item inline (PDF and a few safe types only, sandboxed; any other type is 404).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "description": "The Library file.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/pagine": { "post": { "operationId": "post-sessions-sessionid-pagine", "tags": [ "Files and folders" ], "summary": "Get an address to show an HTML page of the session’s folder, or a library item, inside the window.", "description": "The body is `{ percorso }` or `{ voceId }`. The server checks the file exists, is inside the session’s folder and is a page, and answers an address with a fresh pass (frames do not carry the cookie).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "voceId": { "description": "Or a library item." }, "percorso": { "description": "The page, relative to the session’s folder." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/pagine/{pageId}/{path}": { "get": { "operationId": "get-pagine-pageid-path", "tags": [ "Files and folders" ], "summary": "Serve a page, and the files next to it, by the pass `POST …/pagine` gave (no cookie needed, never outside the page’s folder).", "description": "The type comes from the extension, with `nosniff`; an unknown type is `application/octet-stream`. The query string is ignored (pages use it for caching).", "parameters": [ { "name": "pageId", "in": "path", "required": true, "description": "The page’s pass, from `POST …/pagine`.", "schema": { "type": "string" } }, { "name": "path", "in": "path", "required": true, "description": "The file, inside the page’s folder.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/file/anteprima": { "get": { "operationId": "get-sessions-sessionid-file-anteprima", "tags": [ "Files and folders" ], "summary": "Preview a PDF of the session’s folder inline, sandboxed (the type is decided by the bytes: a file that does not start with `%PDF-` is 404).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "percorso", "in": "query", "required": true, "description": "the file, relative to the session’s folder.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/lettore/ospite": { "get": { "operationId": "get-lettore-ospite", "tags": [ "Files and folders" ], "summary": "The sandboxed guest page in which Word documents and presentations are rendered for preview (the window sends it the bytes).", "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } } } } }, "/sessions/{sessionId}/library/{itemId}/rivela": { "post": { "operationId": "post-sessions-sessionid-library-itemid-rivela", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Show a library item in the file manager of this computer.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "description": "The Library file.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/library/{itemId}/apri": { "post": { "operationId": "post-sessions-sessionid-library-itemid-apri", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Open a library item with this computer’s default application.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "description": "The Library file.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/library/{itemId}": { "patch": { "operationId": "patch-sessions-sessionid-library-itemid", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Rename a library item.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "description": "The Library file.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "nome": { "description": "The new name." } }, "required": [ "nome" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "delete-sessions-sessionid-library-itemid", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Delete a library item; the answer says which one went.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "required": true, "description": "The Library file.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/plugins": { "get": { "operationId": "get-sessions-sessionid-plugins", "tags": [ "Tools and extensions" ], "summary": "The plugins the session’s project declares, with their real trust state (a plugin runs code; a skill does not).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/notes": { "get": { "operationId": "get-sessions-sessionid-notes", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Your notes (global to you, not to the session’s project).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "post-sessions-sessionid-notes", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Create a note.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "titolo": { "description": "The title." }, "contenuto": { "description": "The text." }, "formato": { "description": "`markdown` or `testo`; detected when absent." } }, "required": [ "titolo", "contenuto" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/notes/{noteId}": { "get": { "operationId": "get-sessions-sessionid-notes-noteid", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Read a note.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "noteId", "in": "path", "required": true, "description": "The note.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "patch-sessions-sessionid-notes-noteid", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Change a note: only the fields sent change (at least one).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "noteId", "in": "path", "required": true, "description": "The note.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "titolo": { "description": "The new title." }, "contenuto": { "description": "The new text." }, "formato": { "description": "`markdown`, `testo`, or `null` to detect it again." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "delete-sessions-sessionid-notes-noteid", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Delete a note.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "noteId", "in": "path", "required": true, "description": "The note.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tasks": { "get": { "operationId": "get-sessions-sessionid-tasks", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Your tasks (global to you, like the notes).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "post-sessions-sessionid-tasks", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Create a task.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "titolo": { "description": "The title." }, "descrizione": { "description": "A description, or `null`." }, "priorita": { "description": "`low`, `normal` (default) or `high`." } }, "required": [ "titolo" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tasks/{taskId}": { "get": { "operationId": "get-sessions-sessionid-tasks-taskid", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Read a task.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "taskId", "in": "path", "required": true, "description": "The task.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "patch-sessions-sessionid-tasks-taskid", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Change a task’s title, description or priority (never its state: that has its own door).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "taskId", "in": "path", "required": true, "description": "The task.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "titolo": { "description": "The new title." }, "descrizione": { "description": "The new description, or `null`." }, "priorita": { "description": "`low`, `normal` or `high`." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "delete-sessions-sessionid-tasks-taskid", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Delete a task.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "taskId", "in": "path", "required": true, "description": "The task.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tasks/{taskId}/stato": { "post": { "operationId": "post-sessions-sessionid-tasks-taskid-stato", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Set a task’s state.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "taskId", "in": "path", "required": true, "description": "The task.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "stato": { "description": "`todo`, `doing` or `done`." } }, "required": [ "stato" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/memory": { "get": { "operationId": "get-sessions-sessionid-memory", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Your memory: what TALOS remembers about you and your work, across sessions.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "post-sessions-sessionid-memory", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Add a memory. The answer says `duplicato: true` when the same memory already existed.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "titolo": { "description": "The title." }, "contenuto": { "description": "The text." }, "genere": { "description": "The kind: `preference`, `project_fact`, `procedure` or `policy_note`." } }, "required": [ "titolo", "contenuto" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/memory/{memoryId}": { "get": { "operationId": "get-sessions-sessionid-memory-memoryid", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Read a memory.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "memoryId", "in": "path", "required": true, "description": "The memory.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "patch-sessions-sessionid-memory-memoryid", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Change a memory: only the fields sent change (at least one).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "memoryId", "in": "path", "required": true, "description": "The memory.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "titolo": { "description": "The new title." }, "contenuto": { "description": "The new text." }, "genere": { "description": "`preference`, `project_fact`, `procedure` or `policy_note`." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "delete-sessions-sessionid-memory-memoryid", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Delete a memory.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "memoryId", "in": "path", "required": true, "description": "The memory.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/me/notes": { "get": { "operationId": "get-me-notes", "tags": [ "Health and diagnostics" ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "post-me-notes", "tags": [ "Health and diagnostics" ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/me/tasks": { "get": { "operationId": "get-me-tasks", "tags": [ "Health and diagnostics" ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "post-me-tasks", "tags": [ "Health and diagnostics" ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/me/memory": { "get": { "operationId": "get-me-memory", "tags": [ "Health and diagnostics" ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "post-me-memory", "tags": [ "Health and diagnostics" ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/me/notes/{noteId}": { "get": { "operationId": "get-me-notes-noteid", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "noteId", "in": "path", "required": true, "description": "The note.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "patch-me-notes-noteid", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "noteId", "in": "path", "required": true, "description": "The note.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "delete-me-notes-noteid", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "noteId", "in": "path", "required": true, "description": "The note.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/me/tasks/{taskId}": { "get": { "operationId": "get-me-tasks-taskid", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "The task.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "patch-me-tasks-taskid", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "The task.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "delete-me-tasks-taskid", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "The task.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/me/memory/{memoryId}": { "get": { "operationId": "get-me-memory-memoryid", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "memoryId", "in": "path", "required": true, "description": "The memory.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "patch-me-memory-memoryid", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "memoryId", "in": "path", "required": true, "description": "The memory.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "delete-me-memory-memoryid", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "memoryId", "in": "path", "required": true, "description": "The memory.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/me/tasks/{taskId}/stato": { "post": { "operationId": "post-me-tasks-taskid-stato", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "The task.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "stato": {} }, "required": [ "stato" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/me/notes/batch": { "post": { "operationId": "post-me-notes-batch", "tags": [ "Health and diagnostics" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "azione": {}, "ids": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.\nRESEARCH_INVALID: The request is not valid for deep research.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.\nRESEARCH_NOT_FOUND: The research run no longer exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "RESEARCH_CONFLICT: The research run is not in the right state for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/me/tasks/batch": { "post": { "operationId": "post-me-tasks-batch", "tags": [ "Health and diagnostics" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "azione": {}, "ids": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.\nRESEARCH_INVALID: The request is not valid for deep research.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.\nRESEARCH_NOT_FOUND: The research run no longer exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "RESEARCH_CONFLICT: The research run is not in the right state for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/me/memory/batch": { "post": { "operationId": "post-me-memory-batch", "tags": [ "Health and diagnostics" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "azione": {}, "ids": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.\nRESEARCH_INVALID: The request is not valid for deep research.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.\nRESEARCH_NOT_FOUND: The research run no longer exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "RESEARCH_CONFLICT: The research run is not in the right state for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/messages/{messageId}": { "delete": { "operationId": "delete-sessions-sessionid-messages-messageid", "tags": [ "Sessions" ], "summary": "Remove a message from the conversation. Refused with 409 while the session is still running.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "description": "The message.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/research": { "get": { "operationId": "get-sessions-sessionid-research", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "The deep research runs of the session’s project.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/research/{researchId}/pausa": { "post": { "operationId": "post-sessions-sessionid-research-researchid-pausa", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Pause a research run.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "researchId", "in": "path", "required": true, "description": "The research.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.\nRESEARCH_INVALID: The request is not valid for deep research.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.\nRESEARCH_NOT_FOUND: The research run no longer exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "RESEARCH_CONFLICT: The research run is not in the right state for this action.\nRESEARCH_RECHECK_UNAVAILABLE: This research run cannot be checked again yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/research/{researchId}/ripresa": { "post": { "operationId": "post-sessions-sessionid-research-researchid-ripresa", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Resume a paused research run.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "researchId", "in": "path", "required": true, "description": "The research.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.\nRESEARCH_INVALID: The request is not valid for deep research.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.\nRESEARCH_NOT_FOUND: The research run no longer exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "RESEARCH_CONFLICT: The research run is not in the right state for this action.\nRESEARCH_RECHECK_UNAVAILABLE: This research run cannot be checked again yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/research/{researchId}/riverifica": { "post": { "operationId": "post-sessions-sessionid-research-researchid-riverifica", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Check the sources of a finished research run again.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "researchId", "in": "path", "required": true, "description": "The research.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.\nRESEARCH_INVALID: The request is not valid for deep research.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.\nRESEARCH_NOT_FOUND: The research run no longer exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "RESEARCH_CONFLICT: The research run is not in the right state for this action.\nRESEARCH_RECHECK_UNAVAILABLE: This research run cannot be checked again yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/research/{researchId}/esporta": { "get": { "operationId": "get-sessions-sessionid-research-researchid-esporta", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Export a research run as a file.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "researchId", "in": "path", "required": true, "description": "The research.", "schema": { "type": "string" } }, { "name": "formato", "in": "query", "required": true, "description": "`md`, `html`, `pdf`, `docx`, `json`, `bib`, `ris` or `fonti` (the sources, as Markdown).", "schema": { "type": "string" } }, { "name": "tono", "in": "query", "required": false, "description": "For the report: `report` (default), `brief` or `dossier`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "application/octet-stream": {} } }, "400": { "description": "RESEARCH_INVALID: The request is not valid for deep research.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.\nRESEARCH_NOT_FOUND: The research run no longer exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/research/{researchId}": { "get": { "operationId": "get-sessions-sessionid-research-researchid", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "One research run: its question, plan, sources and report.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "researchId", "in": "path", "required": true, "description": "The research.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.\nRESEARCH_INVALID: The request is not valid for deep research.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.\nRESEARCH_NOT_FOUND: The research run no longer exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "RESEARCH_CONFLICT: The research run is not in the right state for this action.\nRESEARCH_RECHECK_UNAVAILABLE: This research run cannot be checked again yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "operationId": "delete-sessions-sessionid-research-researchid", "tags": [ "Library, notes, tasks, memory and research" ], "summary": "Delete a research run; when it cannot be deleted now the answer is `RESEARCH_CONFLICT` with the reason.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "researchId", "in": "path", "required": true, "description": "The research.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.\nRESEARCH_INVALID: The request is not valid for deep research.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.\nRESEARCH_NOT_FOUND: The research run no longer exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "RESEARCH_CONFLICT: The research run is not in the right state for this action.\nRESEARCH_RECHECK_UNAVAILABLE: This research run cannot be checked again yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tool-forge": { "get": { "operationId": "get-sessions-sessionid-tool-forge", "tags": [ "Tools and extensions" ], "summary": "The forged tools installed (tools the agent wrote and you enabled), global to you.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/children": { "get": { "operationId": "get-sessions-sessionid-children", "tags": [ "Sessions" ], "summary": "The sub-agents a session started: its real children, with their state.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/agent-timeline": { "get": { "operationId": "get-sessions-sessionid-agent-timeline", "tags": [ "Sessions" ], "summary": "The timeline of the agents of a session: who did what, in order.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "description": "Only entries after this sequence number.", "schema": { "type": "string" } }, { "name": "through", "in": "query", "required": false, "description": "Only entries up to this sequence number.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many entries.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/terminals": { "get": { "operationId": "get-sessions-sessionid-terminals", "tags": [ "Terminals" ], "summary": "The terminals open in a session.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "post-sessions-sessionid-terminals", "tags": [ "Terminals" ], "summary": "Open a terminal in the session’s folder (the body must be empty).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TERMINAL_STORE_UNAVAILABLE: Terminals are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/search-source/key": { "post": { "operationId": "post-search-source-key", "tags": [ "Models and providers" ], "summary": "Save the key of a search source.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "source": { "description": "The source." }, "key": { "description": "The key." } }, "required": [ "source", "key" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "SEARCH_NOT_READY: The search source is not ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "SEARCH_STORE_UNAVAILABLE: The search key store is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/search-source/key/remove": { "post": { "operationId": "post-search-source-key-remove", "tags": [ "Models and providers" ], "summary": "Remove the key of a search source.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "source": { "description": "The source." } }, "required": [ "source" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "SEARCH_NOT_READY: The search source is not ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "SEARCH_STORE_UNAVAILABLE: The search key store is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/search-source/test": { "post": { "operationId": "post-search-source-test", "tags": [ "Models and providers" ], "summary": "Try the active search source with a query (it must be ready).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "query": { "description": "What to search for (a default query otherwise)." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "SEARCH_NOT_READY: The search source is not ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "SEARCH_STORE_UNAVAILABLE: The search key store is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/{providerId}/test": { "post": { "operationId": "post-providers-providerid-test", "tags": [ "Models and providers" ], "summary": "Test a provider: whether it answers with the key and address configured.", "parameters": [ { "name": "providerId", "in": "path", "required": true, "description": "The provider (see Providers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "PROVIDER_STORE_UNAVAILABLE: The computer’s key store is not available: check the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/{providerId}/key": { "post": { "operationId": "post-providers-providerid-key", "tags": [ "Models and providers" ], "summary": "Save the key of a provider (the single key).", "parameters": [ { "name": "providerId", "in": "path", "required": true, "description": "The provider (see Providers).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "key": { "description": "The key." } }, "required": [ "key" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "PROVIDER_STORE_UNAVAILABLE: The computer’s key store is not available: check the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/{providerId}/keys": { "post": { "operationId": "post-providers-providerid-keys", "tags": [ "Models and providers" ], "summary": "Add a key to the provider’s pool of keys.", "parameters": [ { "name": "providerId", "in": "path", "required": true, "description": "The provider (see Providers).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "key": { "description": "The key." }, "priorita": { "description": "Its priority in the pool." } }, "required": [ "key" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "PROVIDER_STORE_UNAVAILABLE: The computer’s key store is not available: check the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/{providerId}/key/remove": { "post": { "operationId": "post-providers-providerid-key-remove", "tags": [ "Models and providers" ], "summary": "Remove the single key of a provider (the body must be empty).", "parameters": [ { "name": "providerId", "in": "path", "required": true, "description": "The provider (see Providers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "PROVIDER_STORE_UNAVAILABLE: The computer’s key store is not available: check the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/{providerId}/keys/remove": { "post": { "operationId": "post-providers-providerid-keys-remove", "tags": [ "Models and providers" ], "summary": "Remove a key from the pool, by its fingerprint.", "parameters": [ { "name": "providerId", "in": "path", "required": true, "description": "The provider (see Providers).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "impronta": { "description": "The SHA-256 fingerprint of the key (64 hexadecimal digits)." } }, "required": [ "impronta" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "PROVIDER_STORE_UNAVAILABLE: The computer’s key store is not available: check the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/providers/{providerId}/runtime/reset": { "post": { "operationId": "post-providers-providerid-runtime-reset", "tags": [ "Models and providers" ], "summary": "Put a provider’s address back to its default (the body must be empty).", "parameters": [ { "name": "providerId", "in": "path", "required": true, "description": "The provider (see Providers).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "PROVIDER_STORE_UNAVAILABLE: The computer’s key store is not available: check the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/automations/{automationId}/toggle": { "post": { "operationId": "post-automations-automationid-toggle", "tags": [ "Automations" ], "summary": "Turn an automation on or off.", "parameters": [ { "name": "automationId", "in": "path", "required": true, "description": "The automation.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "attiva": { "description": "`true` or `false`." } }, "required": [ "attiva" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/automations/{automationId}/coordinazione": { "post": { "operationId": "post-automations-automationid-coordinazione", "tags": [ "Automations" ], "parameters": [ { "name": "automationId", "in": "path", "required": true, "description": "The automation.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "coordinazione": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/automations/{automationId}/elimina": { "post": { "operationId": "post-automations-automationid-elimina", "tags": [ "Automations" ], "summary": "Delete an automation.", "parameters": [ { "name": "automationId", "in": "path", "required": true, "description": "The automation.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/automations/{automationId}/modifica": { "post": { "operationId": "post-automations-automationid-modifica", "tags": [ "Automations" ], "parameters": [ { "name": "automationId", "in": "path", "required": true, "description": "The automation.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "decisione": {}, "modello": { "description": "The model, as OpenRouter names it (`vendor/model-name`), or `:` for a provider’s own endpoint; default: the server’s." }, "coordinazione": {}, "ripeti": {}, "pianificazione": {}, "contesto": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: An unexpected error on the server; the Doctor has the detail, under the reference shown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/automations/{automationId}/esegui": { "post": { "operationId": "post-automations-automationid-esegui", "tags": [ "Automations" ], "parameters": [ { "name": "automationId", "in": "path", "required": true, "description": "The automation.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "decisione": {}, "modello": { "description": "The model, as OpenRouter names it (`vendor/model-name`), or `:` for a provider’s own endpoint; default: the server’s." }, "coordinazione": {}, "ripeti": {}, "pianificazione": {}, "contesto": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: An unexpected error on the server; the Doctor has the detail, under the reference shown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/automations/{automationId}/ferma": { "post": { "operationId": "post-automations-automationid-ferma", "tags": [ "Automations" ], "parameters": [ { "name": "automationId", "in": "path", "required": true, "description": "The automation.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "decisione": {}, "modello": { "description": "The model, as OpenRouter names it (`vendor/model-name`), or `:` for a provider’s own endpoint; default: the server’s." }, "coordinazione": {}, "ripeti": {}, "pianificazione": {}, "contesto": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: An unexpected error on the server; the Doctor has the detail, under the reference shown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/automations/{automationId}/runs/{runId}/letta": { "post": { "operationId": "post-automations-automationid-runs-runid-letta", "tags": [ "Automations" ], "parameters": [ { "name": "automationId", "in": "path", "required": true, "description": "The automation.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "decisione": {}, "modello": { "description": "The model, as OpenRouter names it (`vendor/model-name`), or `:` for a provider’s own endpoint; default: the server’s." }, "coordinazione": {}, "ripeti": {}, "pianificazione": {}, "contesto": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: An unexpected error on the server; the Doctor has the detail, under the reference shown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/automations/{automationId}/runs/{runId}/proposta": { "post": { "operationId": "post-automations-automationid-runs-runid-proposta", "tags": [ "Automations" ], "parameters": [ { "name": "automationId", "in": "path", "required": true, "description": "The automation.", "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "description": "The workflow run.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "decisione": {}, "modello": { "description": "The model, as OpenRouter names it (`vendor/model-name`), or `:` for a provider’s own endpoint; default: the server’s." }, "coordinazione": {}, "ripeti": {}, "pianificazione": {}, "contesto": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "INTERNAL_ERROR: An unexpected error on the server; the Doctor has the detail, under the reference shown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/automations/{automationId}/runs": { "get": { "operationId": "get-automations-automationid-runs", "tags": [ "Automations" ], "parameters": [ { "name": "automationId", "in": "path", "required": true, "description": "The automation.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/automations/inbox": { "get": { "operationId": "get-automations-inbox", "tags": [ "Automations" ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/local-models/{modelId}/rename": { "post": { "operationId": "post-local-models-modelid-rename", "tags": [ "Local models" ], "summary": "Rename an installed model.", "parameters": [ { "name": "modelId", "in": "path", "required": true, "description": "The installed model.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "description": "The new name." } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/local-models/{modelId}/copy-path": { "post": { "operationId": "post-local-models-modelid-copy-path", "tags": [ "Local models" ], "summary": "The path of an installed model’s file, to copy it.", "parameters": [ { "name": "modelId", "in": "path", "required": true, "description": "The installed model.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/local-models/{modelId}/delete": { "post": { "operationId": "post-local-models-modelid-delete", "tags": [ "Local models" ], "summary": "Delete an installed model.", "parameters": [ { "name": "modelId", "in": "path", "required": true, "description": "The installed model.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/local-models/{modelId}/qualify": { "post": { "operationId": "post-local-models-modelid-qualify", "tags": [ "Local models" ], "summary": "Qualify an installed model: run it for one real turn to measure how it behaves on this machine (it loads the model, so it needs your consent).", "parameters": [ { "name": "modelId", "in": "path", "required": true, "description": "The installed model.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "consent": { "description": "`true`: you agree to load and run the model." }, "profile": { "description": "The profile to measure for." }, "contextTokens": { "description": "The context length, in tokens (a positive integer)." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "FIT_INVALID: The parameters of the check are not valid.\nQUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/huggingface/downloads/{downloadId}/pause": { "post": { "operationId": "post-huggingface-downloads-downloadid-pause", "tags": [ "Local models" ], "summary": "Pause a model download.", "parameters": [ { "name": "downloadId", "in": "path", "required": true, "description": "The download.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/huggingface/downloads/{downloadId}/resume": { "post": { "operationId": "post-huggingface-downloads-downloadid-resume", "tags": [ "Local models" ], "summary": "Resume a paused model download.", "parameters": [ { "name": "downloadId", "in": "path", "required": true, "description": "The download.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/huggingface/downloads/{downloadId}/cancel": { "post": { "operationId": "post-huggingface-downloads-downloadid-cancel", "tags": [ "Local models" ], "summary": "Cancel a model download.", "parameters": [ { "name": "downloadId", "in": "path", "required": true, "description": "The download.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "RUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/cancel": { "post": { "operationId": "post-sessions-sessionid-cancel", "tags": [ "Turns and approvals" ], "summary": "Stop a running session.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/terminals/{terminalId}/close": { "post": { "operationId": "post-sessions-sessionid-terminals-terminalid-close", "tags": [ "Terminals" ], "summary": "Close a terminal (the body must be empty).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "The terminal.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "TERMINAL_STORE_UNAVAILABLE: Terminals are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/stage": { "post": { "operationId": "post-sessions-sessionid-git-stage", "tags": [ "Git and GitHub" ], "summary": "Stage files.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "percorsi": { "description": "The files, relative to the repository." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/unstage": { "post": { "operationId": "post-sessions-sessionid-git-unstage", "tags": [ "Git and GitHub" ], "summary": "Unstage files.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "percorsi": { "description": "The files, relative to the repository." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/commit": { "post": { "operationId": "post-sessions-sessionid-git-commit", "tags": [ "Git and GitHub" ], "summary": "Commit files with a message.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "percorsi": { "description": "The files to commit." }, "messaggio": { "description": "The commit message." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/discard": { "post": { "operationId": "post-sessions-sessionid-git-discard", "tags": [ "Git and GitHub" ], "summary": "Discard the changes of files in the working tree.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "percorsi": { "description": "The files." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/commit-staged": { "post": { "operationId": "post-sessions-sessionid-git-commit-staged", "tags": [ "Git and GitHub" ], "summary": "Commit what is staged.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "messaggio": { "description": "The commit message." }, "impronta": { "description": "The fingerprint of the staged changes the window saw: if they changed since, nothing is committed." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/amend": { "post": { "operationId": "post-sessions-sessionid-git-amend", "tags": [ "Git and GitHub" ], "summary": "Amend the last commit.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "messaggio": { "description": "The new message." }, "impronta": { "description": "The fingerprint of the staged changes the window saw." }, "commit": { "description": "The commit the window saw as the last one." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/undo-commit": { "post": { "operationId": "post-sessions-sessionid-git-undo-commit", "tags": [ "Git and GitHub" ], "summary": "Undo the last commit, keeping its changes.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "commit": { "description": "The commit the window saw as the last one." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/switch": { "post": { "operationId": "post-sessions-sessionid-git-switch", "tags": [ "Git and GitHub" ], "summary": "Switch to another branch.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "ramo": { "description": "The branch." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/branch-create": { "post": { "operationId": "post-sessions-sessionid-git-branch-create", "tags": [ "Git and GitHub" ], "summary": "Create a branch.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "ramo": { "description": "The new branch." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/branch-rename": { "post": { "operationId": "post-sessions-sessionid-git-branch-rename", "tags": [ "Git and GitHub" ], "summary": "Rename a branch.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "da": { "description": "The current name." }, "a": { "description": "The new name." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/branch-delete": { "post": { "operationId": "post-sessions-sessionid-git-branch-delete", "tags": [ "Git and GitHub" ], "summary": "Delete a branch. The first attempt refuses an unmerged branch and says so; `forza: true` deletes it anyway.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "ramo": { "description": "The branch." }, "forza": { "description": "`true` to delete it even if not merged." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/stash": { "post": { "operationId": "post-sessions-sessionid-git-stash", "tags": [ "Git and GitHub" ], "summary": "Set the changes aside (stash).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "messaggio": { "description": "A message for the stash." }, "conNuovi": { "description": "`true` to include untracked files." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/stash-pop": { "post": { "operationId": "post-sessions-sessionid-git-stash-pop", "tags": [ "Git and GitHub" ], "summary": "Bring back a stash and drop it.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "indice": { "description": "The stash’s position." }, "commit": { "description": "The stash’s commit the window saw, so the right one is taken." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/stash-drop": { "post": { "operationId": "post-sessions-sessionid-git-stash-drop", "tags": [ "Git and GitHub" ], "summary": "Drop a stash.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "indice": { "description": "The stash’s position." }, "commit": { "description": "The stash’s commit the window saw." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/hunk": { "post": { "operationId": "post-sessions-sessionid-git-hunk", "tags": [ "Git and GitHub" ], "summary": "Stage, unstage or discard one hunk of a file’s diff (applied like GitHub Desktop, checked before it is applied: a hunk that does not apply changes nothing).", "description": "Only tracked text files: a new or binary file is staged whole (`GIT_HUNK_UNSUPPORTED`). If the file changed since the window read its diff, the hunk is refused (`GIT_DIFF_CHANGED`).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "percorso": { "description": "The file." }, "area": { "description": "`lavoro` (working tree) or `preparato` (staged)." }, "indice": { "description": "Which hunk of the diff." }, "impronta": { "description": "The fingerprint of the diff the window saw." }, "azione": { "description": "`prepara` (stage), `togli` (unstage) or `annulla` (discard)." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/commit-message": { "post": { "operationId": "post-sessions-sessionid-git-commit-message", "tags": [ "Git and GitHub" ], "summary": "Ask the session’s model to write a commit message from the staged diff.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "bozza": { "description": "A first line you already wrote, to keep." }, "lingua": { "description": "`en` for English; Italian otherwise." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/fetch": { "post": { "operationId": "post-sessions-sessionid-git-fetch", "tags": [ "Git and GitHub" ], "summary": "Fetch from a remote.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "remoto": { "description": "The remote (default: the branch’s own)." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/fetch-stop": { "post": { "operationId": "post-sessions-sessionid-git-fetch-stop", "tags": [ "Git and GitHub" ], "summary": "Stop a fetch in progress.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/pull": { "post": { "operationId": "post-sessions-sessionid-git-pull", "tags": [ "Git and GitHub" ], "summary": "Pull the current branch.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/push": { "post": { "operationId": "post-sessions-sessionid-git-push", "tags": [ "Git and GitHub" ], "summary": "Push the current branch.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "remoto": { "description": "The remote (default: the branch’s own)." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/rename": { "post": { "operationId": "post-sessions-sessionid-rename", "tags": [ "Sessions" ], "summary": "Rename a session.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "nome": { "description": "The new name." } }, "required": [ "nome" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/delete": { "post": { "operationId": "post-sessions-sessionid-delete", "tags": [ "Sessions" ], "summary": "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.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "WORKFLOW_RUN_NOT_FINISHED: A workflow of this conversation is still running: cancel it first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tree/rename": { "post": { "operationId": "post-sessions-sessionid-tree-rename", "tags": [ "Files and folders" ], "summary": "Rename a file or folder of the session’s folder.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "percorso": { "description": "The file or folder." }, "nuovoNome": { "description": "The new name." } }, "required": [ "percorso", "nuovoNome" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tree/delete": { "post": { "operationId": "post-sessions-sessionid-tree-delete", "tags": [ "Files and folders" ], "summary": "Delete a file or folder of the session’s folder.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "percorso": { "description": "The file or folder." } }, "required": [ "percorso" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tree/reveal": { "post": { "operationId": "post-sessions-sessionid-tree-reveal", "tags": [ "Files and folders" ], "summary": "Show a file in the file manager of this computer.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "percorso": { "description": "The file." } }, "required": [ "percorso" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tree/open": { "post": { "operationId": "post-sessions-sessionid-tree-open", "tags": [ "Files and folders" ], "summary": "Open a folder in the file manager of this computer.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "percorso": { "description": "The folder; an empty string is the session’s folder itself." } }, "required": [ "percorso" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tree/move": { "post": { "operationId": "post-sessions-sessionid-tree-move", "tags": [ "Files and folders" ], "summary": "Move a file or folder into another folder of the session’s folder.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "percorso": { "description": "What to move." }, "cartellaDestinazione": { "description": "Where to." } }, "required": [ "percorso", "cartellaDestinazione" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tree/copy": { "post": { "operationId": "post-sessions-sessionid-tree-copy", "tags": [ "Files and folders" ], "summary": "Duplicate a file or folder in the same place, named like a file manager does: “name (copia).ext”, then “(copia 2)” and so on.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "percorso": { "description": "What to copy." } }, "required": [ "percorso" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tree/create": { "post": { "operationId": "post-sessions-sessionid-tree-create", "tags": [ "Files and folders" ], "summary": "Create a file or a folder.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "percorsoBase": { "description": "The folder to create it in." }, "nome": { "description": "Its name." }, "tipo": { "description": "`file` or `cartella` (folder)." } }, "required": [ "percorsoBase", "nome", "tipo" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/stop": { "post": { "operationId": "post-sessions-sessionid-stop", "tags": [ "Turns and approvals" ], "summary": "Stop the session’s current turn.", "description": "The body may be empty; with `{ redirectId }` it also cancels a redirection in flight.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "redirectId": { "description": "The redirection to cancel (a UUID)." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/processes/{processeId}/stop": { "post": { "operationId": "post-sessions-sessionid-processes-processeid-stop", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "processeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "PROCESS_NOT_RUNNING: ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/processes/{processeId}/sfondo": { "post": { "operationId": "post-sessions-sessionid-processes-processeid-sfondo", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "processeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "PROCESS_NOT_RUNNING: ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/mcp-elicitation": { "post": { "operationId": "post-sessions-sessionid-mcp-elicitation", "tags": [ "Tools and extensions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "requestId": {}, "risposta": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/redirect": { "post": { "operationId": "post-sessions-sessionid-redirect", "tags": [ "Turns and approvals" ], "summary": "Redirect the running turn with a new message: the agent takes it into account without starting over.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "messaggio": { "description": "The message." }, "redirectId": { "description": "An id for this redirection (a UUID), to cancel it with `…/stop`." } }, "required": [ "messaggio" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/fork": { "post": { "operationId": "post-sessions-sessionid-fork", "tags": [ "Sessions" ], "summary": "Fork a session: a new session that starts from the same conversation.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/resume": { "post": { "operationId": "post-sessions-sessionid-resume", "tags": [ "Sessions" ], "summary": "Resume a session: without a body, it resumes an interrupted turn; with a message, it is the next turn of the chat.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "messaggio": { "description": "A new message (a non-empty string)." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/settings": { "post": { "operationId": "post-sessions-sessionid-settings", "tags": [ "Sessions" ], "summary": "Change a session’s preferences: model, planner model, reasoning, permissions, fallback providers or mode (at least one).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "modello": { "description": "The model, as OpenRouter names it (`vendor/model-name`), or `:` for a provider’s own endpoint; default: the server’s." }, "modelloPlanner": { "description": "The model that writes plans, in the same form as `modello`." }, "reasoning": { "description": "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": { "description": "What the session may do on its own: `Read only`, `Workspace write` (default), `On request` or `Full access`. See Permissions." }, "permessiPerAttrezzo": { "description": "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": {}, "rispettaNega": {}, "fallbackProviders": { "description": "Up to 8 providers to continue with when the main one fails: `[{ provider, model }]`, each model declared able to use tools." }, "modalitaOperativa": { "description": "`normale` or `piano` (plan first). The former `workflow` mode is retired (`MODE_WORKFLOW_RETIRED`)." }, "linguaInterfaccia": {} }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "MODEL_ID_INVALID: The model name is not one this server recognizes (expected `vendor/model-name`).\nPERMISSIONS_INVALID: The permissions are not among those allowed.\nQUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.\nREASONING_INVALID: The reasoning level is not one of those allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/compact": { "post": { "operationId": "post-sessions-sessionid-compact", "tags": [ "Sessions" ], "summary": "Compact the conversation now: older turns are summarized so the context has room again.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/migliora-prompt": { "post": { "operationId": "post-sessions-sessionid-migliora-prompt", "tags": [ "Sessions" ], "summary": "Improve a prompt before sending it: the session’s model (local or cloud) rewrites it as a clearer brief, without sending it.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "prompt": { "description": "The text to improve (up to 12,000 characters)." }, "profondita": { "description": "How far to go: `concisa` (`concise`), `equilibrata` (`balanced`, default) or `estesa` (`extended`)." } }, "required": [ "prompt" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "PROVIDER_RUNTIME_UNAVAILABLE: The provider’s preferences could not be saved: check the Doctor.\nRUNTIME_NOT_AVAILABLE: The local runtime is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/shell": { "post": { "operationId": "post-sessions-sessionid-shell", "tags": [ "Turns and approvals" ], "summary": "Run a command of yours in the session’s folder (a `!` command in the chat); it is recorded in the process ledger.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "comando": { "description": "The command." } }, "required": [ "comando" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/dove-girano-i-comandi": { "post": { "operationId": "post-sessions-sessionid-dove-girano-i-comandi", "tags": [ "Turns and approvals" ], "summary": "Choose where the session’s commands run on Windows: WSL 2 or Windows itself.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "dove": { "description": "`wsl2`, `windows`, or `null` for the default." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/comandi-nella-conversazione": { "post": { "operationId": "post-sessions-sessionid-comandi-nella-conversazione", "tags": [ "Turns and approvals" ], "summary": "Choose whether your `!` commands and their output enter the model’s conversation (off by default).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "acceso": { "description": "`true` to include them." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/impostazioni-comandi": { "get": { "operationId": "get-sessions-sessionid-impostazioni-comandi", "tags": [ "Turns and approvals" ], "summary": "Read the two command settings of a session: where commands run, and whether they enter the conversation.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/pending": { "get": { "operationId": "get-sessions-sessionid-pending", "tags": [ "Health and diagnostics" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/approve": { "post": { "operationId": "post-sessions-sessionid-approve", "tags": [ "Turns and approvals" ], "summary": "Answer an approval request of the agent (with the “On request” permission): allow or deny that one action.", "description": "The request id is required: there is never an answer “to the last pending request”.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "description": "The request." }, "approvato": { "description": "`true` to allow, `false` to deny." }, "ambito": {}, "rispostoDa": {}, "automazioneModificata": {} }, "required": [ "requestId", "approvato" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/question": { "post": { "operationId": "post-sessions-sessionid-question", "tags": [ "Turns and approvals" ], "summary": "Answer a question the agent asked you.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "description": "The question." }, "status": { "description": "`answered`, `skipped`, `cancelled` or `expired`." }, "answers": { "description": "With `answered` only: the answers, by question." }, "rispostoDa": {} }, "required": [ "requestId", "status" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/plan-decision": { "post": { "operationId": "post-sessions-sessionid-plan-decision", "tags": [ "Turns and approvals" ], "summary": "Decide on a plan the agent proposed: proceed, proceed accepting its changes, start a clean conversation with it, or keep planning.", "description": "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.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "description": "The plan request." }, "decisione": { "description": "`procedi-con-conferma`, `procedi-accetta-modifiche`, `conversazione-pulita` or `continua-a-pianificare`." }, "hash": { "description": "The plan’s fingerprint, `sha256:` and 64 hexadecimal digits." }, "feedback": { "description": "With `continua-a-pianificare` only: what to change (up to 4,000 characters)." } }, "required": [ "requestId", "decisione", "hash" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "PAYLOAD_LIMIT: The body is larger than the server accepts: shorten it, or put the text in a file and attach it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/queue": { "get": { "operationId": "get-sessions-sessionid-queue", "tags": [ "Turns and approvals" ], "summary": "The messages waiting in the session’s queue, sent after the current turn.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "post-sessions-sessionid-queue", "tags": [ "Turns and approvals" ], "summary": "Queue a message to send after the current turn.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "messaggio": { "description": "The message." } }, "required": [ "messaggio" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/queue/annulla": { "post": { "operationId": "post-sessions-sessionid-queue-annulla", "tags": [ "Turns and approvals" ], "summary": "Remove a queued message, or empty the queue.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "description": "One message to remove; without it, the whole queue." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/queue/invia": { "post": { "operationId": "post-sessions-sessionid-queue-invia", "tags": [ "Turns and approvals" ], "summary": "Send a queued message now: during a turn it enters as a correction, otherwise it resumes the session.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "description": "The queued message." } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/hooks/{hookId}/trust": { "post": { "operationId": "post-sessions-sessionid-hooks-hookid-trust", "tags": [ "Tools and extensions" ], "summary": "Trust a hook of the project: the only way it becomes able to run. The server reads its fingerprint from disk; nothing comes from the client.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "hookId", "in": "path", "required": true, "description": "The hook.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/tool-forge/{toolId}/enable": { "post": { "operationId": "post-sessions-sessionid-tool-forge-toolid-enable", "tags": [ "Tools and extensions" ], "summary": "Enable or disable a forged tool.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "toolId", "in": "path", "required": true, "description": "The forged tool.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "abilitato": { "description": "`true` or `false`." } }, "required": [ "abilitato" ] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/mcp/{serverId}/trust": { "post": { "operationId": "post-sessions-sessionid-mcp-serverid-trust", "tags": [ "Tools and extensions" ], "summary": "Trust an MCP server of the project (its fingerprint is read from disk, as for hooks).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "serverId", "in": "path", "required": true, "description": "The MCP server.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/plugins/{pluginId}/trust": { "post": { "operationId": "post-sessions-sessionid-plugins-pluginid-trust", "tags": [ "Tools and extensions" ], "summary": "Trust a plugin of the project (its fingerprint is read from disk, as for hooks).", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } }, { "name": "pluginId", "in": "path", "required": true, "description": "The plugin.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "NOT_FOUND: Nothing answers at this address, or the resource it names does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/openrouter/inizia": { "post": { "operationId": "post-auth-openrouter-inizia", "tags": [ "Models and providers" ], "summary": "Start signing in to OpenRouter: answers the address to open. The key that comes back is kept by the key store and never returned.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "senzaRitorno": { "description": "`true` for the “code on screen” way (from another machine); otherwise the browser comes back to TALOS by itself, when the window is on this computer." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "OAUTH_CODICE_MANCANTE: The confirmation code is missing: start again.\nQUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "OAUTH_CUSTODIA_FALLITA: The sign-in succeeded, but the key could not be stored safely: open the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "OAUTH_NON_CONFIGURATO: Signing in with an account is not possible on this server: paste a key in Settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/openrouter/codice": { "post": { "operationId": "post-auth-openrouter-codice", "tags": [ "Models and providers" ], "summary": "Finish signing in to OpenRouter with the code shown on screen.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "stato": { "description": "The state of the sign-in started." }, "codice": { "description": "The code OpenRouter showed." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "OAUTH_CODICE_MANCANTE: The confirmation code is missing: start again.\nQUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "OAUTH_CUSTODIA_FALLITA: The sign-in succeeded, but the key could not be stored safely: open the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "OAUTH_NON_CONFIGURATO: Signing in with an account is not possible on this server: paste a key in Settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/openrouter/ritorno": { "get": { "operationId": "get-auth-openrouter-ritorno", "tags": [ "Models and providers" ], "summary": "Where OpenRouter sends the browser back after sign-in (the state in `state` or `stato`). No cookie needed.", "parameters": [ { "name": "code", "in": "query", "required": false, "description": "The code OpenRouter returns.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "The state of the sign-in.", "schema": { "type": "string" } }, { "name": "stato", "in": "query", "required": false, "description": "The same, under its Italian name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "OAUTH_CODICE_MANCANTE: The confirmation code is missing: start again.\nQUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "OAUTH_CUSTODIA_FALLITA: The sign-in succeeded, but the key could not be stored safely: open the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "OAUTH_NON_CONFIGURATO: Signing in with an account is not possible on this server: paste a key in Settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/openrouter/ritorno/{state}": { "get": { "operationId": "get-auth-openrouter-ritorno-state", "tags": [ "Models and providers" ], "summary": "The same return, with the state in the path (the form OpenRouter documents).", "parameters": [ { "name": "state", "in": "path", "required": true, "description": "The state of the sign-in.", "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "description": "The code OpenRouter returns.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "OAUTH_CODICE_MANCANTE: The confirmation code is missing: start again.\nQUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "OAUTH_CUSTODIA_FALLITA: The sign-in succeeded, but the key could not be stored safely: open the Doctor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "OAUTH_NON_CONFIGURATO: Signing in with an account is not possible on this server: paste a key in Settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/sessions/{sessionId}/git/init": { "post": { "operationId": "post-sessions-sessionid-git-init", "tags": [ "Git and GitHub" ], "summary": "Create a Git repository in the session’s folder, on a `main` branch unless Git is configured otherwise.", "description": "Refused when the folder is already inside a repository. When the folder contains your user folder, it is refused until the request carries `conferma: true`.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "The session.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "conferma": { "description": "`true` to confirm a repository in a folder that contains your user folder." } }, "required": [] } } } }, "responses": { "200": { "description": "The JSON envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "QUERY_INVALID: The request is not valid: a query parameter or a body field is missing, unknown or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "GIT_STORE_UNAVAILABLE: Git functions are not available on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "securitySchemes": { "talosToken": { "type": "apiKey", "in": "cookie", "name": "talos_token", "description": "Needed when the server was started with a token; `GET /?token=` sets it." } }, "schemas": { "Envelope": { "type": "object", "required": [ "ok", "data", "meta" ], "properties": { "ok": { "const": true }, "data": {}, "meta": { "type": "object", "properties": { "schema": { "const": "talos.harness-ui.api.v1" }, "generatedAt": { "type": "string", "format": "date-time" } } } } }, "ErrorEnvelope": { "type": "object", "required": [ "ok", "error", "meta" ], "properties": { "ok": { "const": false }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "DOVE_NON_VALIDO", "SCELTA_NON_VALIDA", "BROWSER_VIVO_NON_CONFIGURATO", "BROWSER_VIVO_ASSENTE", "BROWSER_VIVO_SCHEDA_ASSENTE", "BROWSER_VIVO_TROPPE_SCHEDE", "BROWSER_VIVO_GESTO_IGNOTO", "BROWSER_VIVO_SENZA_SESSIONE", "BROWSER_VIVO_CONNESSIONE_FALLITA", "BROWSER_VIVO_SENZA_CONNESSIONE", "CONFIG_INVALID", "QUERY_INVALID", "MODEL_ID_INVALID", "REASONING_INVALID", "PERMISSIONS_INVALID", "REPORT_UNAVAILABLE", "PAYLOAD_LIMIT", "METHOD_NOT_ALLOWED", "NOT_FOUND", "TASK_NOT_ALLOWED", "TASK_CATALOG_UNAVAILABLE", "SESSION_NOT_READY", "SESSION_STORE_WRITE_FAILED", "SESSION_STORE_HEADER_FAILED", "SESSION_STORE_FS_UNSUPPORTED", "SESSION_STORE_DELETE_FAILED", "SESSION_STORE_AMBIGUOUS", "SESSION_STORE_BUSY", "SERVER_SHUTTING_DOWN", "COMPACTION_NOT_FOUND", "AUTOMATION_INVALID", "AUTOMATION_SCHEDULE_INVALID", "AUTOMATION_SCHEDULE_TOO_FREQUENT", "AUTOMATION_SCHEDULE_PAST", "AUTOMATION_CRON_FIELDS", "AUTOMATION_CRON_INVALID", "AUTOMATION_TIMEZONE_INVALID", "AUTOMATION_FOLDER_UNAVAILABLE", "AUTOMATION_LEGACY", "AUTOMATION_PROPOSAL_NOT_FOUND", "AUTOMATION_PROPOSAL_DECIDED", "AUTOMATION_PROPOSAL_STALE", "AUTOMATION_ORIGIN_FORBIDDEN", "AUTOMATION_RUN_IN_PROGRESS", "AUTOMATION_NO_RUN_IN_PROGRESS", "AUTOMATION_RUN_NOT_STARTED", "CATALOG_UNREACHABLE", "CATALOG_UPSTREAM_ERROR", "CATALOG_CONFIGURATION_REQUIRED", "INTERNAL_ERROR", "FILE_NOT_FOUND", "FILE_TOO_LARGE", "FILE_EXISTS", "PLATFORM_UNSUPPORTED", "NOTE_INVALID", "NOTE_NOT_FOUND", "TASK_INVALID", "TASK_NOT_FOUND", "MEMORY_INVALID", "MEMORY_NOT_FOUND", "RESEARCH_INVALID", "RESEARCH_NOT_FOUND", "RESEARCH_CONFLICT", "RESEARCH_RECHECK_UNAVAILABLE", "PROCESS_NOT_RUNNING", "ELICITATION_NOT_PENDING", "ELICITATION_ANSWER_INVALID", "LIBRARY_NOT_FOUND", "LIBRARY_NAME_EMPTY", "LIBRARY_TOO_LARGE", "LIBRARY_MALFORMED", "LIBRARY_READ_FAILED", "LIBRARY_INVALID", "HOOK_INVALID", "MCP_INVALID", "PLUGIN_INVALID", "SESSION_STILL_RUNNING", "WORKFLOW_RUN_NOT_FINISHED", "APPROVAL_NOT_PENDING", "QUESTION_NOT_PENDING", "APPROVAL_ANSWER_FORBIDDEN", "QUESTION_ANSWER_FORBIDDEN", "MODE_WORKFLOW_RETIRED", "QUESTION_ANSWER_NOT_SAVED", "PLAN_NOT_PENDING", "PLAN_STALE", "PLAN_DECISION_NOT_SAVED", "PLAN_APPROVAL_ORIGIN_FORBIDDEN", "WORKFLOW_STORE_UNAVAILABLE", "WORKFLOW_PROPOSAL_NOT_FOUND", "WORKFLOW_DEFINITION_HASH_MISMATCH", "WORKFLOW_COMMAND_CONFLICT", "WORKFLOW_APPROVAL_CONFLICT", "WORKFLOW_STORE_NEEDS_ATTENTION", "WORKFLOW_APPROVAL_ORIGIN_FORBIDDEN", "WORKFLOW_RUNTIME_NOT_READY", "WORKFLOW_RUN_STATE_CONFLICT", "WORKFLOW_DEFINITION_NOT_APPROVED", "WORKFLOW_START_UNSUPPORTED", "WORKFLOW_COMMAND_ORIGIN_FORBIDDEN", "WORKFLOW_REVISION_INVALID", "WORKFLOW_REVISION_EMPTY", "WORKFLOW_VERSION_NOT_LATEST", "WORKFLOW_ALREADY_STARTED", "WORKFLOW_VERSION_SUPERSEDED", "WORKFLOW_DEFINITION_INVALID", "WORKSPACE_LAUNCH_UNAUTHORIZED", "WORKSPACE_LAUNCH_NOT_AVAILABLE", "WORKSPACE_NOT_AVAILABLE", "WORKSPACE_ALREADY_EXISTS", "PROVIDER_INVALID", "PROVIDER_KEY_REQUIRED", "PROVIDER_KEY_INVALID", "PROVIDER_STORE_UNAVAILABLE", "PROVIDER_RUNTIME_INVALID", "PROVIDER_RUNTIME_UNAVAILABLE", "OPENROUTER_PROVIDER_NOT_FOUND", "OPENROUTER_ENDPOINTS_UNAVAILABLE", "PROVIDER_SETTINGS_ORIGIN_FORBIDDEN", "PROVIDER_POOL_FULL", "PROVIDER_KEY_NOT_FOUND", "PROVIDER_FALLBACK_INVALID", "PROVIDER_FALLBACK_TOOLS_UNSUPPORTED", "SEARCH_SOURCE_INVALID", "SEARCH_KEY_REQUIRED", "SEARCH_KEY_INVALID", "SEARCH_ENDPOINT_INVALID", "SEARCH_STORE_UNAVAILABLE", "SEARCH_NOT_READY", "SEARCH_BLOCKED", "SEARCH_UNREACHABLE", "SEARCH_FAILED", "WSL_STORE_UNAVAILABLE", "AUTH_REQUIRED", "CHAT_FILE_ORIGIN_FORBIDDEN", "PAGE_ORIGIN_FORBIDDEN", "HOST_FORBIDDEN", "ORIGIN_FORBIDDEN", "TERMINAL_LIMIT_REACHED", "TERMINAL_STORE_UNAVAILABLE", "BROWSER_PROXY_SOLO_LOCALE", "BROWSER_PROXY_NON_HTML", "BROWSER_PROXY_TROPPO_GRANDE", "BROWSER_PROXY_IRRAGGIUNGIBILE", "GIT_NOT_A_REPOSITORY", "GIT_ALREADY_A_REPOSITORY", "GIT_INIT_NEEDS_CONFIRM", "GIT_PATH_INVALID", "GIT_PATHS_REQUIRED", "GIT_MESSAGE_REQUIRED", "GIT_NOTHING_TO_COMMIT", "GIT_WORKTREE_DIFFERS", "GIT_COMMAND_FAILED", "GIT_STORE_UNAVAILABLE", "GIT_TIMEOUT", "GIT_OUTPUT_TOO_LARGE", "GIT_DIFF_AREA_INVALID", "GIT_PATH_UNCHANGED", "GIT_NOTHING_TO_DISCARD", "GIT_CONFLICTS", "GIT_NESTED_REPO", "GIT_STAGED_CHANGED", "GIT_NOTHING_STAGED", "GIT_STAGED_OUTSIDE", "GIT_HEAD_CHANGED", "GIT_COMMIT_PUSHED", "GIT_MERGE_COMMIT", "GIT_COMMIT_OUTSIDE", "GIT_BRANCH_INVALID", "GIT_BRANCH_EXISTS", "GIT_BRANCH_NOT_FOUND", "GIT_BRANCH_CURRENT", "GIT_BRANCH_NOT_MERGED", "GIT_SWITCH_BLOCKED", "GIT_NOTHING_TO_STASH", "GIT_STASH_CHANGED", "GIT_STASH_OUTSIDE", "GIT_STASH_CONFLICT", "GIT_NO_REMOTE", "GIT_REMOTE_UNKNOWN", "GIT_REMOTE_REQUIRED", "GIT_REMOTE_MISMATCH", "GIT_NO_UPSTREAM", "GIT_UPSTREAM_GONE", "GIT_DETACHED", "GIT_BEHIND", "GIT_WORKTREE_DIRTY", "GIT_PULL_FAILED", "GIT_PUSH_REJECTED", "GIT_FETCH_RUNNING", "GIT_ABORTED", "GIT_COMMIT_INVALID", "GIT_COMMIT_UNKNOWN", "GH_STORE_UNAVAILABLE", "GH_NOT_INSTALLED", "GH_NOT_LOGGED_IN", "GH_UNSUPPORTED_PLATFORM", "GH_DOWNLOAD_FAILED", "GH_CHECKSUM_MISMATCH", "GH_EXTRACT_FAILED", "GH_TIMEOUT", "GH_COMMAND_FAILED", "GH_OUTPUT_INVALID", "GH_OUTPUT_TOO_LARGE", "GH_NOT_GITHUB", "GH_BRANCH_NOT_PUSHED", "GH_BASE_UNKNOWN", "GH_INPUT_INVALID", "GH_LOGIN_FAILED", "GH_GIT_FAILED", "GIT_HUNK_INVALID", "GIT_DIFF_CHANGED", "GIT_HUNK_UNSUPPORTED", "GIT_HUNK_FAILED", "SESSION_MODEL_UNKNOWN", "MODEL_CALL_FAILED", "RUNTIME_NOT_AVAILABLE", "RUNTIME_UNREACHABLE", "RUNTIME_OPERATION_UNSUPPORTED", "MODEL_NOT_FOUND", "MODEL_LOAD_UNCONFIRMED", "MODEL_UNLOAD_UNCONFIRMED", "LOCAL_RUNTIME_FAILED", "HF_HUB_INVALID", "HF_HUB_UPSTREAM", "HF_HUB_RESPONSE_INVALID", "HF_REPOSITORY_GATED", "HF_RATE_LIMITED", "HF_REDIRECT_INVALID", "HF_REDIRECT_HOST_REJECTED", "HF_RESOLVE_INVALID", "HF_TRANSFER_INVALID", "HF_TRANSFER_COLLISION", "RUNTIME_ALREADY_RUNNING", "HF_DOWNLOAD_FAILED", "HF_PATH_REJECTED", "CHECKSUM_MISMATCH", "MODEL_FILE_UNREADABLE", "CANCELLED_BY_OWNER", "PAUSED_BY_OWNER", "HF_IMAGE_URL_INVALID", "HF_IMAGE_HOST_REJECTED", "HF_IMAGE_REDIRECT_REJECTED", "HF_IMAGE_PRIVATE_ADDRESS", "HF_IMAGE_DNS_FAILED", "HF_IMAGE_ABORTED", "HF_IMAGE_UPSTREAM", "HF_IMAGE_MIME_REJECTED", "HF_IMAGE_TOO_LARGE", "HF_IMAGE_CONFIG_INVALID", "LOCAL_IMPORT_INVALID", "LOCAL_IMPORT_TOO_LARGE", "LOCAL_IMPORT_SIZE_MISMATCH", "LOCAL_IMPORT_EMPTY", "LOCAL_IMPORT_NOT_GGUF", "MODEL_NOT_READY", "MODEL_HEADER_INVALID", "MODEL_HEADER_UNREADABLE", "RUNTIME_PROBE_FAILED", "FIT_INVALID", "LOCAL_RUNTIME_PROBE_MISCONFIGURED", "PROBE_CONSENT_REQUIRED", "PROBE_GENERATION_FAILED", "PROBE_GENERATION_INCOMPLETE", "MODEL_NOT_COMPATIBLE", "OAUTH_NON_CONFIGURATO", "OAUTH_ATTESA_IGNOTA", "OAUTH_CODICE_MANCANTE", "OAUTH_SCAMBIO_RIFIUTATO", "OAUTH_RETE", "OAUTH_RISPOSTA_INATTESA", "OAUTH_CUSTODIA_FALLITA" ] }, "message": { "type": "string" }, "title": { "type": "string" }, "explanation": { "type": "string" }, "action": { "type": "string" }, "doctorReference": { "type": "string" } } }, "meta": { "type": "object" } } } } } }