Execute a workflow action and stream events via SSE

curl --request POST \ --url https://agent.getmodus.com/agent/v1/workflow-actions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "organizationId": "<string>", "sessionId": "<string>", "workflowAction": {}, "fileThreadId": "<string>", "previousOutputs": [ {} ], "userTimezone": "<string>", "runId": "<string>", "automationId": "<string>" } '

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.

automationId

string

Agent (automation) id for usage attribution.

source

enum<string>

UI surface that triggered this action.

Available options:

agent,

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.