> ## Documentation Index
> Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Orchestration

> Manage conversations and runs.

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`](/docs/cloud/rest/api-reference/execution-runs-runs/create-run) 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](/docs/cloud/rest/apis/orchestration#triggers) and [webhooks](/docs/cloud/rest/apis/orchestration#triggers) to trigger runs automatically.

[Conversations](#conversations) · [Triggers](#triggers) · [Runs](#runs) · [Executors](#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.

| Endpoint | Methods | Description |
| - | - | - |
| `/conversations` | [GET](/docs/cloud/rest/api-reference/execution-conversations-conversations/list-conversations), [POST](/docs/cloud/rest/api-reference/execution-conversations-conversations/create-conversation) | List conversations; Create conversation |
| `/conversations/{conversation_id}` | [GET](/docs/cloud/rest/api-reference/execution-conversations-conversations/get-conversation), [PATCH](/docs/cloud/rest/api-reference/execution-conversations-conversations/update-conversation), [DELETE](/docs/cloud/rest/api-reference/execution-conversations-conversations/delete-conversation) | Get conversation; Update conversation; Delete conversation |
| `/conversations/{conversation_id}/branch-selection` | [GET](/docs/cloud/rest/api-reference/execution-conversations-conversations/get-branch-selection) (deprecated), [PUT](/docs/cloud/rest/api-reference/execution-conversations-conversation-messages/update-conversation-branch-selection) | Get branch selection; Update conversation branch selection |
| `/conversations/{conversation_id}/messages` | [GET](/docs/cloud/rest/api-reference/execution-conversations-conversation-messages/list-conversation-messages), [POST](/docs/cloud/rest/api-reference/execution-conversations-conversation-messages/create-conversation-message) | List conversation messages; Create conversation message |
| `/conversations/{conversation_id}/messages/{message_id}` | [GET](/docs/cloud/rest/api-reference/execution-conversations-conversation-messages/get-conversation-message), [PATCH](/docs/cloud/rest/api-reference/execution-conversations-conversation-messages/update-conversation-message), [DELETE](/docs/cloud/rest/api-reference/execution-conversations-conversation-messages/delete-conversation-message) | Get conversation message; Update conversation message; Delete conversation message |
| `/conversations/{conversation_id}/messages/{message_id}/branches` | [GET](/docs/cloud/rest/api-reference/execution-conversations-conversation-messages/list-conversation-message-branches), [POST](/docs/cloud/rest/api-reference/execution-conversations-conversation-messages/create-conversation-message-branch) | List conversation message branches; Create conversation message branch |
| `/conversations/{conversation_id}/tree` | [GET](/docs/cloud/rest/api-reference/execution-conversations-conversation-messages/get-conversation-tree) (deprecated) | Get conversation tree |
| `/conversations/{conversation_id}/branches/{message_id}` | [GET](/docs/cloud/rest/api-reference/execution-conversations-conversation-messages/list-message-branches) (deprecated) | List message branches |
| `/conversations/{conversation_id}/branches` | [POST](/docs/cloud/rest/api-reference/execution-conversations-conversation-messages/fork-message) (deprecated) | Fork message |
| `/conversations/{conversation_id}/participants` | [GET](/docs/cloud/rest/api-reference/execution-conversations-conversation-participants/list-conversation-participants), [POST](/docs/cloud/rest/api-reference/execution-conversations-conversation-participants/create-conversation-participant) | List conversation participants; Create conversation participant |
| `/conversations/{conversation_id}/participants/{user_id}` | [DELETE](/docs/cloud/rest/api-reference/execution-conversations-conversation-participants/delete-conversation-participant) | Delete conversation participant |
| `/conversations/{conversation_id}/read-state` | [GET](/docs/cloud/rest/api-reference/execution-conversations-conversation-read-state/get-conversation-read-state), [PUT](/docs/cloud/rest/api-reference/execution-conversations-conversation-read-state/update-conversation-read-state) | Get conversation read state; Update conversation read state |

## Triggers

Configure schedules. To start a run from an existing schedule, use [`POST /runs`](/docs/cloud/rest/api-reference/execution-runs-runs/create-run) 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.

| Endpoint | Methods | Description |
| - | - | - |
| `/projects/{project_reference}/schedules` | [GET](/docs/cloud/rest/api-reference/execution-triggers-project-schedules/list-schedules), [POST](/docs/cloud/rest/api-reference/execution-triggers-project-schedules/create-schedule) | List schedules; Create schedule |
| `/projects/{project_reference}/source-schedules` | [GET](/docs/cloud/rest/api-reference/execution-triggers-project-schedules/list-source-schedules) | List source schedules |
| `/projects/{project_reference}/schedules/{schedule_id}` | [GET](/docs/cloud/rest/api-reference/execution-triggers-project-schedules/get-schedule), [PATCH](/docs/cloud/rest/api-reference/execution-triggers-project-schedules/update-schedule), [DELETE](/docs/cloud/rest/api-reference/execution-triggers-project-schedules/delete-schedule) | Get schedule; Update schedule; Delete schedule |
| `/projects/{project_reference}/webhooks` | [GET](/docs/cloud/rest/api-reference/execution-triggers-webhooks/list-webhooks), [POST](/docs/cloud/rest/api-reference/execution-triggers-webhooks/create-webhook) | List webhooks; Create webhook |
| `/projects/{project_reference}/source-webhooks` | [GET](/docs/cloud/rest/api-reference/execution-triggers-webhooks/list-source-webhooks) | List source webhooks |
| `/projects/{project_reference}/webhooks/{webhook_id}` | [GET](/docs/cloud/rest/api-reference/execution-triggers-webhooks/get-webhook), [PATCH](/docs/cloud/rest/api-reference/execution-triggers-webhooks/update-webhook), [DELETE](/docs/cloud/rest/api-reference/execution-triggers-webhooks/delete-webhook) | Get webhook; Update webhook; Delete webhook |
| `/projects/{project_reference}/webhooks/{webhook_id}/events` | [GET](/docs/cloud/rest/api-reference/execution-triggers-webhook-events/list-webhook-events) | List webhook events |
| `/projects/{project_reference}/webhooks/{webhook_id}/events/{webhook_event_id}/replay` | [POST](/docs/cloud/rest/api-reference/execution-triggers-webhook-events/replay-webhook-event) | Replay 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.

| Endpoint | Methods | Description |
| - | - | - |
| `/runs/{run_id}/input-requests` | [GET](/docs/cloud/rest/api-reference/execution-runs-run-input-requests/list-run-input-requests), [POST](/docs/cloud/rest/api-reference/execution-runs-run-input-requests/create-input-request) | List run input requests; Create input request |
| `/input-requests/{input_request_id}/responses` | [POST](/docs/cloud/rest/api-reference/execution-runs-run-input-requests/respond-to-input-request) | Respond to input request |
| `/conversations/{conversation_id}/input-requests` | [GET](/docs/cloud/rest/api-reference/execution-runs-run-input-requests/list-conversation-input-requests) | List conversation input requests |
| `/input-requests/{input_request_id}` | [GET](/docs/cloud/rest/api-reference/execution-runs-run-input-requests/get-input-request) | Get input request |
| `/input-requests/{input_request_id}/cancel` | [POST](/docs/cloud/rest/api-reference/execution-runs-run-input-requests/cancel-input-request) | Cancel input request |
| `/runs` | [GET](/docs/cloud/rest/api-reference/execution-runs-runs/list-runs), [POST](/docs/cloud/rest/api-reference/execution-runs-runs/create-run) | List runs; Create run |
| `/runs/{run_id}` | [GET](/docs/cloud/rest/api-reference/execution-runs-runs/get-run), [PATCH](/docs/cloud/rest/api-reference/execution-runs-runs/update-run), [DELETE](/docs/cloud/rest/api-reference/execution-runs-runs/delete-run) | Get run; Update run; Delete run |
| `/runs/{run_id}/event-tokens` | [POST](/docs/cloud/rest/api-reference/execution-runs-runtime/create-run-event-token) | Create run event token |
| `/runs/{run_id}/heartbeats` | [POST](/docs/cloud/rest/api-reference/execution-runs-runtime/send-run-heartbeat) | Send run heartbeat |
| `/runs/{run_id}/pause-checkpoint` | [GET](/docs/cloud/rest/api-reference/execution-runs-runtime/get-dispatch-continuation) | Get dispatch continuation |
| `/runs/{run_id}/cancellation-ack` | [POST](/docs/cloud/rest/api-reference/execution-runs-runtime/acknowledge-run-cancellation) | Acknowledge run cancellation |
| `/runs/{run_id}/pause-ack` | [POST](/docs/cloud/rest/api-reference/execution-runs-runtime/acknowledge-run-pause) | Acknowledge run pause |
| `/runs/{run_id}/child-runs` | [GET](/docs/cloud/rest/api-reference/execution-runs-child-runs/list-child-runs) | List child runs |
| `/conversations/{conversation_id}/child-runs` | [GET](/docs/cloud/rest/api-reference/execution-runs-conversation-runs/list-conversation-child-runs) | List conversation child runs |
| `/conversations/{conversation_id}/runs` | [GET](/docs/cloud/rest/api-reference/execution-runs-conversation-runs/list-conversation-runs) | List conversation runs |
| `/projects/{project_reference}/runs` | [GET](/docs/cloud/rest/api-reference/execution-runs-project-runs/list-project-runs) | List project runs |
| `/projects/{project_reference}/public-inference-runs/{run_id}` | [GET](/docs/cloud/rest/api-reference/execution-runs-project-runs/get-project-public-inference-run-status) | Get project public inference run status |
| `/projects/{project_reference}/webhooks/{webhook_definition_id}/runs` | [GET](/docs/cloud/rest/api-reference/execution-runs-webhook-runs/list-project-webhook-runs) | List project webhook runs |
| `/runs/event-types` | [GET](/docs/cloud/rest/api-reference/execution-runs-run-events/list-run-event-types) | List run event types |
| `/runs/{run_id}/events` | [GET](/docs/cloud/rest/api-reference/execution-runs-run-events/list-run-events), [POST](/docs/cloud/rest/api-reference/execution-runs-run-events/append-run-events) | List run events; Append run events |
| `/runs/{run_id}/events/{event_id}` | [GET](/docs/cloud/rest/api-reference/execution-runs-run-events/get-run-event) | Get run event |
| `/schemas/run-events/{schema_file}` | [GET](/docs/cloud/rest/api-reference/execution-runs-run-events/get-run-event-data-schema) | Get run event data schema |
| `/runs/{run_id}/events/summary` | [GET](/docs/cloud/rest/api-reference/execution-runs-run-events/get-run-event-summary) | Get run event summary |
| `/runs/{run_id}/snapshot` | [GET](/docs/cloud/rest/api-reference/execution-runs-run-events/get-run-snapshot) | Get run snapshot |
| `/conversations/{conversation_id}/runs/{run_id}/stream` | [GET](/docs/cloud/rest/api-reference/execution-runs-run-events/stream-conversation-run-events-compatibility) | Stream conversation run events (compatibility) |
| `/runs/{run_id}/stream` | [GET](/docs/cloud/rest/api-reference/execution-runs-run-events/stream-run-events) | Stream run events |
| `/runs/{run_id}/cancel` | [POST](/docs/cloud/rest/api-reference/execution-runs-run-actions/cancel-run) | Cancel run |
| `/runs/{run_id}/fail` | [POST](/docs/cloud/rest/api-reference/execution-runs-run-actions/fail-run) | Fail run |
| `/runs/{run_id}/finalize` | [POST](/docs/cloud/rest/api-reference/execution-runs-run-actions/finalize-run) | Finalize run |
| `/runs/{run_id}/pause` | [POST](/docs/cloud/rest/api-reference/execution-runs-run-actions/pause-run) | Pause run |
| `/runs/{run_id}/resume` | [POST](/docs/cloud/rest/api-reference/execution-runs-run-actions/resume-run) | Resume run |
| `/runs/{run_id}/succeed` | [POST](/docs/cloud/rest/api-reference/execution-runs-run-actions/succeed-run) | Succeed run |
| `/runs/{run_id}/artifacts/{artifact_id}` | [GET](/docs/cloud/rest/api-reference/execution-runs-run-artifacts/download-run-artifact) | Download 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.

| Endpoint | Methods | Description |
| - | - | - |
| `/projects/{project_reference}/connected-agents` | [GET](/docs/cloud/rest/api-reference/execution-executors-connected-agents/list-connected-agents) | List connected agents |
| `/agent-workers/projects/{project_reference}/workers` | [GET](/docs/cloud/rest/api-reference/execution-executors-agent-workers/list-workers) (deprecated), [POST](/docs/cloud/rest/api-reference/execution-executors-agent-workers/register-worker) | List workers; Register worker |
| `/agent-workers/workers/{worker_id}/claim` | [POST](/docs/cloud/rest/api-reference/execution-executors-agent-workers/claim-run) | Claim run |
| `/agent-workers/workers/{worker_id}` | [DELETE](/docs/cloud/rest/api-reference/execution-executors-agent-workers/delete-worker) | Delete worker |
| `/agent-workers/workers/{worker_id}/heartbeat` | [POST](/docs/cloud/rest/api-reference/execution-executors-agent-workers/heartbeat-worker) | Heartbeat worker |
| `/agent-workers/workers/{worker_id}/runs/{run_id}/session` | [PUT](/docs/cloud/rest/api-reference/execution-executors-agent-workers/update-worker-run-session) | Update worker run session |
| `/agent-workers/workers/{worker_id}/runs/{run_id}/lease` | [POST](/docs/cloud/rest/api-reference/execution-executors-agent-workers/renew-run-lease) | Renew run lease |

[Back to REST API reference](/docs/cloud/rest)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.