Start an agent turn
Starts a new agent turn in a session and returns 202 with the durable handle {runId, sessionId, jobId}. The turn runs detached; stream its events over the session WebSocket or poll the session. agentMode is required. The SDK's sessions.dispatch.
POST
/api/agent/runsBody
sessionIdstringrequiredpromptstringclientTurnIdstringresumebooleanmodelIdstringworkflowIdstringworkflowRunIdobjectworkflowNamestringversionIdstringcheckpointVersionIdstringvaultIdstringspaceIdstringworkflowDataobjectworkflowDataHashstringlastRunIdstringisScheduledbooleanlastRunStatusobjectrunIdstringrequiredstatusstringrequiredcompletedAtstringeditorModeenumOne of: workflow, app, agent, database
moduleContextobjectisModuleWorkflowbooleanrequiredmoduleWorkflowIdstringparentWorkflowIdstringparentWorkflowNamestringreturnToNodestringagentModeenumrequiredOne of: agent, plan
focusedNodestringfocusedNodeContextobjectmentionedNodesstring[]timezonestringappContextstringsandboxSessionIdstringsandboxPreviewUrlstringsandboxDatasetsobject[]tableIdstringrequiredtableNamestringrequiredcolumnsobject[]requirednamestringrequiredtypestringrequiredimageAttachmentsobject[]typeenumrequiredOne of: image
datastringrequiredmimeTypestringrequirednamestringrequiredsizenumberrequiredfileAttachmentsobject[]typeenumrequiredOne of: file
idstringrequirednamestringrequiredsizenumberrequiredRequest
curl
curl -X POST https://trickest.io/api/agent/runs \
-H "Authorization: Token $TRICKEST_TOKEN" \
-H "Content-Type: application/json" \
-d '{ }'Responses
202Turn accepted
runIdstringrequiredsessionIdstringrequiredjobIdstringrequired400Bad Request – validation error or malformed input
codestringrequiredmessagestringrequireddetailsobjectField-level detail when the error is a validation failure.
401Unauthorized – missing or expired token
codestringrequiredmessagestringrequireddetailsobjectField-level detail when the error is a validation failure.
403Forbidden – insufficient permissions
codestringrequiredmessagestringrequireddetailsobjectField-level detail when the error is a validation failure.
429Too Many Requests – rate limited
codestringrequiredmessagestringrequireddetailsobjectField-level detail when the error is a validation failure.
500Internal Server Error
codestringrequiredmessagestringrequireddetailsobjectField-level detail when the error is a validation failure.