Skip to navigation

Execute a flow or agent

Main dispatch endpoint for flow and agent execution with record resolution. Supports streaming via SSE or synchronous JSON responses. Send the RFC 7240 Prefer: respond-async header to receive a durable execution handle immediately, then poll its status URL for completion. A saved agent may run on the durable session lane; the admission headers x-runtype-concurrency (reject, supersede, queue, steer), x-runtype-coalesce (true) and idempotency-key then apply exactly as on POST /v1/agents/{id}/execute, and are ignored for in-process execution except steer, which fails explicitly on unsupported lanes. x-runtype-concurrency: auto sends the same user-message deltas as steer and lets a classifier choose: while a turn runs, a message that belongs to it steers and an independent one queues as the next turn; with nothing running it is an ordinary turn with no route report. A routed or downgraded answer carries X-Runtype-Busy-Message-Route (steer or queue) and X-Runtype-Busy-Message-Source (classifier, shadow, abstained, timeout, error, unanswered, circuit_open, or disabled), plus X-Runtype-Busy-Message-Probability and X-Runtype-Busy-Message-Model when the classifier answered; JSON bodies repeat them as busyMessageRoute. Where auto cannot route (in-process execution, stored history, a flow, no conversationId, coalesce, Prefer: respond-async) it keeps the default admission and reports source disabled. Any other x-runtype-concurrency value is refused with 400 INVALID_CONCURRENCY_MODE. Steer accepts only new user-message deltas, preserves the active execution configuration and authority, and returns a deliveryId with a deliveryStatusUrl. Prefer: respond-async with steer returns a native delivery receipt without queuing an HTTP replay.

Authentication

AuthorizationBearer
API key or Clerk session token

Request

This endpoint expects an object.
objectRequired
OR
objectRequired

Response

Execution result (SSE stream or JSON)

object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error