> ## 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. # Create run > Creates a run for the specified owner and returns the accepted run details. ## OpenAPI ````yaml /cloud/rest/openapi.json post /runs 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: post: tags: - Runs summary: Create run description: >- Creates a run for the specified owner and returns the accepted run details. operationId: createRun requestBody: required: true content: application/json: schema: anyOf: - oneOf: - type: object properties: public_id: type: string minLength: 1 maxLength: 128 parent_run_id: type: string minLength: 1 maxLength: 128 trigger: type: object properties: conversation_id: type: string format: uuid message_id: type: string format: uuid tool_call_id: type: string minLength: 1 maxLength: 128 additionalProperties: false kind: type: string enum: - agent owner: anyOf: - type: object properties: kind: type: string enum: - conversation id: type: string format: uuid required: - kind - id additionalProperties: false - type: object properties: kind: type: string enum: - project id: type: string format: uuid required: - kind - id additionalProperties: false composing_user_id: type: string format: uuid description: >- Account that composed a conversation-owned agent run. The API rejects the run if the authenticated account changed before creation. conversation_mode: type: string enum: - create_new - existing - none default: none description: >- Conversation behaviour for an agent target. Defaults to none. Use create_new for an agent that delegates with invoke_agent - a run with no conversation cannot be paused for delegation. conversation_id: type: string format: uuid description: >- Existing conversation to continue. Only allowed when conversation_mode is existing, and required in that case. request: anyOf: - type: object properties: mode: type: string enum: - agent name: type: string minLength: 1 maxLength: 255 description: >- Human-readable run name, returned as the run's title. Surrounding whitespace is trimmed. Without it, the run has no title. agent_id: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9_-]+$ implementation_kind: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z0-9_-]+$ worker_key: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9_.:-]+$ initial_status: type: string enum: - pending - running source_target_kind: type: - string - 'null' enum: - project - main_branch - environment - preview_branch - release - null source_target_environment_id: type: - string - 'null' format: uuid source_target_branch_id: type: - string - 'null' format: uuid source_target_release_version: type: - string - 'null' minLength: 1 maxLength: 128 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 required: - mode - agent_id - implementation_kind additionalProperties: false title: RuntimeAgentRequest - type: object properties: mode: type: string enum: - agent name: type: string minLength: 1 maxLength: 255 description: >- Human-readable run name, returned as the run's title. Surrounding whitespace is trimmed. Without it, the run has no title. agent_id: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9_-]+$ initial_status: type: string enum: - pending - running source_target_kind: type: - string - 'null' enum: - project - main_branch - environment - preview_branch - release - null source_target_environment_id: type: - string - 'null' format: uuid source_target_branch_id: type: - string - 'null' format: uuid source_target_release_version: type: - string - 'null' minLength: 1 maxLength: 128 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: type: object properties: messages: type: array items: type: object properties: {} tools: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z][a-zA-Z0-9._:-]*$ description: type: string maxLength: 1024 parameters: type: object additionalProperties: {} inputSchema: type: object additionalProperties: {} outputSchema: type: object additionalProperties: {} required: - name maxItems: 50 context: type: object properties: conversation_id: type: string format: uuid project_id: type: - string - 'null' format: uuid project_reference: type: - string - 'null' minLength: 1 branch_id: type: - string - 'null' format: uuid environment_context: type: string required: - project_id - branch_id additionalProperties: false model: type: string active_chat_id: type: string allow_delegation: type: boolean forwarded_props: type: object additionalProperties: {} runtime_overrides: type: object properties: allowed_tools: type: array items: type: string minLength: 1 maxItems: 100 thinking: anyOf: - type: boolean enum: - false - type: integer exclusiveMinimum: 0 max_steps: type: integer exclusiveMinimum: 0 additionalProperties: false durable_root_run: type: object properties: run_id: type: string minLength: 1 maxLength: 128 message_id: type: string format: uuid required: - run_id - message_id additionalProperties: false required: - messages - context additionalProperties: false required: - mode - agent_id additionalProperties: false title: HostedDefaultChatAgentRequest - type: object properties: mode: type: string enum: - agent name: type: string minLength: 1 maxLength: 255 description: >- Human-readable run name, returned as the run's title. Surrounding whitespace is trimmed. Without it, the run has no title. input: type: object properties: agent_id: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9_-]+$ task_id: type: string minLength: 1 maxLength: 200 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._:-]*$ source_target_kind: type: string enum: - project - main_branch - environment - preview_branch allow_delegation: type: boolean default: true messages: type: array items: {} maxItems: 0 default: [] tools: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z][a-zA-Z0-9._:-]*$ description: type: string maxLength: 1024 parameters: type: object additionalProperties: {} inputSchema: type: object additionalProperties: {} outputSchema: type: object additionalProperties: {} required: - name maxItems: 50 default: [] context: type: array items: oneOf: - type: object properties: type: type: string enum: - text title: type: string maxLength: 256 text: type: string maxLength: 16384 required: - type - text - type: object properties: type: type: string enum: - json title: type: string maxLength: 256 data: type: object additionalProperties: {} required: - type - data - type: object properties: type: type: string enum: - resource title: type: string maxLength: 256 uri: type: string maxLength: 2048 mimeType: type: string maxLength: 256 text: type: string maxLength: 16384 required: - type - uri maxItems: 10 default: [] forwarded_props: type: object additionalProperties: {} runtime_target_kind: type: - string - 'null' enum: - main_branch - environment - preview_branch - null target_environment_id: type: - string - 'null' format: uuid target_branch_id: type: - string - 'null' format: uuid required: - agent_id additionalProperties: false timeout_seconds: type: integer exclusiveMinimum: 0 required: - mode - input additionalProperties: false title: ProjectAgentStreamAgentRequest required: - kind - owner - request additionalProperties: false title: agent - type: object properties: public_id: type: string minLength: 1 maxLength: 128 parent_run_id: type: string minLength: 1 maxLength: 128 trigger: type: object properties: conversation_id: type: string format: uuid message_id: type: string format: uuid tool_call_id: type: string minLength: 1 maxLength: 128 additionalProperties: false kind: type: string enum: - workflow owner: type: object properties: kind: type: string enum: - project id: type: string format: uuid required: - kind - id additionalProperties: false request: type: object properties: name: type: string minLength: 1 maxLength: 255 description: >- Human-readable run name, returned as the run's title. Surrounding whitespace is trimmed. Without it, the run has no title. workflow_id: type: string minLength: 1 maxLength: 255 target: type: string minLength: 1 maxLength: 512 pattern: ^workflow:\S+$ description: >- The workflow to run, as 'workflow:' (for example 'workflow:classify-ticket-flow'). runtime_target_kind: type: string enum: - main_branch - environment - preview_branch runtime_target_environment_id: type: - string - 'null' format: uuid runtime_target_branch_id: type: - string - 'null' format: uuid input: description: >- Business input for the run: any JSON value (object, array, string, number, boolean or null). Stored as run.input and passed to the runtime unchanged. null counts as no input, the same as leaving the field out. Tasks read it as ctx.input; when a task run has no input, ctx.input falls back to config. start_mode: type: string minLength: 1 maxLength: 64 required: - workflow_id - target additionalProperties: false required: - kind - owner - request additionalProperties: false title: workflow - type: object properties: public_id: type: string minLength: 1 maxLength: 128 parent_run_id: type: string minLength: 1 maxLength: 128 trigger: type: object properties: conversation_id: type: string format: uuid message_id: type: string format: uuid tool_call_id: type: string minLength: 1 maxLength: 128 additionalProperties: false kind: type: string enum: - task owner: type: object properties: kind: type: string enum: - project id: type: string format: uuid required: - kind - id additionalProperties: false request: type: object properties: name: type: string minLength: 1 maxLength: 255 description: >- Human-readable run name, returned as the run's title. Surrounding whitespace is trimmed. Without it, the run has no title. target: type: string minLength: 1 maxLength: 512 pattern: ^task:\S+$ description: >- The task to run, as 'task:' (for example 'task:echo-input'). batch_id: type: string format: uuid description: Batch UUID to group related task runs. runtime_target_kind: type: string enum: - main_branch - environment - preview_branch runtime_target_environment_id: type: - string - 'null' format: uuid runtime_target_branch_id: type: - string - 'null' format: uuid input: description: >- Business input for the run: any JSON value (object, array, string, number, boolean or null). Stored as run.input and passed to the runtime unchanged. null counts as no input, the same as leaving the field out. Tasks read it as ctx.input; when a task run has no input, ctx.input falls back to config. config: type: object additionalProperties: {} description: >- Execution settings. The task reads them as ctx.config. timeout_seconds: type: integer exclusiveMinimum: 0 description: >- 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 minimum: 0 description: >- 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. required: - target additionalProperties: false required: - kind - owner - request additionalProperties: false title: task - type: object properties: public_id: type: string minLength: 1 maxLength: 128 parent_run_id: type: string minLength: 1 maxLength: 128 trigger: type: object properties: conversation_id: type: string format: uuid message_id: type: string format: uuid tool_call_id: type: string minLength: 1 maxLength: 128 additionalProperties: false kind: type: string enum: - eval owner: type: object properties: kind: type: string enum: - project id: type: string format: uuid required: - kind - id additionalProperties: false request: type: object properties: name: type: string minLength: 1 maxLength: 255 description: >- Human-readable run name, returned as the run's title. Surrounding whitespace is trimmed. Without it, the run has no title. target: type: string minLength: 1 maxLength: 512 runtime_target_kind: type: string enum: - main_branch - environment - preview_branch runtime_target_environment_id: type: - string - 'null' format: uuid runtime_target_branch_id: type: - string - 'null' format: uuid input: description: >- Eval run input: any JSON value (object, array, string, number, boolean or null). config: type: object additionalProperties: {} start_mode: type: string minLength: 1 maxLength: 64 required: - target additionalProperties: false required: - kind - owner - request additionalProperties: false title: eval responses: '202': description: Run accepted content: application/json: schema: type: object properties: accepted: type: boolean duplicate: 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 conversation_id: type: - string - 'null' format: uuid message_id: type: - string - 'null' format: uuid required: - accepted - run 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. 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.