Skip to main content
POST
Execute a workflow action

Authorizations

Authorization
string
header
required

A Modus personal access token (modus_<orgUuid>_<prefix>_<secret>) or an OAuth 2.1 access token, sent as Authorization: Bearer <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
sessionId
string
required

Client-generated session identifier.

workflowAction
object
required

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

organizationId
string

Organization the run belongs to. Omit for PAT/SDK callers — falls back to the authenticated principal's org.

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

Workflow 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.