Orchestration

Manage conversations and runs.

List agents across the projects you can access, or edit definitions within a project. To start an agent run, use POST /runs with project_id and target: { type: "agent", id }.

Find every run operation under Runs: lifecycle, events, input requests, children, the runs that triggers start, and the runtime callbacks workers use. Configure schedules and webhooks to trigger runs automatically.

Conversations · Triggers · Runs · Executors

Conversations

Create, read, update, and delete conversations. Find a conversation’s runs and the input requests that need a response under Runs.

List, create, read, update, or delete messages, branch from a message, and select the current branch.

List, add, or remove participants.

Read or update conversation read state.

EndpointMethodsDescription
/conversationsGET, POSTList conversations; Create conversation
/conversations/{conversation_id}GET, PATCH, DELETEGet conversation; Update conversation; Delete conversation
/conversations/{conversation_id}/messagesGET, POSTList conversation messages; Create conversation message
/conversations/{conversation_id}/messages/{message_id}GET, PATCH, DELETEGet conversation message; Update conversation message; Delete conversation message
/conversations/{conversation_id}/messages/{message_id}/branchesGET, POSTList conversation message branches; Create conversation message branch
/conversations/{conversation_id}/branch-selectionPUTUpdate conversation branch selection
/conversations/{conversation_id}/participantsGET, POSTList conversation participants; Create conversation participant
/conversations/{conversation_id}/participants/{user_id}DELETEDelete conversation participant
/participantsGETList participants
/conversations/{conversation_id}/read-stateGET, PUTGet conversation read state; Update conversation read state

Triggers

Configure schedules. To start a run from an existing schedule, use POST /runs with project_id and source: { type: "schedule", id }.

Create and configure webhooks, and list the webhooks declared in source files. A webhook is a project URL that external services post to. Start a webhook run and list the runs a webhook started under Runs.

List the events a webhook received and replay a stored event. Each delivery is stored as a webhook event that may start a run.

EndpointMethodsDescription
/projects/{project_reference}/schedulesGET, POSTList schedules; Create schedule
/projects/{project_reference}/source-schedulesGETList source schedules
/projects/{project_reference}/schedules/{schedule_id}GET, PATCH, DELETEGet schedule; Update schedule; Delete schedule
/projects/{project_reference}/webhooksGET, POSTList webhooks; Create webhook
/projects/{project_reference}/source-webhooksGETList source webhooks
/projects/{project_reference}/webhooks/{webhook_id}GET, PATCH, DELETEGet webhook; Update webhook; Delete webhook
/projects/{project_reference}/webhooks/{webhook_id}/eventsGETList webhook events
/projects/{project_reference}/webhooks/{webhook_id}/events/{webhook_event_id}/replayPOSTReplay webhook event

Runs

Start, list, inspect, cancel, and resume agent, task, and workflow runs, follow their events, answer their input requests, and find the runs that schedules, webhooks, and evaluations start.

EndpointMethodsDescription
/runs/{run_id}/input-requestsGET, POSTList run input requests; Create input request
/input-requests/{input_request_id}/responsesPOSTRespond to input request
/conversations/{conversation_id}/input-requestsGETList conversation input requests
/input-requests/{input_request_id}GETGet input request
/input-requests/{input_request_id}/cancelPOSTCancel input request
/runsGET, POSTList runs; Create run
/runs/{run_id}GET, PATCH, DELETEGet run; Update run; Delete run
/runs/{run_id}/event-tokensPOSTCreate run event token
/runs/{run_id}/heartbeatsPOSTSend run heartbeat
/runs/{run_id}/runtime/ownershipGETRead live runtime ownership
/runs/{run_id}/runtime/recovery-ownershipGETRead managed recovery ownership
/runs/{run_id}/runtime/recovery-eventsGETRead authenticated recovery events
/runs/{run_id}/pause-checkpointGETGet dispatch continuation
/runs/{run_id}/cancellation-ackPOSTAcknowledge run cancellation
/runs/{run_id}/pause-ackPOSTAcknowledge run pause
/runs/{run_id}/child-runsGETList child runs
/conversations/{conversation_id}/child-runsGETList conversation child runs
/conversations/{conversation_id}/runsGETList conversation runs
/projects/{project_reference}/runsGETList project runs
/projects/{project_reference}/public-inference-runs/{run_id}GETGet project public inference run status
/projects/{project_reference}/webhooks/{webhook_definition_id}/runsGETList project webhook runs
/runs/event-typesGETList run event types
/runs/{run_id}/eventsGET, POSTList run events; Append run events
/runs/{run_id}/model-call-inputsGETList model-call input references
/runs/{run_id}/model-call-usageGETList model-call usage references
/events/{event_id}GETGet canonical event
/runs/{run_id}/events/{event_id}GETGet run event
/schemas/run-events/{schema_file}GETGet run event data schema
/runs/{run_id}/events/summaryGETGet run event summary
/runs/{run_id}/snapshotGETGet run snapshot
/conversations/{conversation_id}/runs/{run_id}/streamGETStream conversation run events (compatibility)
/runs/{run_id}/streamGETStream run events
/runs/{run_id}/cancelPOSTCancel run
/runs/{run_id}/failPOSTFail run
/runs/{run_id}/finalizePOSTFinalize run
/runs/{run_id}/pausePOSTPause run
/runs/{run_id}/resumePOSTResume run
/runs/{run_id}/succeedPOSTSucceed run
/runs/{run_id}/artifacts/{artifact_id}GETDownload run artifact

Executors

List the push runtime services and pull workers connected to a project. Requires project.runtime.manage.

Register workers, claim runs, renew leases, and report session state. Project administrators manage workers; worker operations accept credentials scoped to the worker.

EndpointMethodsDescription
/projects/{project_reference}/connected-agentsGETList connected agents
/agent-workers/workers/{worker_id}/claimPOSTClaim run
/agent-workers/workers/{worker_id}DELETEDelete worker
/agent-workers/workers/{worker_id}/heartbeatPOSTHeartbeat worker
/agent-workers/workers/{worker_id}/runs/{run_id}/sessionPUTUpdate worker run session
/agent-workers/projects/{project_reference}/workersPOSTRegister worker
/agent-workers/workers/{worker_id}/runs/{run_id}/leasePOSTRenew run lease

Back to REST API reference