Skip to main content

Execute a published agent asynchronously

POST 
https://platform.docana.com/api/v1/agents/:agentId/execute/

Validates the request, schedules a background run of the published agent version and returns immediately with both the executionId and assistantMessageId handles the run will use. Output content is populated asynchronously. Body: { prompt: string, threadId?: string, context?: object, waitSeconds?: number, deliverToChannel?: boolean }. With deliverToChannel: true and a threadId, the run's output (and any follow-up it schedules) is also sent through the channel the thread came in on, to the sender of its latest inbound message; without it the reply is only stored. Poll getAgentExecution with the returned id for status, node outputs and the threadId. An agent whose published spec has workflow.dispatch: "queued", or any run above the application's concurrency limit, is handed to the workers instead: the acknowledgement carries executionStatus: "QUEUED" and the execution row exists right away, waiting for a worker. For an in-process run the row appears once the background run starts, so a brief 404 right after scheduling means "not started yet" while a persistent one means the run failed to start. Optional bounded wait: waitSeconds (1-120) holds the response until the run settles or the window elapses; the response then carries waitOutcome (completed, failed or timeout) and, when the run settled, executionStatus. A timeout never cancels the run — keep polling getAgentExecution with the same executionId. Supports the Idempotency-Key header: a retry with the same key and body replays the stored ack (same executionId) instead of running the agent a second time. waitSeconds is a delivery preference, not part of the request identity: it is excluded from the idempotency payload hash, and replays return the stored asynchronous ack immediately without waiting.

Request​

Responses​

The run was scheduled