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 }. Poll getAgentExecution with the returned id for status, node outputs and the threadId; the execution 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