Skip to main content
POST
/
agent
/
runs
Create a run and stream events via SSE
curl --request POST \
  --url https://agent.staging.getmodus.com/agent/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "sessionId": "<string>",
  "organizationId": "<string>",
  "fileThreadId": "<string>",
  "runId": "<string>"
}
'
"id: 1717000000000-0\ndata: {\"type\":\"token\",\"content\":\"Hello\"}\n\nid: 1717000000001-0\ndata: {\"type\":\"done\",\"runId\":\"abc-123\"}\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). A retry with the same key + same body resumes the existing SSE stream. Same key + different body returns a 409 error event.

Body

application/json
​
message
string
required

The user message to send to the agent.

​
sessionId
string
required

Client-generated session identifier for conversation continuity.

​
organizationId
string
required

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

​
fileThreadId
string

File thread ID for document-scoped conversations.

​
action
enum<string>

Action type. Only "chat" is accepted on this endpoint.

Available options:
chat
​
runId
string

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

Response

200 - text/event-stream

SSE stream of run events. Each event line is a JSON-encoded RunEvent. The stream ends with a done, error, or cancelled control event.

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

RunEvent discriminated union: {type:"token", content:string} — LLM text chunk {type:"done", runId:string, threadId?:string} — terminal success {type:"error", error:string} — terminal failure {type:"cancelled", runIds:string[], timestamp:number} — terminal cancel {type:"notice", message:string, severity:"info"|"warning"} — non-terminal warning {type:"heartbeat", timestamp?:number} — keepalive {type:"tool_start"|"tool_end"|string, ...} — runtime streaming frames