Workflows

Review, approve and start workflow proposals; follow and control their runs. Paths are relative to /api/v1.

GET /workflows/{workflowId}/versions/{version}

Read one version of a workflow proposal: its plan, budgets and approval state.

Path

workflowId

The workflow proposal.

version

The version of the proposal (a positive integer).

Answers The JSON envelope.

Errors3

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

Any operation can also answer the common errors.

POST /workflows/{workflowId}/versions/{version}/approve

Approve a version of a workflow proposal, so it can be started.

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.

Path

workflowId

The workflow proposal.

version

The version of the proposal (a positive integer).

Body

commandIdrequired

An id you choose for this command; sending it again repeats nothing.

definitionHashrequired

The SHA-256 of the definition you reviewed; a different one is refused.

Answers The JSON envelope.

Errors4

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

Any operation can also answer the common errors.

POST /workflows/{workflowId}/versions/{version}/revise

Change the budgets of a workflow proposal: creates the next version, to approve again.

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.

Path

workflowId

The workflow proposal.

version

The version of the proposal (a positive integer).

Body

definitionHashrequired

The SHA-256 of the version you are revising.

budgetsrequired

The limits to change, any of promptTokens, completionTokens, wallMs, modelRequests, toolCalls and knownCostUsd.

Answers The JSON envelope.

Errors4

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

Any operation can also answer the common errors.

POST /workflows/{workflowId}/versions/{version}/start

Start a run of an approved workflow version.

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.

Path

workflowId

The workflow proposal.

version

The version of the proposal (a positive integer).

Body

commandIdrequired

An id you choose for this command.

definitionHashrequired

The SHA-256 of the approved definition.

Answers The JSON envelope.

Errors5

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

Any operation can also answer the common errors.

POST /sessions/{sessionId}/workflows/{runId}/pause

Pause a running workflow run of this session: steps in flight finish first.

Same defenses as approval. Answers 202; a repeated command answers the same receipt with Idempotency-Replayed: true.

Path

sessionId

The session.

runId

The workflow run.

Body

commandIdrequired

An id you choose for this command.

Answers The JSON envelope.

Errors5

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

Any operation can also answer the common errors.

POST /sessions/{sessionId}/workflows/{runId}/resume

Resume a paused workflow run of this session.

Same defenses and answer as pause.

Path

sessionId

The session.

runId

The workflow run.

Body

commandIdrequired

An id you choose for this command.

Answers The JSON envelope.

Errors5

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

Any operation can also answer the common errors.

POST /sessions/{sessionId}/workflows/{runId}/cancel

Cancel a workflow run of this session.

Same defenses and answer as pause.

Path

sessionId

The session.

runId

The workflow run.

Body

commandIdrequired

An id you choose for this command.

Answers The JSON envelope.

Errors5

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

Any operation can also answer the common errors.

POST /sessions/{sessionId}/workflows/{runId}/retry

Retry the failed steps of a finished workflow run.

Same defenses and answer as pause. See what would run again with retry-preview first.

Path

sessionId

The session.

runId

The workflow run.

Body

commandIdrequired

An id you choose for this command.

Answers The JSON envelope.

Errors5

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

Any operation can also answer the common errors.

GET /sessions/{sessionId}/workflows/{runId}/retry-preview

Preview what a retry would run again: the failed steps and what depends on them.

Path

sessionId

The session.

runId

The workflow run.

Answers The JSON envelope.

Errors4

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.
WORKFLOW_RUNTIME_NOT_READY	503	The workflow runtime is not ready.
WORKFLOW_STORE_UNAVAILABLE	503	Workflows are not available on this server.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/workflows/{runId}/events

The live stream of a workflow run (server-sent events).

Opens at ?after=<sequence> the first time; on reconnection the browser sends Last-Event-ID and the stream resumes after it. No other query parameter is accepted.

Path

sessionId

The session.

runId

The workflow run.

Query

after

The last sequence number already seen (from the run graph), to start after it.

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

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
WORKFLOW_STORE_UNAVAILABLE	503	Workflows are not available on this server.

Any operation can also answer the common errors.

GET /workflows/{workflowId}/versions/{version}/graph

The planned graph of a workflow proposal, as an overview (read only).

Path

workflowId

The workflow proposal.

version

The version of the proposal (a positive integer).

Answers The JSON envelope.

Errors3

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

Any operation can also answer the common errors.

GET /workflows/{workflowId}/versions/{version}/edges

The edges of the planned graph of a proposal, a page at a time.

Path

workflowId

The workflow proposal.

version

The version of the proposal (a positive integer).

Query

offset

Where the page starts (default 0).

limit

Edges per page, 1 to 100 (default 50).

phaseId

Only the edges of these groups: repeat it once per open group (up to 64).

Answers The JSON envelope.

