> ## 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. # Cancel run > Cancels an agent, workflow or task run and every active descendant, and returns the run. Requires editor access to every affected run owner. Cookie authentication also requires application/json or application/graphql-response+json and a trusted browser Origin. Eval runs cannot be cancelled here. One transaction records `run.cancellation.requested_at` on the run and each active descendant and ends them cancelled, so no new child is admitted under any of them. Finished descendants, ancestors and siblings keep their outcome. `cancelled` is true when the run ends cancelled; repeating the cancel returns the same run. A run that already completed or failed returns 409 RUN_TERMINAL_CONFLICT. `stopped_at` is set once the runtime confirms the stop and stays null while it is unconfirmed; null does not mean the run is still executing. ## OpenAPI ````yaml /cloud/rest/openapi.json post /runs/{run_id}/cancel openapi: 3.1.0 info: title: Veryfront REST API reference version: 1.0.0 description: >- ## Explore the API | API | Use it to | | --- | --- | | [Agents API](#tag/agents-api) | Define agents, tasks and workflows, and configure their prompts, skills, tools and resources. | | [Execution API](#tag/execution-api) | Start and monitor agent, task, and workflow runs. | | [Evaluations API](#tag/evaluations-api) | Define agent evaluations, run them, and inspect results. | | [AI Gateway API](#tag/ai-gateway-api) | Generate messages, responses, embeddings, and images. | | [Knowledge API](#tag/knowledge-api) | Store document metadata, index file chunks, and search project content. | | [Integrations API](#tag/integrations-api) | Connect external accounts, invoke integration tools, and configure messaging channels. | | [Projects API](#tag/projects-api) | Create projects and manage source files, branches, and uploads. | | [Deployment API](#tag/deployment-api) | Create releases and deploy them to project environments. | | [Sandbox API](#tag/sandbox-api) | Create isolated sessions, run commands, and manage files. | | [Cache API](#tag/cache-api) | Read and write cached values in project or user scope. | | [Observability API](#tag/observability-api) | Query logs, metrics, traces, and alerts to investigate application behavior. | | [Identity and Access API](#tag/identity-and-access-api) | Authenticate callers and manage account and project access. | | [Billing and Usage API](#tag/billing-and-usage-api) | Manage subscriptions, payments, credits, budgets, and usage. | [API discovery and metadata](#tag/api-discovery-and-metadata) · [OpenAPI specification (JSON)](/openapi.json) contact: name: Veryfront API Support url: https://veryfront.com/docs email: support@veryfront.com x-api-id: 5f1f0b8a-6b0e-4c1a-9b35-0f3a1e6d84c7 x-audience: external-public servers: - url: https://api.veryfront.com security: - bearerAuth: [] - apiKeyAuth: [] tags: - name: Agents API description: >- Define agents, tasks and workflows, and configure their prompts, skills, tools and resources. | Endpoint group | Use it to | | --- | --- | | [Accessible agents](/cloud/rest/apis/agents-api#accessible-agents) | List agents you can access across projects. Each result includes the project needed to locate its definition. | | [Agent templates](/cloud/rest/apis/agents-api#agent-templates) | Browse agent templates. Use [agent installation](/cloud/rest/apis/agents-api#agent-installation) to add a selected template. | | [Project agents](/cloud/rest/apis/agents-api#project-agents) | Create and edit project agent definitions. Use [Runs](/cloud/rest/apis/execution-api#runs) to start and monitor agent runs. | | [Agent Capabilities](/cloud/rest/apis/agents-api#agent-capabilities) | Read project capabilities and the capabilities enabled for an agent. | | [Agent Tool References](/cloud/rest/apis/agents-api#agent-tool-references) | Search tools that can be attached to agents. | | [Agent Labels](/cloud/rest/apis/agents-api#agent-labels) | List, create, update, or delete labels on an agent. | | [Agent Avatars](/cloud/rest/apis/agents-api#agent-avatars) | Preview, generate, or read agent avatars. | | [Agent Installation](/cloud/rest/apis/agents-api#agent-installation) | Install or remove agents from selected projects. | | [Project prompts](/cloud/rest/apis/agents-api#project-prompts) | Manage prompts stored in project source. List prompts, read their source, and edit supported fields for the selected source version. | | [Project skills](/cloud/rest/apis/agents-api#project-skills) | Manage skills stored in project source. List skills, read their source, and edit the fields supported by the selected source and definition format. | | [Project tools](/cloud/rest/apis/agents-api#project-tools) | Manage tool definitions in project source. Use [integration tool endpoints](/cloud/rest/apis/integrations-api#integration-tools) to discover and invoke connected-service tools. | | [Project tasks](/cloud/rest/apis/agents-api#project-tasks) | Manage task definitions stored in project source. List definitions, read their source, and edit supported fields. To start a task run, use [`POST /runs`](/cloud/rest/api-reference/runs/create-run) with `kind: "task"` and the task’s execution target. | | [Project workflows](/cloud/rest/apis/agents-api#project-workflows) | Manage workflow definitions stored in project source. List definitions, read their source, and edit supported fields. To start a workflow run, use [`POST /runs`](/cloud/rest/api-reference/runs/create-run) with `kind: "workflow"` and the workflow’s execution target. | | [Project resources](/cloud/rest/apis/agents-api#project-resources) | Create and edit project resource documents. Manage servers and other deployment infrastructure through the [Deployment API](/cloud/rest/apis/deployment-api). | - name: Accessible agents description: >- List agents you can access across projects. Each result includes the project needed to locate its definition. - name: Agent templates description: >- Browse agent templates. Use [agent installation](/cloud/rest/apis/agents-api#agent-installation) to add a selected template. - name: Project agents description: >- Create and edit project agent definitions. Use [Runs](/cloud/rest/apis/execution-api#runs) to start and monitor agent runs. - name: Agent Capabilities description: Read project capabilities and the capabilities enabled for an agent. - name: Agent Tool References description: Search tools that can be attached to agents. - name: Agent Labels description: List, create, update, or delete labels on an agent. - name: Agent Avatars description: Preview, generate, or read agent avatars. - name: Agent Installation description: Install or remove agents from selected projects. - name: Project prompts description: >- Manage prompts stored in project source. List prompts, read their source, and edit supported fields for the selected source version. - name: Project skills description: >- Manage skills stored in project source. List skills, read their source, and edit the fields supported by the selected source and definition format. - name: Project tools description: >- Manage tool definitions in project source. Use [integration tool endpoints](/cloud/rest/apis/integrations-api#integration-tools) to discover and invoke connected-service tools. - name: Project tasks description: >- Manage task definitions stored in project source. List definitions, read their source, and edit supported fields. To start a task run, use [`POST /runs`](/cloud/rest/api-reference/runs/create-run) with `kind: "task"` and the task’s execution target. - name: Project workflows description: >- Manage workflow definitions stored in project source. List definitions, read their source, and edit supported fields. To start a workflow run, use [`POST /runs`](/cloud/rest/api-reference/runs/create-run) with `kind: "workflow"` and the workflow’s execution target. - name: Project resources description: >- Create and edit project resource documents. Manage servers and other deployment infrastructure through the [Deployment API](/cloud/rest/apis/deployment-api). - name: Execution API description: >- Start and monitor agent, task, and workflow runs. | Endpoint group | Use it to | | --- | --- | | [Runs](/cloud/rest/apis/execution-api#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. | | [Conversations](/cloud/rest/apis/execution-api#conversations) | Create, read, update, or delete conversations. Find runs and input requests under [Runs](/cloud/rest/apis/execution-api#runs). | | [Conversation Messages](/cloud/rest/apis/execution-api#conversation-messages) | List, send, read, edit, or delete messages. | | [Conversation Branches](/cloud/rest/apis/execution-api#conversation-branches) | Fork messages and select the active branch. | | [Conversation Participants](/cloud/rest/apis/execution-api#conversation-participants) | List, add, or remove participants. | | [Conversation Read State](/cloud/rest/apis/execution-api#conversation-read-state) | Read or update conversation read state. | | [Participant lookup](/cloud/rest/apis/execution-api#participant-lookup) | Find an existing participant identity by user or agent ID. Use the conversation participant endpoints to [add](/cloud/rest/api-reference/conversation-participants/add-participant) or [remove](/cloud/rest/api-reference/conversation-participants/remove-participant) users. | | [Project schedules](/cloud/rest/apis/execution-api#project-schedules) | Configure schedules. To start a run from an existing schedule, use [`POST /projects/{project_reference}/schedules/{schedule_id}/runs`](/cloud/rest/api-reference/runs/create-scheduled-run). | | [Project webhooks](/cloud/rest/apis/execution-api#project-webhooks) | Configure automation webhooks and replay recorded deliveries. Start a webhook run and list its runs under [Runs](/cloud/rest/apis/execution-api#runs). | - name: Runs description: >- 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. | Operations | Use them to | | --- | --- | | Lifecycle | Create, list, get, cancel, pause, and resume runs, and read account run analytics. | | Events | Read, summarize, and stream run events, and list the event types. | | Input requests | Create, find, cancel, and respond to the input requests a run waits for. | | Children | List the child runs a run starts. | | Triggers | Start runs from schedules, webhooks, and evaluations, and list the runs they started. | - name: Conversations description: >- Create, read, update, or delete conversations. Find runs and input requests under [Runs](/cloud/rest/apis/execution-api#runs). - name: Conversation Messages description: List, send, read, edit, or delete messages. - name: Conversation Branches description: Fork messages and select the active branch. - name: Conversation Participants description: List, add, or remove participants. - name: Conversation Read State description: Read or update conversation read state. - name: Participant lookup description: >- Find an existing participant identity by user or agent ID. Use the conversation participant endpoints to [add](/cloud/rest/api-reference/conversation-participants/add-participant) or [remove](/cloud/rest/api-reference/conversation-participants/remove-participant) users. - name: Project schedules description: >- Configure schedules. To start a run from an existing schedule, use [`POST /projects/{project_reference}/schedules/{schedule_id}/runs`](/cloud/rest/api-reference/runs/create-scheduled-run). - name: Project webhooks description: >- Configure automation webhooks and replay recorded deliveries. Start a webhook run and list its runs under [Runs](/cloud/rest/apis/execution-api#runs). - name: Evaluations API description: >- Define agent evaluations, run them, and inspect results. | Endpoint group | Use it to | | --- | --- | | [Evaluation Definitions](/cloud/rest/apis/evaluations-api#evaluation-definitions) | List and create evaluation definitions stored in project source. Read the source document to inspect its dataset, metrics, and editable fields, then update supported fields. | - name: Evaluation Definitions description: >- List and create evaluation definitions stored in project source. Read the source document to inspect its dataset, metrics, and editable fields, then update supported fields. - name: AI Gateway API description: >- Generate messages, responses, embeddings, and images. | Endpoint group | Use it to | | --- | --- | | [Model discovery](/cloud/rest/apis/ai-gateway-api#model-discovery) | Find available models and inspect their metadata. Provider-compatible model lists are grouped with [inference models](/cloud/rest/apis/ai-gateway-api#inference-models). | | [Anthropic Messages](/cloud/rest/apis/ai-gateway-api#anthropic-messages) | Create Anthropic-compatible messages or count message tokens. | | [OpenAI Chat Completions](/cloud/rest/apis/ai-gateway-api#openai-chat-completions) | Create OpenAI-compatible chat completions. | | [OpenAI Responses](/cloud/rest/apis/ai-gateway-api#openai-responses) | Create OpenAI-compatible responses. | | [Embeddings](/cloud/rest/apis/ai-gateway-api#embeddings) | Create embeddings. | | [Inference Models](/cloud/rest/apis/ai-gateway-api#inference-models) | List provider-compatible inference models. | | [Gemini Models](/cloud/rest/apis/ai-gateway-api#gemini-models) | Call Gemini-compatible generateContent methods. | | [Image generation](/cloud/rest/apis/ai-gateway-api#image-generation) | Generate images from a prompt. Manage generated images through [project upload endpoints](/cloud/rest/apis/projects-api#project-uploads). | | [Provider gateway](/cloud/rest/apis/ai-gateway-api#provider-gateway) | Use [billing finalization](/cloud/rest/api-reference/provider-gateway/finalize-gateway-billing-group) when your integration manages gateway billing groups. Inspect spending limits through [budgets](/cloud/rest/apis/billing-and-usage-api#budgets). | | [Project inference policy](/cloud/rest/apis/ai-gateway-api#project-inference-policy) | Read, replace, or clear project inference constraints. These endpoints require a signed-in project administrator. Record standard-tier consent through [the opt-in endpoint](/cloud/rest/api-reference/project-inference-policy/opt-in-to-standard-tier-serving). | - name: Model discovery description: >- Find available models and inspect their metadata. Provider-compatible model lists are grouped with [inference models](/cloud/rest/apis/ai-gateway-api#inference-models). - name: Anthropic Messages description: Create Anthropic-compatible messages or count message tokens. - name: OpenAI Chat Completions description: Create OpenAI-compatible chat completions. - name: OpenAI Responses description: Create OpenAI-compatible responses. - name: Embeddings description: Create embeddings. - name: Inference Models description: List provider-compatible inference models. - name: Gemini Models description: Call Gemini-compatible generateContent methods. - name: Image generation description: >- Generate images from a prompt. Manage generated images through [project upload endpoints](/cloud/rest/apis/projects-api#project-uploads). - name: Provider gateway description: >- Use [billing finalization](/cloud/rest/api-reference/provider-gateway/finalize-gateway-billing-group) when your integration manages gateway billing groups. Inspect spending limits through [budgets](/cloud/rest/apis/billing-and-usage-api#budgets). - name: Project inference policy description: >- Read, replace, or clear project inference constraints. These endpoints require a signed-in project administrator. Record standard-tier consent through [the opt-in endpoint](/cloud/rest/api-reference/project-inference-policy/opt-in-to-standard-tier-serving). - name: Knowledge API description: >- Store document metadata, index file chunks, and search project content. | Endpoint group | Use it to | | --- | --- | | [Project documents](/cloud/rest/apis/knowledge-api#project-documents) | List, create, or update metadata records in the project’s retrieval-augmented generation (RAG) store. Use [project file endpoints](/cloud/rest/apis/projects-api#project-files) to edit source content. | | [File Chunks](/cloud/rest/apis/knowledge-api#file-chunks) | Read file chunks used for indexing. Create or delete chunks on a branch, or read chunks from a branch, environment, or release. | | [Project embeddings](/cloud/rest/apis/knowledge-api#project-embeddings) | Store and retrieve vectors by chunk ID. Generate vectors through [the embeddings endpoint](/cloud/rest/api-reference/embeddings/create-embeddings) or your provider before storing them here. | | [Vector search](/cloud/rest/apis/knowledge-api#vector-search) | Search indexed content with an embedding vector. Choose the branch, environment, or release endpoint for the content you need. | | [Project knowledge](/cloud/rest/apis/knowledge-api#project-knowledge) | Search metadata in project knowledge files. Specify a branch, environment, or release to query the required content version. | - name: Project documents description: >- List, create, or update metadata records in the project’s retrieval-augmented generation (RAG) store. Use [project file endpoints](/cloud/rest/apis/projects-api#project-files) to edit source content. - name: File Chunks description: >- Read file chunks used for indexing. Create or delete chunks on a branch, or read chunks from a branch, environment, or release. - name: Project embeddings description: >- Store and retrieve vectors by chunk ID. Generate vectors through [the embeddings endpoint](/cloud/rest/api-reference/embeddings/create-embeddings) or your provider before storing them here. - name: Vector search description: >- Search indexed content with an embedding vector. Choose the branch, environment, or release endpoint for the content you need. - name: Project knowledge description: >- Search metadata in project knowledge files. Specify a branch, environment, or release to query the required content version. - name: Integrations API description: >- Connect external accounts, invoke integration tools, and configure messaging channels. | Endpoint group | Use it to | | --- | --- | | [Integration catalog](/cloud/rest/apis/integrations-api#integration-catalog) | Browse integrations and read their metadata, icons, and connection summaries. Configure project-specific settings through the [project integration endpoints](/cloud/rest/apis/integrations-api#project-integrations). | | [Project integrations](/cloud/rest/apis/integrations-api#project-integrations) | Read or update an integration’s project configuration and connection state. Some integrations also expose service-specific metadata, such as Salesforce objects and fields. | | [Integration OAuth](/cloud/rest/apis/integrations-api#integration-oauth) | Authorize or disconnect an external account. Use [platform authentication](/cloud/rest/apis/identity-and-access-api#authentication) to sign in to Veryfront. Inspect connection status and retrieve tokens with the required permissions. | | [Connections](/cloud/rest/apis/integrations-api#connections) | List connected external accounts across projects you can access. | | [Integration tools](/cloud/rest/apis/integrations-api#integration-tools) | List tools exposed by connected services and invoke them with the required connection context. Manage source-defined tools through the [Agents API](/cloud/rest/apis/agents-api#project-tools). | | [Channel Bindings](/cloud/rest/apis/integrations-api#channel-bindings) | List, create, read, update, delete, or test channel bindings. | | [Channel Platforms](/cloud/rest/apis/integrations-api#channel-platforms) | Read, update, delete, or test platform channel configuration. | | [Channel Assistants](/cloud/rest/apis/integrations-api#channel-assistants) | List assistants that can receive channel messages. | | [Slack Channels](/cloud/rest/apis/integrations-api#slack-channels) | List Slack conversations available to a project channel integration. | | [Provider Files](/cloud/rest/apis/integrations-api#provider-files) | Browse, upload, move, import, or delete provider files. Use [project files](/cloud/rest/apis/projects-api#project-files) for files already stored in a project. | | [Provider Folders](/cloud/rest/apis/integrations-api#provider-folders) | Create folders through a connected storage provider. | | [Provider Search](/cloud/rest/apis/integrations-api#provider-search) | Search files through a connected storage provider. | - name: Integration catalog description: >- Browse integrations and read their metadata, icons, and connection summaries. Configure project-specific settings through the [project integration endpoints](/cloud/rest/apis/integrations-api#project-integrations). - name: Project integrations description: >- Read or update an integration’s project configuration and connection state. Some integrations also expose service-specific metadata, such as Salesforce objects and fields. - name: Integration OAuth description: >- Authorize or disconnect an external account. Use [platform authentication](/cloud/rest/apis/identity-and-access-api#authentication) to sign in to Veryfront. Inspect connection status and retrieve tokens with the required permissions. - name: Connections description: List connected external accounts across projects you can access. - name: Integration tools description: >- List tools exposed by connected services and invoke them with the required connection context. Manage source-defined tools through the [Agents API](/cloud/rest/apis/agents-api#project-tools). - name: Channel Bindings description: List, create, read, update, delete, or test channel bindings. - name: Channel Platforms description: Read, update, delete, or test platform channel configuration. - name: Channel Assistants description: List assistants that can receive channel messages. - name: Slack Channels description: List Slack conversations available to a project channel integration. - name: Provider Files description: >- Browse, upload, move, import, or delete provider files. Use [project files](/cloud/rest/apis/projects-api#project-files) for files already stored in a project. - name: Provider Folders description: Create folders through a connected storage provider. - name: Provider Search description: Search files through a connected storage provider. - name: Projects API description: >- Create projects and manage source files, branches, and uploads. | Endpoint group | Use it to | | --- | --- | | [Projects](/cloud/rest/apis/projects-api#projects) | List, create, read, update, or delete projects. | | [Project Labels](/cloud/rest/apis/projects-api#project-labels) | List, create, update, or delete project labels. | | [Account Projects](/cloud/rest/apis/projects-api#account-projects) | List or create projects assigned to an account. | | [Project Templates](/cloud/rest/apis/projects-api#project-templates) | List or search starter templates before creating a project. | | [Project Files](/cloud/rest/apis/projects-api#project-files) | List, read, write, move, delete, diff, or batch-read project files. | | [Project File Versions](/cloud/rest/apis/projects-api#project-file-versions) | List or read saved project file versions. | | [File search](/cloud/rest/apis/projects-api#file-search) | Search project or branch files by text. Use the [Knowledge API](/cloud/rest/apis/knowledge-api#vector-search) for vector search. | | [Branches](/cloud/rest/apis/projects-api#branches) | Create, read, delete, preview, check, or merge branches. | | [Branch Approvals](/cloud/rest/apis/projects-api#branch-approvals) | List, create, or dismiss branch approvals. | | [Branch Status Checks](/cloud/rest/apis/projects-api#branch-status-checks) | List or upsert branch status checks. | | [Branch Policies](/cloud/rest/apis/projects-api#branch-policies) | List, create, or delete branch policies. | | [Project Commits](/cloud/rest/apis/projects-api#project-commits) | Commit project file changes. | | [Branch Files](/cloud/rest/apis/projects-api#branch-files) | Read branch files and diffs. | | [Branch File Versions](/cloud/rest/apis/projects-api#branch-file-versions) | List or read saved branch file versions. | | [Branch File Drafts](/cloud/rest/apis/projects-api#branch-file-drafts) | Read, replace, or discard pending file drafts. | | [Environment Files](/cloud/rest/apis/projects-api#environment-files) | Read files and diffs from a named environment. Manage environment settings through [Environments](/cloud/rest/apis/deployment-api#environments). | | [Release Files](/cloud/rest/apis/projects-api#release-files) | Read files and diffs from a specific release. | | [Project Uploads](/cloud/rest/apis/projects-api#project-uploads) | List, upload, read, move, restore, delete, or get download URLs for uploads. | | [Upload Folders](/cloud/rest/apis/projects-api#upload-folders) | Create, rename, or delete upload folders. | | [Upload Grants](/cloud/rest/apis/projects-api#upload-grants) | List, set, or revoke upload grants. | | [Upload Visibility](/cloud/rest/apis/projects-api#upload-visibility) | Set or remove upload path visibility. | | [Dependencies](/cloud/rest/apis/projects-api#dependencies) | Resolve and pin project dependencies. Read recent dependency metadata to inspect the recorded configuration. | | [Style artifacts](/cloud/rest/apis/projects-api#style-artifacts) | Read or register the current CSS artifact and request its background build. Select the project and style profile in the request. | | [Favorites](/cloud/rest/apis/projects-api#favorites) | List, add, or remove favorite projects for the current user. Favorites do not grant project access. | - name: Projects description: List, create, read, update, or delete projects. - name: Project Labels description: List, create, update, or delete project labels. - name: Account Projects description: List or create projects assigned to an account. - name: Project Templates description: List or search starter templates before creating a project. - name: Project Files description: List, read, write, move, delete, diff, or batch-read project files. - name: Project File Versions description: List or read saved project file versions. - name: File search description: >- Search project or branch files by text. Use the [Knowledge API](/cloud/rest/apis/knowledge-api#vector-search) for vector search. - name: Branches description: Create, read, delete, preview, check, or merge branches. - name: Branch Approvals description: List, create, or dismiss branch approvals. - name: Branch Status Checks description: List or upsert branch status checks. - name: Branch Policies description: List, create, or delete branch policies. - name: Project Commits description: Commit project file changes. - name: Branch Files description: Read branch files and diffs. - name: Branch File Versions description: List or read saved branch file versions. - name: Branch File Drafts description: Read, replace, or discard pending file drafts. - name: Environment Files description: >- Read files and diffs from a named environment. Manage environment settings through [Environments](/cloud/rest/apis/deployment-api#environments). - name: Release Files description: Read files and diffs from a specific release. - name: Project Uploads description: >- List, upload, read, move, restore, delete, or get download URLs for uploads. - name: Upload Folders description: Create, rename, or delete upload folders. - name: Upload Grants description: List, set, or revoke upload grants. - name: Upload Visibility description: Set or remove upload path visibility. - name: Dependencies description: >- Resolve and pin project dependencies. Read recent dependency metadata to inspect the recorded configuration. - name: Style artifacts description: >- Read or register the current CSS artifact and request its background build. Select the project and style profile in the request. - name: Favorites description: >- List, add, or remove favorite projects for the current user. Favorites do not grant project access. - name: Deployment API description: >- Create releases and deploy them to project environments. | Endpoint group | Use it to | | --- | --- | | [Releases](/cloud/rest/apis/deployment-api#releases) | Create, read, delete, or find project releases. | | [Release Versions](/cloud/rest/apis/deployment-api#release-versions) | List the versions recorded for a release. | | [Release Source Manifests](/cloud/rest/apis/deployment-api#release-source-manifests) | Export the source manifest for a release. | | [Release Asset Manifests](/cloud/rest/apis/deployment-api#release-asset-manifests) | Read, write, build, or update release asset manifests. | | [Environments](/cloud/rest/apis/deployment-api#environments) | Create and manage deployment environments. Use the environment ID when configuring [deployments](/cloud/rest/apis/deployment-api#project-deployments), [domains](/cloud/rest/apis/deployment-api#environment-domains), [variables](/cloud/rest/apis/deployment-api#environment-variables), or [servers](/cloud/rest/apis/deployment-api#environment-servers). | | [Project deployments](/cloud/rest/apis/deployment-api#project-deployments) | Deploy a release to an environment. Read deployment records to inspect the resulting configuration. Investigate application behavior through [project logs](/cloud/rest/apis/observability-api#project-logs). | | [Project Domains](/cloud/rest/apis/deployment-api#project-domains) | List domains across a project. | | [Environment Domains](/cloud/rest/apis/deployment-api#environment-domains) | Create, read, update, or delete domains for an environment. | | [Environment Variable Keys](/cloud/rest/apis/deployment-api#environment-variable-keys) | List environment variable keys without values. | | [Environment variables](/cloud/rest/apis/deployment-api#environment-variables) | List, create, read, update, or delete environment variables. | | [Project servers](/cloud/rest/apis/deployment-api#project-servers) | List, read, or delete project server records. | | [Environment Servers](/cloud/rest/apis/deployment-api#environment-servers) | Create a server for an environment. | | [Proxy metadata](/cloud/rest/apis/deployment-api#proxy-metadata) | Read routing or access metadata for proxy requests. These endpoints have separate freshness and authorization requirements. | - name: Releases description: Create, read, delete, or find project releases. - name: Release Versions description: List the versions recorded for a release. - name: Release Source Manifests description: Export the source manifest for a release. - name: Release Asset Manifests description: Read, write, build, or update release asset manifests. - name: Environments description: >- Create and manage deployment environments. Use the environment ID when configuring [deployments](/cloud/rest/apis/deployment-api#project-deployments), [domains](/cloud/rest/apis/deployment-api#environment-domains), [variables](/cloud/rest/apis/deployment-api#environment-variables), or [servers](/cloud/rest/apis/deployment-api#environment-servers). - name: Project deployments description: >- Deploy a release to an environment. Read deployment records to inspect the resulting configuration. Investigate application behavior through [project logs](/cloud/rest/apis/observability-api#project-logs). - name: Project Domains description: List domains across a project. - name: Environment Domains description: Create, read, update, or delete domains for an environment. - name: Environment Variable Keys description: List environment variable keys without values. - name: Environment variables description: List, create, read, update, or delete environment variables. - name: Project servers description: List, read, or delete project server records. - name: Environment Servers description: Create a server for an environment. - name: Proxy metadata description: >- Read routing or access metadata for proxy requests. These endpoints have separate freshness and authorization requirements. - name: Sandbox API description: >- Create isolated sessions, run commands, and manage files. | Endpoint group | Use it to | | --- | --- | | [Sandbox Sessions](/cloud/rest/apis/sandbox-api#sandbox-sessions) | Create, read, update, or delete sandbox sessions. | | [Sandbox Commands](/cloud/rest/apis/sandbox-api#sandbox-commands) | Run commands and inspect command output. | | [Sandbox Files](/cloud/rest/apis/sandbox-api#sandbox-files) | List, read, or write sandbox files. | | [Sandbox Terminal](/cloud/rest/apis/sandbox-api#sandbox-terminal) | Open a sandbox terminal. | | [Sandbox Health](/cloud/rest/apis/sandbox-api#sandbox-health) | Check sandbox health, readiness, and heartbeat state. | - name: Sandbox Sessions description: Create, read, update, or delete sandbox sessions. - name: Sandbox Commands description: Run commands and inspect command output. - name: Sandbox Files description: List, read, or write sandbox files. - name: Sandbox Terminal description: Open a sandbox terminal. - name: Sandbox Health description: Check sandbox health, readiness, and heartbeat state. - name: Cache API description: >- Read and write cached values in project or user scope. | Endpoint group | Use it to | | --- | --- | | [Project Cache](/cloud/rest/apis/cache-api#project-cache) | Read and write individual values or batches. Inspect keys and statistics, delete matching keys, or clear the project cache. | | [User Cache](/cloud/rest/apis/cache-api#user-cache) | Read, write, or delete values in the authenticated user’s cache. | - name: Project Cache description: >- Read and write individual values or batches. Inspect keys and statistics, delete matching keys, or clear the project cache. - name: User Cache description: Read, write, or delete values in the authenticated user’s cache. - name: Observability API description: >- Query logs, metrics, traces, and alerts to investigate application behavior. | Endpoint group | Use it to | | --- | --- | | [Project logs](/cloud/rest/apis/observability-api#project-logs) | Query project logs to investigate activity and failures. Each endpoint reference lists the supported filters. | | [Project metrics](/cloud/rest/apis/observability-api#project-metrics) | Query project metrics to inspect measurements over time. | | [Project traces](/cloud/rest/apis/observability-api#project-traces) | Find project traces and inspect individual traces by ID. Trace spans connect related execution activity. For a run’s event history, use the [run endpoints](/cloud/rest/apis/execution-api#runs). | | [Project alerts](/cloud/rest/apis/observability-api#project-alerts) | List the alerts that fired for a project, firing and recently resolved, with links to the logs and traces they cover. | | [Account conversation analytics](/cloud/rest/apis/observability-api#account-conversation-analytics) | Read account-level conversation analytics. Find account run analytics under [Runs](/cloud/rest/apis/execution-api#runs). Use the [Billing and Usage API](/cloud/rest/apis/billing-and-usage-api) for consumption and spending data. | - name: Project logs description: >- Query project logs to investigate activity and failures. Each endpoint reference lists the supported filters. - name: Project metrics description: Query project metrics to inspect measurements over time. - name: Project traces description: >- Find project traces and inspect individual traces by ID. Trace spans connect related execution activity. For a run’s event history, use the [run endpoints](/cloud/rest/apis/execution-api#runs). - name: Project alerts description: >- List the alerts that fired for a project, firing and recently resolved, with links to the logs and traces they cover. - name: Account conversation analytics description: >- Read account-level conversation analytics. Find account run analytics under [Runs](/cloud/rest/apis/execution-api#runs). Use the [Billing and Usage API](/cloud/rest/apis/billing-and-usage-api) for consumption and spending data. - name: Identity and Access API description: >- Authenticate callers and manage account and project access. | Endpoint group | Use it to | | --- | --- | | [Authentication](/cloud/rest/apis/identity-and-access-api#authentication) | Sign in through an identity provider or magic link, create tokens, and end sessions. Retrieve public verification keys from [the JWKS endpoint](/cloud/rest/api-reference/authentication/get-jwks). | | [Current user](/cloud/rest/apis/identity-and-access-api#current-user) | Read the authenticated user’s profile. | | [Accounts](/cloud/rest/apis/identity-and-access-api#accounts) | List, create, or read accounts. | | [Account Collaboration](/cloud/rest/apis/identity-and-access-api#account-collaboration) | Read owner-wide collaboration entitlements and seat usage. The project reference selects its owner. | | [Account Members](/cloud/rest/apis/identity-and-access-api#account-members) | List, update, or remove account members. | | [Account Invitations](/cloud/rest/apis/identity-and-access-api#account-invitations) | List, create, revoke, or accept account invitations. | | [Account directory](/cloud/rest/apis/identity-and-access-api#account-directory) | List pending invitations and active members across projects you own. | | [Project Members](/cloud/rest/apis/identity-and-access-api#project-members) | List, read, remove, or update project members. | | [Project Invitations](/cloud/rest/apis/identity-and-access-api#project-invitations) | Create, read, delete, or resend project invitations. | | [Project Ownership](/cloud/rest/apis/identity-and-access-api#project-ownership) | Transfer project ownership. | | [API keys](/cloud/rest/apis/identity-and-access-api#api-keys) | Create, inspect, update, and revoke API keys. View [API key usage](/cloud/rest/apis/billing-and-usage-api#api-key-usage) in the Billing and Usage API. | | [OAuth Metadata](/cloud/rest/apis/identity-and-access-api#oauth-metadata) | Discover OAuth authorization and protected-resource metadata. | | [OAuth Clients](/cloud/rest/apis/identity-and-access-api#oauth-clients) | Register public OAuth clients. | | [OAuth Authorization Requests](/cloud/rest/apis/identity-and-access-api#oauth-authorization-requests) | Start, read, or decide MCP authorization requests. | | [OAuth Tokens](/cloud/rest/apis/identity-and-access-api#oauth-tokens) | Exchange, rotate, or revoke OAuth tokens. | | [OAuth Grants](/cloud/rest/apis/identity-and-access-api#oauth-grants) | List or revoke authorized MCP app grants. | - name: Authentication description: >- Sign in through an identity provider or magic link, create tokens, and end sessions. Retrieve public verification keys from [the JWKS endpoint](/cloud/rest/api-reference/authentication/get-jwks). - name: Current user description: Read the authenticated user’s profile. - name: Accounts description: List, create, or read accounts. - name: Account Collaboration description: >- Read owner-wide collaboration entitlements and seat usage. The project reference selects its owner. - name: Account Members description: List, update, or remove account members. - name: Account Invitations description: List, create, revoke, or accept account invitations. - name: Account directory description: List pending invitations and active members across projects you own. - name: Project Members description: List, read, remove, or update project members. - name: Project Invitations description: Create, read, delete, or resend project invitations. - name: Project Ownership description: Transfer project ownership. - name: API keys description: >- Create, inspect, update, and revoke API keys. View [API key usage](/cloud/rest/apis/billing-and-usage-api#api-key-usage) in the Billing and Usage API. - name: OAuth Metadata description: Discover OAuth authorization and protected-resource metadata. - name: OAuth Clients description: Register public OAuth clients. - name: OAuth Authorization Requests description: Start, read, or decide MCP authorization requests. - name: OAuth Tokens description: Exchange, rotate, or revoke OAuth tokens. - name: OAuth Grants description: List or revoke authorized MCP app grants. - name: Billing and Usage API description: >- Manage subscriptions, payments, credits, budgets, and usage. | Endpoint group | Use it to | | --- | --- | | [Subscriptions](/cloud/rest/apis/billing-and-usage-api#subscriptions) | Read, upgrade, or cancel the account subscription. Create [a checkout session](/cloud/rest/api-reference/subscriptions/create-checkout-session) or open [the billing portal](/cloud/rest/api-reference/subscriptions/get-billing-portal-url). | | [Billing Details](/cloud/rest/apis/billing-and-usage-api#billing-details) | Read or update account billing details. | | [Invoices](/cloud/rest/apis/billing-and-usage-api#invoices) | List invoices and upcoming invoices. | | [Payment Methods](/cloud/rest/apis/billing-and-usage-api#payment-methods) | List, attach, detach, or select payment methods. | | [Payments](/cloud/rest/apis/billing-and-usage-api#payments) | List account payments. | | [Credits](/cloud/rest/apis/billing-and-usage-api#credits) | Check the credit balance, review transactions, buy credits, or redeem a coupon. | | [Budgets](/cloud/rest/apis/billing-and-usage-api#budgets) | Set monthly AI spending caps by project, person, API key, or a combination of these fields. New budgets count spending already incurred that month; use [`PATCH /budgets/{budget_id}`](/cloud/rest/api-reference/budgets/update-budget) to change an existing cap. | | [Account usage](/cloud/rest/apis/billing-and-usage-api#account-usage) | Read account consumption, credit usage, limits, trends, and warnings. | | [Project usage](/cloud/rest/apis/billing-and-usage-api#project-usage) | Use [member usage](/cloud/rest/api-reference/project-usage/get-project-member-usage) for project AI spend by person and automation. The [project usage endpoint](/cloud/rest/api-reference/project-usage/get-project-usage) returns the project owner’s account-wide totals, not project-attributed usage. | | [API key usage](/cloud/rest/apis/billing-and-usage-api#api-key-usage) | List usage across API keys or inspect one key. Manage the keys themselves through [API key endpoints](/cloud/rest/apis/identity-and-access-api#api-keys). Manage [inference limits](/cloud/rest/api-reference/api-key-usage/get-api-key-inference-limits) for project-bound keys. | | [Feature gates](/cloud/rest/apis/billing-and-usage-api#feature-gates) | Check access to a named plan or feature gate. Individual endpoints still enforce their resource permissions. | - name: Subscriptions description: >- Read, upgrade, or cancel the account subscription. Create [a checkout session](/cloud/rest/api-reference/subscriptions/create-checkout-session) or open [the billing portal](/cloud/rest/api-reference/subscriptions/get-billing-portal-url). - name: Billing Details description: Read or update account billing details. - name: Invoices description: List invoices and upcoming invoices. - name: Payment Methods description: List, attach, detach, or select payment methods. - name: Payments description: List account payments. - name: Credits description: >- Check the credit balance, review transactions, buy credits, or redeem a coupon. - name: Budgets description: >- Set monthly AI spending caps by project, person, API key, or a combination of these fields. New budgets count spending already incurred that month; use [`PATCH /budgets/{budget_id}`](/cloud/rest/api-reference/budgets/update-budget) to change an existing cap. - name: Account usage description: Read account consumption, credit usage, limits, trends, and warnings. - name: Project usage description: >- Use [member usage](/cloud/rest/api-reference/project-usage/get-project-member-usage) for project AI spend by person and automation. The [project usage endpoint](/cloud/rest/api-reference/project-usage/get-project-usage) returns the project owner’s account-wide totals, not project-attributed usage. - name: API key usage description: >- List usage across API keys or inspect one key. Manage the keys themselves through [API key endpoints](/cloud/rest/apis/identity-and-access-api#api-keys). Manage [inference limits](/cloud/rest/api-reference/api-key-usage/get-api-key-inference-limits) for project-bound keys. - name: Feature gates description: >- Check access to a named plan or feature gate. Individual endpoints still enforce their resource permissions. - name: API discovery and metadata description: >- Discover tools, inspect schemas, and look up API error types. | Endpoint group | Use it to | | --- | --- | | [MCP discovery](/cloud/rest/apis/api-discovery-and-metadata#mcp-discovery) | List MCP tools and inspect their schemas before invoking them through the [MCP interface](https://veryfront.com/docs/cloud/rest/protocols#mcp). Use [the MCP playground](/cloud/rest/api-reference/mcp-discovery/open-mcp-playground) to explore tools. The older catalog alias is deprecated; use [the tool list](/cloud/rest/api-reference/mcp-discovery/list-public-mcp-tools) and [tool details](/cloud/rest/api-reference/mcp-discovery/get-public-mcp-tool-detail). | | [Error metadata](/cloud/rest/apis/api-discovery-and-metadata#error-metadata) | Read the meaning of a published error type. Use [logs](/cloud/rest/apis/observability-api#project-logs) or [traces](/cloud/rest/apis/observability-api#project-traces) to investigate a specific failed request. | - name: MCP discovery description: >- List MCP tools and inspect their schemas before invoking them through the [MCP interface](https://veryfront.com/docs/cloud/rest/protocols#mcp). Use [the MCP playground](/cloud/rest/api-reference/mcp-discovery/open-mcp-playground) to explore tools. The older catalog alias is deprecated; use [the tool list](/cloud/rest/api-reference/mcp-discovery/list-public-mcp-tools) and [tool details](/cloud/rest/api-reference/mcp-discovery/get-public-mcp-tool-detail). - name: Error metadata description: >- Read the meaning of a published error type. Use [logs](/cloud/rest/apis/observability-api#project-logs) or [traces](/cloud/rest/apis/observability-api#project-traces) to investigate a specific failed request. paths: /runs/{run_id}/cancel: post: tags: - Runs summary: Cancel run description: >- Cancels an agent, workflow or task run and every active descendant, and returns the run. Requires editor access to every affected run owner. Cookie authentication also requires application/json or application/graphql-response+json and a trusted browser Origin. Eval runs cannot be cancelled here. One transaction records `run.cancellation.requested_at` on the run and each active descendant and ends them cancelled, so no new child is admitted under any of them. Finished descendants, ancestors and siblings keep their outcome. `cancelled` is true when the run ends cancelled; repeating the cancel returns the same run. A run that already completed or failed returns 409 RUN_TERMINAL_CONFLICT. `stopped_at` is set once the runtime confirms the stop and stays null while it is unconfirmed; null does not mean the run is still executing. operationId: cancelRun parameters: - schema: type: string minLength: 1 required: true name: run_id in: path responses: '200': description: Run canceled. content: application/json: schema: type: object properties: cancelled: type: boolean run: type: object properties: run_id: type: string minLength: 1 id: type: string minLength: 1 description: The run id. Same value as run_id, which it replaces. kind: type: string enum: - agent - workflow - task - eval status: type: string enum: - pending - running - waiting - completed - failed - cancelled owner: type: object properties: kind: type: string enum: - conversation - project id: type: string format: uuid required: - kind - id additionalProperties: false project_id: type: - string - 'null' format: uuid description: >- The project the run belongs to. Null only for platform runs outside a project. With conversation_id, replaces owner. conversation_id: type: - string - 'null' format: uuid message_id: type: - string - 'null' format: uuid usage: type: - object - 'null' properties: requests: type: integer minimum: 0 description: >- Deprecated. Keeps the legacy usage row count (the aggregate rows, or the per-call rows when there is no aggregate row); use model_calls for the billed provider call count. model_calls: type: - integer - 'null' minimum: 0 description: >- Billed provider calls. Null for legacy runs that have only an aggregate usage row, and null in a subtree sum whenever any included run has a null count. input_tokens: type: integer minimum: 0 output_tokens: type: integer minimum: 0 cache_creation_input_tokens: type: integer minimum: 0 cache_read_input_tokens: type: integer minimum: 0 reasoning_tokens: type: integer minimum: 0 total_tokens: type: integer minimum: 0 description: >- input_tokens + output_tokens + cache_creation_input_tokens + cache_read_input_tokens. cost_credits: anyOf: - type: string - type: number - type: 'null' required: - requests - model_calls - input_tokens - output_tokens - cache_creation_input_tokens - cache_read_input_tokens - reasoning_tokens - total_tokens - cost_credits description: >- AI usage summed over the billed provider calls; token totals may undercount calls whose provider usage was not captured. tool_error_count: type: integer minimum: 0 children_failed: type: boolean parent_run_id: type: - string - 'null' minLength: 1 root_run_id: type: string minLength: 1 waiting_reason: type: - string - 'null' enum: - tool - approval - event - input - child_run - manual_pause - null waiting_on: type: - array - 'null' items: type: object properties: kind: type: string enum: - run run_id: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9_-]+$ correlation: type: object properties: kind: type: string enum: - tool_call - workflow_node id: type: string minLength: 1 maxLength: 255 required: - kind - id additionalProperties: false description: >- The tool call or workflow node that started the run this run waits on. required: - kind - run_id - correlation additionalProperties: false description: A run this run waits on. description: >- Active dependencies while waiting_reason is child_run: every listed run must finish before this run continues. Null otherwise, including runs that waited before this field existed. waiting: type: - object - 'null' properties: reason: type: string enum: - tool - approval - event - input - child_run - manual_pause 'on': type: array items: type: object properties: kind: type: string enum: - run run_id: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9_-]+$ correlation: type: object properties: kind: type: string enum: - tool_call - workflow_node id: type: string minLength: 1 maxLength: 255 required: - kind - id additionalProperties: false description: >- The tool call or workflow node that started the run this run waits on. required: - kind - run_id - correlation additionalProperties: false description: A run this run waits on. description: >- The runs this run waits on while reason is child_run; empty otherwise. pending_approvals: type: array items: type: string minLength: 1 maxLength: 256 maxItems: 100 description: >- Workflow approval node IDs accepted by POST /runs/{run_id}/resume as node_id. Empty for other waits. resume_at: type: - string - 'null' format: date-time description: >- When a waiting workflow run resumes on its own (a delay or a timeout); null when nothing is scheduled. required: - reason - 'on' - pending_approvals - resume_at additionalProperties: false description: >- Why the run is waiting. Null unless status is waiting. Replaces waiting_reason and waiting_on. metadata: {} cancellation: type: - object - 'null' properties: requested_at: type: string description: When the cancel was requested. stopped_at: type: - string - 'null' description: >- When the runtime confirmed that execution stopped. Null means the stop is unconfirmed, not that the run is still executing. required: - requested_at - stopped_at description: >- Set once the run was cancelled through `POST /runs/{run_id}/cancel`; null otherwise. pause: type: - object - 'null' properties: requested_at: type: string description: When the pause was requested. required: - requested_at additionalProperties: false description: >- Set while a pause requested through `POST /runs/{run_id}/pause` governs the run: requested on a pending or running run, or confirmed as its manual_pause wait. Null otherwise. control: type: object properties: pause: $ref: '#/components/schemas/RunPause' waiting: $ref: '#/components/schemas/RunWait' title: type: - string - 'null' description: >- The custom title set at creation with request.name; null when none was set. target: type: - string - 'null' workflow_id: type: - string - 'null' schedule_id: type: - string - 'null' format: uuid batch_id: type: - string - 'null' format: uuid runtime_target_kind: type: - string - 'null' enum: - main_branch - environment - preview_branch - null runtime_target_environment_id: type: - string - 'null' format: uuid runtime_target_branch_id: type: - string - 'null' format: uuid input: {} config: {} output: description: >- The final output of a completed run. Its JSON serialization is at most 1,048,576 bytes (1 MiB) of UTF-8. A larger output is never stored or truncated: the run fails with error.code OUTPUT_TOO_LARGE and output null. error: type: - object - 'null' properties: message: type: string code: type: string required: - message description: >- Why the run failed. OUTPUT_TOO_LARGE carries detail { size_bytes, limit_bytes }, and its message names both sizes. logs: type: - string - 'null' artifacts: type: array items: {} duration_ms: type: - integer - 'null' exit_code: type: - integer - 'null' start_mode: type: - string - 'null' timeout_seconds: type: - integer - 'null' description: >- Task runs only; null for other kinds. The execution deadline for the whole task run, in seconds, measured from its first started_at and spanning every attempt. At the deadline the runtime aborts ctx.signal and the run fails with error.code RUN_TIMEOUT. Task code that ignores ctx.signal can keep running inside the runtime process. Default 300; task:eval defaults to 7200. backoff_limit: type: - integer - 'null' description: >- Task runs only; null for other kinds. How many times a failed task run is retried, with exponential backoff, before it fails: at most backoff_limit + 1 attempts. Only two failures are retried: the runtime never started the task (connection refused, or HTTP 503 with the runtime RUNTIME_SHUTTING_DOWN admission refusal), or the task threw the framework RetryableError. Every other failure, and any retry whose backoff would pass the timeout_seconds deadline, fails the run at once. Default 3; task:eval defaults to 0. input_schema_sha256: type: - string - 'null' pattern: ^[0-9a-f]{64}$ description: >- Lowercase sha256 hex of the canonical JSON Schema of the declared input schema this run ran against. Null when none is declared or the run predates schema identities. output_schema_sha256: type: - string - 'null' pattern: ^[0-9a-f]{64}$ description: >- Lowercase sha256 hex of the canonical JSON Schema of the declared output schema this run ran against. Null when none is declared or the run predates schema identities. input_schema_hash: type: - string - 'null' pattern: ^sha256:[0-9a-f]{64}$ description: >- The declared input schema this run ran against, as sha256:. Replaces input_schema_sha256. output_schema_hash: type: - string - 'null' pattern: ^sha256:[0-9a-f]{64}$ description: >- The declared output schema this run ran against, as sha256:. Replaces output_schema_sha256. trigger: type: - object - 'null' properties: kind: type: string enum: - manual - schedule - webhook - api id: type: - string - 'null' description: >- The schedule, webhook or API key that fired the run, when there is one. principal: type: object properties: kind: type: string enum: - system - user - api_key - service_account id: type: string required: - kind - id additionalProperties: false description: Who started the run. required: - kind - id - principal additionalProperties: false description: >- How and by whom the run was started. Null for runs recorded without a trigger principal. Replaces trigger_kind, trigger_id and trigger_principal_*. trigger_kind: type: - string - 'null' enum: - manual - schedule - webhook - api - null trigger_id: type: - string - 'null' trigger_principal_type: type: - string - 'null' enum: - system - user - api_key - service_account - null trigger_principal_id: type: - string - 'null' created_by: type: - string - 'null' minLength: 1 maxLength: 255 updated_at: type: string created_at: type: string started_at: type: - string - 'null' completed_at: type: - string - 'null' required: - run_id - id - kind - status - owner - project_id - conversation_id - message_id - usage - tool_error_count - children_failed - parent_run_id - root_run_id - waiting_reason - waiting_on - waiting - cancellation - pause - title - target - workflow_id - schedule_id - batch_id - runtime_target_kind - runtime_target_environment_id - runtime_target_branch_id - error - logs - artifacts - duration_ms - exit_code - start_mode - timeout_seconds - backoff_limit - input_schema_sha256 - output_schema_sha256 - input_schema_hash - output_schema_hash - trigger - trigger_kind - trigger_id - created_by - updated_at - created_at - started_at - completed_at required: - cancelled - run '400': description: Bad request content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': description: Forbidden content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '404': description: Not found content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '409': description: Conflict content: application/problem+json: schema: $ref: '#/components/schemas/Problem' components: schemas: RunPause: type: object properties: requested_at: type: string format: date-time required: - requested_at additionalProperties: false description: >- When a pause was requested; control.waiting confirms when execution is paused. RunWait: oneOf: - type: object properties: resume_at: type: string format: date-time reason: type: string enum: - manual_pause required: - reason - type: object properties: resume_at: type: string format: date-time reason: type: string enum: - tool_result tool_call_id: type: string minLength: 1 maxLength: 128 required: - reason - tool_call_id - type: object properties: resume_at: type: string format: date-time reason: type: string enum: - integration_connected integration: type: string minLength: 1 maxLength: 128 required: - reason - integration - type: object properties: resume_at: type: string format: date-time reason: type: string enum: - approval wait_id: type: string minLength: 1 maxLength: 128 node_ids: type: array items: type: string minLength: 1 maxLength: 128 minItems: 1 required: - reason - wait_id - node_ids - type: object properties: resume_at: type: string format: date-time reason: type: string enum: - event wait_id: type: string minLength: 1 maxLength: 128 name: type: string minLength: 1 maxLength: 128 required: - reason - wait_id - name - type: object properties: resume_at: type: string format: date-time reason: type: string enum: - input_request input_request_ids: type: array items: type: string format: uuid minItems: 1 required: - reason - input_request_ids - type: object properties: resume_at: type: string format: date-time reason: type: string enum: - child_run dependencies: type: array items: type: object properties: run_id: type: string format: uuid correlation: oneOf: - type: object properties: type: type: string enum: - tool_call id: type: string minLength: 1 maxLength: 128 required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - workflow_node id: type: string minLength: 1 maxLength: 128 required: - type - id additionalProperties: false required: - run_id - correlation additionalProperties: false minItems: 1 required: - reason - dependencies - type: object properties: resume_at: type: string format: date-time reason: type: string enum: - timer required: - resume_at - reason description: >- The current durable wait, with only the fields required to satisfy that wait. Problem: type: object properties: idempotency: type: object properties: state: type: string enum: - in_progress - payload_mismatch - outcome_unknown operation: type: string minLength: 1 retryable: type: boolean retry_after_seconds: type: - integer - 'null' minimum: 0 expires_at: type: - string - 'null' recovery: type: object properties: available: type: boolean description: type: string resource_url: type: string required: - available - description required: - state - operation - retryable - retry_after_seconds - expires_at description: Replay status, retry timing, and recovery lookup. type: type: string description: URI reference identifying the problem type example: https://api.veryfront.com/errors/validation-failed title: type: string description: Short human-readable summary of the problem example: Validation Failed status: type: integer minimum: 100 maximum: 599 description: HTTP status code example: 400 code: type: string description: Stable machine-readable error code example: RUN_INVALID_INPUT detail: type: string description: Human-readable explanation specific to this occurrence example: The 'email' field must be a valid email address instance: type: string description: URI reference identifying the specific occurrence example: /projects/my-project/members slug: type: string description: Stable identifier for the problem type example: validation-failed category: type: string enum: - AUTH - RESOURCE - VALIDATION - DATABASE - SUBSCRIPTION - INTEGRATION - INTERNAL description: API error category example: VALIDATION suggestion: type: string description: Suggested action to resolve the problem example: >- Check the request body and query parameters against the API documentation. errors: type: array items: type: object properties: field: type: string description: Field path that caused the error example: email message: type: string description: Error message for this field example: Invalid email format code: type: string description: Error code for this field example: INVALID_FORMAT required: - field - message description: Detailed field-level errors for validation failures required: - type - title - status securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT or API Key description: >- Use a JWT bearer token or a Veryfront API key in the `Authorization` header. apiKeyAuth: type: apiKey in: header name: X-API-Key description: Alternative API key header for `vf__` tokens. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.