Skip to main content
POST
/
agent
/
workflow-actions
Execute a workflow action and stream events via SSE
curl --request POST \
  --url https://agent.staging.getmodus.com/agent/workflow-actions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "organizationId": "<string>",
  "sessionId": "<string>",
  "workflowAction": {},
  "fileThreadId": "<string>",
  "previousOutputs": [
    {}
  ],
  "userTimezone": "<string>",
  "runId": "<string>"
}
'
"id: 1717000000000-0\ndata: {\"type\":\"token\",\"content\":\"Result: 42\"}\n\nid: 1717000000001-0\ndata: {\"type\":\"done\",\"runId\":\"xyz-456\"}\n\n"

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Idempotency-Key
string

Client-generated idempotency key (UUID recommended). Retry with same key + same body resumes the existing SSE stream. Same key + different body returns a 409 error event.

Body

application/json
​
organizationId
string
required

Organization ID the run belongs to. Must match the authenticated principal's org.

​
sessionId
string
required

Client-generated session identifier.

​
workflowAction
object
required

Workflow action descriptor: toolId, toolName, aiDescription, runtimeScope, and any action-specific parameters.

​
fileThreadId
string

File thread ID for document-scoped execution.

​
previousOutputs
object[]

Outputs from earlier steps in a multi-step workflow, forwarded to the action runtime.

​
userTimezone
string

IANA time zone name for the executing user (e.g. "America/New_York").

​
runId
string

Optional client-supplied run ID. Idempotency-Key header takes precedence.

​
source
enum<string>

UI surface that triggered this action.

Available options:
automation,
api,
other

Response

200 - text/event-stream

SSE stream of workflow action run events. Same frame format as POST /agent/runs. Ends with a terminal RunEvent (done/error/cancelled).

W3C Server-Sent Events stream. Each frame: id: \n data: \n\n

RunEvent shapes are identical to POST /agent/runs.