Errors3

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

Any operation can also answer the common errors.

GET /workflows/{workflowId}/versions/{version}/groups/{groupId}

One group (phase) of the planned graph of a proposal, a page at a time.

Path

workflowId

The workflow proposal.

version

The version of the proposal (a positive integer).

groupId

The group (phase) of the graph.

Query

offset

Where the page starts (default 0).

limit

Steps per page, 1 to 50 (default 50).

sort

stato to order the steps by state.

Answers The JSON envelope.

Errors3

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

Any operation can also answer the common errors.

GET /workflows/{workflowId}/versions/{version}/nodes/{nodeId}

One step of the planned graph of a proposal.

Path

workflowId

The workflow proposal.

version

The version of the proposal (a positive integer).

nodeId

The step.

Answers The JSON envelope.

Errors3

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

Any operation can also answer the common errors.

GET /sessions/{sessionId}/workflow-proposals

List the workflow proposals of a session, a page at a time.

Path

sessionId

The session.

Query

offset

Where the page starts.

limit

How many proposals per page (at most 50).

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
WORKFLOW_STORE_UNAVAILABLE	503	Workflows are not available on this server.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/workflows

List the workflow runs of a session, a page at a time.

Path

sessionId

The session.

Query

offset

Where the page starts (default 0).

limit

Runs per page, 1 to 50 (default 50).

stato

Only runs in this state: created, running, paused, needs_attention, succeeded, failed or cancelled.

q

Only runs whose title or id contains this text (case-insensitive, up to 256 characters).

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

Errors3

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

Any operation can also answer the common errors.

GET /sessions/{sessionId}/workflows/{runId}/graph

The graph of a workflow run as it stands: steps, groups and their states.

Path

sessionId

The session.

runId

The workflow run.

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

Errors3

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

Any operation can also answer the common errors.

GET /sessions/{sessionId}/workflows/{runId}/edges

The edges of the graph of a workflow run, a page at a time.

Path

sessionId

The session.

runId

The workflow run.

Query

offset

Where the page starts (default 0).

limit

Edges per page, 1 to 100 (default 50).

phaseId

Only the edges of these groups: repeat it once per open group (up to 64).

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

Errors3

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

Any operation can also answer the common errors.

GET /sessions/{sessionId}/workflows/{runId}/history

The public history of the states of a workflow run, to replay it faithfully.

Path

sessionId

The session.

runId

The workflow run.

Query

offset

Where the page starts (default 0).

limit

Entries per page, 1 to 1000 (default 50).

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

Errors3

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

Any operation can also answer the common errors.

GET /sessions/{sessionId}/workflows/{runId}/groups/{groupId}

One group (phase) of a workflow run, with its steps, a page at a time.

Path

sessionId

The session.

runId

The workflow run.

groupId

The group (phase) of the graph.

Query

offset

Where the page of steps starts (default 0).

limit

Steps per page, 1 to 50 (default 50).

sort

stato to order the steps by state.

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

Errors3

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

Any operation can also answer the common errors.

GET /sessions/{sessionId}/workflows/{runId}/nodes/{nodeId}

One step of a workflow run: its state, its attempts and a preview of its output.

Path

sessionId

The session.

runId

The workflow run.

nodeId

The step.

Query

outputOffset

Where the output preview starts, in bytes (default 0).

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

Errors3

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

Any operation can also answer the common errors.

GET /sessions/{sessionId}/workflows/{runId}/nodes/{nodeId}/output

The full output of a finished step, its bytes verified against the content store.

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.

Path

sessionId

The session.

runId

The workflow run.

nodeId

The step.

Query

resultId

Which result of the step (a step retried has several).

format

json (default) or raw for the bytes themselves.

offset

Where to start, in bytes (default 0).

limit

How many bytes (default: all).

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

Errors3

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

Any operation can also answer the common errors.

GET /sessions/{sessionId}/workflows/{runId}/nodes/{nodeId}/lineage

The lineage of a step of a run: the steps upstream or downstream of it, a page at a time.

Path

sessionId

The session.

runId

The workflow run.

nodeId

The step.

Query

directionrequired

upstream or downstream.

offset

Where the page starts (default 0).

limit

Steps per page, 1 to 1000 (default 50).

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

Errors3

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

Any operation can also answer the common errors.

GET /workflows/{workflowId}/versions/{version}/nodes/{nodeId}/lineage

The lineage of a planned step: the steps upstream or downstream of it, a page at a time.

Path

workflowId

The workflow proposal.

version

The version of the proposal (a positive integer).

nodeId

The step.

Query

directionrequired

upstream or downstream.

offset

Where the page starts (default 0).

limit

Steps per page, 1 to 1000 (default 50).

Answers The JSON envelope.

Errors3

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

Any operation can also answer the common errors.