> ## 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 > Create a run. ## 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 | Domain | Use it to | | --- | --- | | [Projects](#tag/projects) | Manage projects and files. | | [Agents](#tag/agents) | Manage agent primitives. | | [Orchestration](#tag/execution) | Manage conversations and runs. | | [Evaluations](#tag/evaluations) | Manage evaluations and results. | | [AI Gateway](#tag/ai-gateway) | Access models and inference. | | [MCP](#tag/mcp) | Discover tools and authorization. | | [Integrations](#tag/integrations) | Manage connections and integrations. | | [Knowledge](#tag/knowledge) | Manage documents and search. | | [Deployments](#tag/deployments) | Manage releases and deployments. | | [Runtime](#tag/runtime) | Manage environments and infrastructure. | | [Observability](#tag/observability) | Monitor activity and performance. | | [Identity & Access](#tag/identity-access) | Manage identity and access. | | [Billing & Usage](#tag/billing-usage) | Manage billing and usage. | | [Other](#tag/platform) | Inspect health and API 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: projects description: Manage projects and files. - name: agents description: Manage agent primitives. - name: execution description: Manage conversations and runs. - name: evaluations description: Manage evaluations and results. - name: ai-gateway description: Access models and inference. - name: mcp description: Discover tools and authorization. - name: integrations description: Manage connections and integrations. - name: knowledge description: Manage documents and search. - name: deployments description: Manage releases and deployments. - name: runtime description: Manage environments and infrastructure. - name: observability description: Monitor activity and performance. - name: identity-access description: Manage identity and access. - name: billing-usage description: Manage billing and usage. - name: platform description: Inspect health and API metadata. - name: projects/Projects - name: projects/Projects/Favorites - name: projects/Projects/Account Projects - name: projects/Projects/Projects - name: projects/Projects/Project Labels - name: projects/Projects/Project templates - name: projects/Files - name: projects/Files/Files - name: projects/Files/File Chunks - name: projects/Files/Branch File Versions - name: projects/Files/Branch Files - name: projects/Files/Environment Files - name: projects/Files/File Versions - name: projects/Files/Branch File Drafts - name: projects/Files/Release Files - name: projects/Files/Sandbox Files - name: projects/Files/File Search - name: projects/Branches - name: projects/Branches/Branches - name: projects/Branches/Branch Policies - name: projects/Branches/Branch Approvals - name: projects/Branches/Branch Status Checks - name: projects/Branches/Project Commits - name: projects/Branches/Branch Merges - name: projects/Uploads - name: projects/Uploads/Upload Folders - name: projects/Uploads/Upload Grants - name: projects/Uploads/Project Uploads - name: projects/Uploads/Upload Visibility - name: agents/Agents - name: agents/Agents/Agents - name: agents/Agents/Agent Labels - name: agents/Agents/Agent templates - name: agents/Agents/Agent Tool References - name: agents/Agents/Agent Avatars - name: agents/Agents/Agent Capabilities - name: agents/Agents/Agent Installation - name: agents/Prompts - name: agents/Prompts/Project prompts - name: agents/Tools - name: agents/Tools/Project tools - name: agents/Skills - name: agents/Skills/Project skills - name: agents/Resources - name: agents/Resources/Project resources - name: agents/Tasks - name: agents/Tasks/Tasks - name: agents/Workflows - name: agents/Workflows/Workflows - name: execution/Conversations - name: execution/Conversations/Conversations - name: execution/Conversations/Conversation messages - name: execution/Conversations/Conversation participants - name: execution/Conversations/Conversation read state - name: execution/Triggers - name: execution/Triggers/Project schedules - name: execution/Triggers/Webhooks - name: execution/Triggers/Webhook events - name: execution/Runs - name: execution/Runs/Run Input Requests - name: execution/Runs/Runs - name: execution/Runs/Runtime - name: execution/Runs/Child Runs - name: execution/Runs/Conversation Runs - name: execution/Runs/Project Runs - name: execution/Runs/Webhook Runs - name: execution/Runs/Run Events - name: execution/Runs/Run Actions - name: execution/Runs/Run Artifacts - name: execution/Executors - name: execution/Executors/Connected agents - name: execution/Executors/Agent workers - name: evaluations/Evaluations - name: evaluations/Evaluations/Evaluations - name: evaluations/Evaluations/Evaluation Runs - name: ai-gateway/Models - name: ai-gateway/Models/Model discovery - name: ai-gateway/Models/Inference Models - name: ai-gateway/Models/Project inference policy - name: ai-gateway/Models/Account inference policy - name: ai-gateway/Inference - name: ai-gateway/Inference/OpenAI Chat Completions - name: ai-gateway/Inference/Embeddings - name: ai-gateway/Inference/OpenAI Responses - name: ai-gateway/Inference/Proxy metadata - name: ai-gateway/Inference/Anthropic Messages - name: ai-gateway/Inference/Provider gateway - name: ai-gateway/Inference/Gemini inference - name: ai-gateway/Inference/Image generation - name: mcp/Tools - name: mcp/Tools/MCP discovery - name: mcp/Authorization - name: mcp/Authorization/Protected resource discovery - name: integrations/Integrations - name: integrations/Integrations/Integration tools - name: integrations/Integrations/Integration catalog - name: integrations/Integrations/Project integrations - name: integrations/Connections - name: integrations/Connections/Connections - name: integrations/Channels - name: integrations/Channels/Channels - name: integrations/Channels/Setup lookups - name: integrations/External storage - name: integrations/External storage/External Files - name: knowledge/Documents - name: knowledge/Documents/Project knowledge - name: knowledge/Documents/Retrieval documents - name: knowledge/Search - name: knowledge/Search/Search - name: knowledge/Embeddings - name: knowledge/Embeddings/Project embeddings - name: deployments/Releases - name: deployments/Releases/Releases - name: deployments/Releases/Release Versions - name: deployments/Releases/Release Source Manifests - name: deployments/Deployments - name: deployments/Deployments/Project deployments - name: deployments/Artifacts - name: deployments/Artifacts/Dependencies - name: deployments/Artifacts/Release Asset Manifests - name: deployments/Artifacts/Style artifacts - name: runtime/Environments - name: runtime/Environments/Environments - name: runtime/Environments/Environment Domains - name: runtime/Environments/Environment variables - name: runtime/Environments/Project Domains - name: runtime/Environments/Environment Variable Keys - name: runtime/Servers - name: runtime/Servers/Environment Servers - name: runtime/Servers/Project servers - name: runtime/Sandboxes - name: runtime/Sandboxes/Sandbox Lifecycle - name: runtime/Sandboxes/Sandbox Commands - name: runtime/Sandboxes/Sandbox Environment - name: runtime/Sandboxes/Sandbox Health - name: runtime/Sandboxes/Sandbox Terminal - name: runtime/Cache - name: runtime/Cache/Project Cache - name: runtime/Cache/User Cache - name: observability/Logs - name: observability/Logs/Log entries - name: observability/Traces - name: observability/Traces/Trace spans - name: observability/Traces/Project traces - name: observability/Traces/Trace Search - name: observability/Metrics - name: observability/Metrics/Metric series - name: observability/Alerts - name: observability/Alerts/Project alerts - name: observability/Error types - name: observability/Error types/Error types - name: identity-access/Users - name: identity-access/Users/Account users - name: identity-access/Users/Project users - name: identity-access/Users/Current user - name: identity-access/Accounts - name: identity-access/Accounts/Accounts - name: identity-access/Invitations - name: identity-access/Invitations/Invitations - name: identity-access/Permissions - name: identity-access/Permissions/Feature gates - name: identity-access/Permissions/Project Ownership - name: identity-access/API keys - name: identity-access/API keys/API keys - name: identity-access/Authentication - name: identity-access/Authentication/Sign-in - name: identity-access/Authentication/Tokens - name: identity-access/Authorization - name: identity-access/Authorization/Authorized apps - name: identity-access/Authorization/General OAuth - name: identity-access/Authorization/Consent - name: billing-usage/Subscriptions - name: billing-usage/Subscriptions/Subscriptions - name: billing-usage/Subscriptions/Seats - name: billing-usage/Billing - name: billing-usage/Billing/Invoices - name: billing-usage/Billing/Payments - name: billing-usage/Billing/Payment Methods - name: billing-usage/Billing/Billing Details - name: billing-usage/Billing/Account billing - name: billing-usage/Credits - name: billing-usage/Credits/Credits - name: billing-usage/Budgets - name: billing-usage/Budgets/Budgets - name: billing-usage/Usage - name: billing-usage/Usage/API key usage - name: billing-usage/Usage/Account usage - name: billing-usage/Usage/Project usage - name: billing-usage/Analytics - name: billing-usage/Analytics/Conversation Analytics - name: billing-usage/Analytics/Run Analytics - name: platform/Other - name: platform/Other/API metadata paths: /runs: post: tags: - execution/Runs/Runs summary: Create run description: Create a run. operationId: createRun parameters: - schema: type: string minLength: 1 maxLength: 128 required: true name: Idempotency-Key in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRunRequest' examples: minimal: summary: Minimal request value: project_id: 00000000-0000-4000-8000-000000000001 target: type: task id: health-check agent: summary: API-started agent value: project_id: 00000000-0000-4000-8000-000000000001 target: type: agent id: coordinator input: message: Research the topic and summarize it. task: summary: Task run value: project_id: 00000000-0000-4000-8000-000000000001 target: type: task id: summarize input: text: A short document. workflow: summary: Workflow run value: project_id: 00000000-0000-4000-8000-000000000001 target: type: workflow id: review input: document_id: document_example child: summary: Child run value: project_id: 00000000-0000-4000-8000-000000000001 target: type: agent id: research input: question: Find relevant sources. parent_run_id: 22222222-2222-4222-8222-222222222222 tool_call_id: call_invoke_agent workflow_child: summary: Workflow starts an agent value: project_id: 00000000-0000-4000-8000-000000000001 target: type: agent id: coordinator input: topic: Energy storage parent_run_id: 11111111-1111-4111-8111-111111111111 node_id: research evaluation: summary: Evaluation run value: project_id: 00000000-0000-4000-8000-000000000001 target: type: task id: eval config: eval_id: eval_example relationships: summary: Conversation and batch value: project_id: 00000000-0000-4000-8000-000000000001 target: type: agent id: support input: message: Summarize this document. conversation_id: 00000000-0000-4000-8000-000000000002 batch_id: 00000000-0000-4000-8000-000000000003 runtime: summary: Registered runtime value: project_id: 00000000-0000-4000-8000-000000000001 target: type: task id: summarize input: text: A short document. execution: runtime: type: registered id: runtime_example schedule: summary: Saved schedule value: project_id: 00000000-0000-4000-8000-000000000001 source: type: schedule id: 00000000-0000-4000-8000-000000000002 webhook: summary: Webhook run value: project_id: 00000000-0000-4000-8000-000000000001 input: event: document_uploaded source: type: webhook id: webhook_example agent_configuration: summary: Agent with client tools and model configuration value: project_id: 00000000-0000-4000-8000-000000000001 target: type: agent id: researcher input: Research the topic and summarize it. config: conversation_mode: create_new tools: - name: read_document description: Reads a document. parameters: type: object properties: id: type: string required: - id context: - type: text text: Use the provided document. forwarded_props: model: provider/model responses: '202': description: >- Run admitted. Project-owned runs need project.runs.write; conversation-owned runs need editor access on the conversation. headers: Location: schema: type: string format: uri-reference content: application/json: schema: $ref: '#/components/schemas/CreateRunResult' examples: minimal: summary: Minimal request value: id: 11111111-1111-4111-8111-111111111111 status: pending project_id: 00000000-0000-4000-8000-000000000001 target: type: task id: health-check input: null output: null created_at: '2026-10-02T10:00:00Z' updated_at: '2026-10-02T10:00:02Z' trigger: type: api_key id: key_example agent: summary: API-started agent value: id: 22222222-2222-4222-8222-222222222222 status: pending project_id: 00000000-0000-4000-8000-000000000001 target: type: agent id: coordinator input: message: Research the topic and summarize it. output: null created_at: '2026-10-02T10:00:00Z' updated_at: '2026-10-02T10:00:02Z' trigger: type: api_key id: key_example task: summary: Task run value: id: 11111111-1111-4111-8111-111111111111 status: pending project_id: 00000000-0000-4000-8000-000000000001 target: type: task id: summarize input: text: A short document. output: null created_at: '2026-10-02T10:00:00Z' updated_at: '2026-10-02T10:00:02Z' trigger: type: api_key id: key_example workflow: summary: Workflow run value: id: 11111111-1111-4111-8111-111111111111 status: pending project_id: 00000000-0000-4000-8000-000000000001 target: type: workflow id: review input: document_id: document_example output: null created_at: '2026-10-02T10:00:00Z' updated_at: '2026-10-02T10:00:02Z' trigger: type: api_key id: key_example child: summary: Child run value: id: 33333333-3333-4333-8333-333333333333 status: pending project_id: 00000000-0000-4000-8000-000000000001 target: type: agent id: research input: question: Find relevant sources. output: null parent_run_id: 22222222-2222-4222-8222-222222222222 root_run_id: 22222222-2222-4222-8222-222222222222 created_at: '2026-10-02T10:00:01Z' updated_at: '2026-10-02T10:00:01Z' trigger: type: agent id: coordinator tool_call_id: call_invoke_agent workflow_child: summary: Workflow starts an agent value: id: 33333333-3333-4333-8333-333333333333 status: pending project_id: 00000000-0000-4000-8000-000000000001 target: type: agent id: coordinator input: topic: Energy storage output: null parent_run_id: 11111111-1111-4111-8111-111111111111 root_run_id: 11111111-1111-4111-8111-111111111111 created_at: '2026-10-02T10:00:01Z' updated_at: '2026-10-02T10:00:01Z' trigger: type: workflow id: daily-brief node_id: research evaluation: summary: Evaluation run value: id: 11111111-1111-4111-8111-111111111111 status: pending project_id: 00000000-0000-4000-8000-000000000001 target: type: task id: eval input: null output: null created_at: '2026-10-02T10:00:00Z' updated_at: '2026-10-02T10:00:02Z' trigger: type: api_key id: key_example config: eval_id: eval_example relationships: summary: Conversation and batch value: id: 11111111-1111-4111-8111-111111111111 status: pending project_id: 00000000-0000-4000-8000-000000000001 target: type: agent id: support input: message: Summarize this document. output: null created_at: '2026-10-02T10:00:00Z' updated_at: '2026-10-02T10:00:02Z' trigger: type: api_key id: key_example conversation_id: 00000000-0000-4000-8000-000000000002 batch_id: 00000000-0000-4000-8000-000000000003 runtime: summary: Registered runtime value: id: 11111111-1111-4111-8111-111111111111 status: pending project_id: 00000000-0000-4000-8000-000000000001 target: type: task id: summarize input: text: A short document. output: null created_at: '2026-10-02T10:00:00Z' updated_at: '2026-10-02T10:00:02Z' trigger: type: api_key id: key_example execution: runtime: type: registered id: runtime_example schedule: summary: Saved schedule value: id: 11111111-1111-4111-8111-111111111111 status: pending project_id: 00000000-0000-4000-8000-000000000001 target: type: task id: summarize input: null output: null created_at: '2026-10-02T10:00:00Z' updated_at: '2026-10-02T10:00:02Z' trigger: type: api_key id: key_example webhook: summary: Webhook run value: id: 11111111-1111-4111-8111-111111111111 status: pending project_id: 00000000-0000-4000-8000-000000000001 target: type: task id: summarize input: event: document_uploaded output: null created_at: '2026-10-02T10:00:00Z' updated_at: '2026-10-02T10:00:02Z' trigger: type: api_key id: key_example '400': description: Bad request content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/TargetRunProblem' - properties: status: const: 400 '401': description: Unauthorized content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/TargetRunProblem' - properties: status: const: 401 '403': description: Forbidden content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/TargetRunProblem' - properties: status: const: 403 '404': description: Not found content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/TargetRunProblem' - properties: status: const: 404 '409': description: Conflict content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/TargetRunProblem' - properties: status: const: 409 '413': description: Payload too large content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/TargetRunProblem' - properties: status: const: 413 '429': description: Rate limit exceeded headers: Retry-After: schema: type: integer format: int32 minimum: 1 content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/TargetRunProblem' - properties: status: const: 429 security: - bearerAuth: [] - apiKeyAuth: [] - runExecutionAuth: [] x-codeSamples: - lang: json label: Request JSON example: minimal contentType: application/json source: |- { "project_id": "00000000-0000-4000-8000-000000000001", "target": { "type": "task", "id": "health-check" } } - lang: json label: Request JSON example: agent contentType: application/json source: |- { "project_id": "00000000-0000-4000-8000-000000000001", "target": { "type": "agent", "id": "coordinator" }, "input": { "message": "Research the topic and summarize it." } } - lang: json label: Request JSON example: task contentType: application/json source: |- { "project_id": "00000000-0000-4000-8000-000000000001", "target": { "type": "task", "id": "summarize" }, "input": { "text": "A short document." } } - lang: json label: Request JSON example: workflow contentType: application/json source: |- { "project_id": "00000000-0000-4000-8000-000000000001", "target": { "type": "workflow", "id": "review" }, "input": { "document_id": "document_example" } } - lang: json label: Request JSON example: child contentType: application/json source: |- { "project_id": "00000000-0000-4000-8000-000000000001", "target": { "type": "agent", "id": "research" }, "input": { "question": "Find relevant sources." }, "parent_run_id": "22222222-2222-4222-8222-222222222222", "tool_call_id": "call_invoke_agent" } - lang: json label: Request JSON example: workflow_child contentType: application/json source: |- { "project_id": "00000000-0000-4000-8000-000000000001", "target": { "type": "agent", "id": "coordinator" }, "input": { "topic": "Energy storage" }, "parent_run_id": "11111111-1111-4111-8111-111111111111", "node_id": "research" } - lang: json label: Request JSON example: evaluation contentType: application/json source: |- { "project_id": "00000000-0000-4000-8000-000000000001", "target": { "type": "task", "id": "eval" }, "config": { "eval_id": "eval_example" } } - lang: json label: Request JSON example: relationships contentType: application/json source: |- { "project_id": "00000000-0000-4000-8000-000000000001", "target": { "type": "agent", "id": "support" }, "input": { "message": "Summarize this document." }, "conversation_id": "00000000-0000-4000-8000-000000000002", "batch_id": "00000000-0000-4000-8000-000000000003" } - lang: json label: Request JSON example: runtime contentType: application/json source: |- { "project_id": "00000000-0000-4000-8000-000000000001", "target": { "type": "task", "id": "summarize" }, "input": { "text": "A short document." }, "execution": { "runtime": { "type": "registered", "id": "runtime_example" } } } - lang: json label: Request JSON example: schedule contentType: application/json source: |- { "project_id": "00000000-0000-4000-8000-000000000001", "source": { "type": "schedule", "id": "00000000-0000-4000-8000-000000000002" } } - lang: json label: Request JSON example: webhook contentType: application/json source: |- { "project_id": "00000000-0000-4000-8000-000000000001", "input": { "event": "document_uploaded" }, "source": { "type": "webhook", "id": "webhook_example" } } - lang: json label: Request JSON example: agent_configuration contentType: application/json source: |- { "project_id": "00000000-0000-4000-8000-000000000001", "target": { "type": "agent", "id": "researcher" }, "input": "Research the topic and summarize it.", "config": { "conversation_mode": "create_new", "tools": [ { "name": "read_document", "description": "Reads a document.", "parameters": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } ], "context": [ { "type": "text", "text": "Use the provided document." } ], "forwarded_props": { "model": "provider/model" } } } components: schemas: CreateRunRequest: anyOf: - $ref: '#/components/schemas/DirectRunRequest' - $ref: '#/components/schemas/ScheduleRunRequest' - $ref: '#/components/schemas/WebhookRunRequest' description: >- Create a direct run with project_id, target:{type,id}, and optional input, or execute a saved schedule or webhook. Input is business data; configuration and execution settings are separate. CreateRunResult: anyOf: - $ref: '#/components/schemas/CreatedRun' - $ref: '#/components/schemas/RunCreationReceipt' description: >- The full created run when readable by the caller; otherwise only its admission receipt. Replay uses the same caller visibility. TargetRunProblem: type: object properties: type: type: string description: Problem type URI reference. title: type: string status: type: integer minimum: 400 maximum: 599 format: int64 code: type: string minLength: 1 maxLength: 128 cause: type: string enum: - schedule_concurrency_forbidden - schedule_fire_in_progress - schedule_run_limit_reached description: Schedule admission refusal. detail: type: string instance: type: string errors: type: array items: type: object properties: field: type: string message: type: string required: - field - message required: - type - title - status - code DirectRunRequest: type: object properties: project_id: type: string format: uuid description: >- UUID of the project containing the execution definition or saved source. title: type: string minLength: 1 maxLength: 255 description: Optional display title for the accepted run. labels: $ref: '#/components/schemas/RunLabels' target: allOf: - $ref: '#/components/schemas/RunTarget' - description: Definition executed by this run. input: description: >- Business input passed to the definition unchanged; omitted input resolves to null. config: type: object additionalProperties: description: A JSON value. description: >- Definition-specific configuration; business keys retain their spelling on every transport. Agent targets with `conversation_id` read `agent_admission` (AgentAdmissionConfig). execution: $ref: '#/components/schemas/RunExecutionOptions' parent_run_id: type: string format: uuid description: >- Canonical UUID of the authenticated runtime parent; ordinary users cannot assert parent authority. tool_call_id: type: string minLength: 1 maxLength: 128 description: >- Durable tool invocation on an agent parent; requires parent_run_id and excludes node_id. node_id: type: string minLength: 1 maxLength: 128 description: >- Started workflow node on the parent; requires parent_run_id and excludes tool_call_id. conversation_id: type: string format: uuid description: Conversation associated with an agent admission, when applicable. batch_id: type: string format: uuid description: Batch UUID associated with the accepted run. required: - project_id - target additionalProperties: false dependentRequired: tool_call_id: - parent_run_id node_id: - parent_run_id allOf: - not: required: - tool_call_id - node_id - if: properties: target: properties: type: const: agent required: - type config: required: - agent_admission required: - target - config then: required: - conversation_id - if: properties: target: properties: type: const: agent required: - type required: - target - conversation_id then: properties: config: properties: agent_admission: $ref: '#/components/schemas/AgentAdmissionConfig' ScheduleRunRequest: type: object properties: project_id: type: string format: uuid description: >- UUID of the project containing the execution definition or saved source. title: type: string minLength: 1 maxLength: 255 description: Optional display title for the accepted run. labels: $ref: '#/components/schemas/RunLabels' source: type: object properties: type: type: string enum: - schedule description: Execute a saved schedule. id: type: string format: uuid description: UUID of the saved schedule in this project. required: - type - id additionalProperties: false description: Saved schedule supplying the target and execution configuration. required: - project_id - source additionalProperties: false WebhookRunRequest: type: object properties: project_id: type: string format: uuid title: type: string minLength: 1 maxLength: 255 labels: $ref: '#/components/schemas/RunLabels' source: type: object properties: type: type: string enum: - webhook description: Saved source kind. id: type: string minLength: 1 maxLength: 128 description: Saved webhook identifier. required: - type - id additionalProperties: false description: Saved webhook to execute. input: description: A JSON value. required: - project_id - source - input additionalProperties: false CreatedRun: type: object properties: id: type: string format: uuid description: Unique run UUID. status: type: string enum: - pending - running - waiting - completed - failed - cancelled description: Current execution state. project_id: type: string format: uuid description: Project containing the run. target: $ref: '#/components/schemas/RunTarget' input: description: Business input supplied when the run was created. output: description: Final business output; null until successful finalization. error: $ref: '#/components/schemas/RunFailure' title: type: string description: Display title, omitted when unset. labels: $ref: '#/components/schemas/RunLabels' parent_run_id: type: string format: uuid description: Immediate parent run ID, present on child runs. root_run_id: type: string format: uuid description: Top-level ancestor run ID, present on child runs. created_at: type: string format: date-time description: When the run was accepted. updated_at: type: string format: date-time description: When the resource last changed, including usage updates. started_at: type: string format: date-time description: When the first execution attempt started, omitted before execution. finished_at: type: string format: date-time description: When the run completed, failed or was cancelled. config: type: object additionalProperties: description: A JSON value. description: Definition-specific execution configuration. execution: type: object properties: runtime: $ref: '#/components/schemas/RunRuntime' timeout_seconds: type: integer exclusiveMinimum: 0 description: >- Deadline for the whole run in seconds, measured from its first start and including retries. retry_limit: type: integer minimum: 0 description: >- Maximum retries after the first attempt; only retryable failures are retried. attempt: type: integer minimum: 1 description: >- Current or last execution attempt, starting at 1; absent before execution. exit_code: type: - integer - 'null' description: >- Runtime process exit code, or null when no exit code was recorded. duration_ms: type: - integer - 'null' minimum: 0 description: >- Elapsed time from first start to finish, including waits and retries; null when not finished. format: int64 tool_error_count: type: integer minimum: 0 description: Recorded failed tool invocations during this run. logs: type: string description: Captured runtime text logs, when available. start_mode: type: string description: Recorded execution start mode, when available. worker: type: object properties: id: type: string format: uuid description: Agent worker ID. name: type: string description: >- Worker display name, omitted when the worker registered without one. claimed_at: type: string format: date-time description: When the worker claimed the run. required: - id - claimed_at description: >- Agent worker that claimed and executed the run; present only on worker-executed runs. description: Resolved execution settings and diagnostics. control: type: object properties: waiting: $ref: '#/components/schemas/RunWait' pause: $ref: '#/components/schemas/RunPause' cancellation: $ref: '#/components/schemas/RunCancellation' description: Pending control requests and the current wait. task_id: type: string minLength: 1 maxLength: 200 description: Orchestration task ID, distinct from the execution definition. conversation_id: type: string format: uuid description: Conversation containing the run. input_message_id: type: string format: uuid description: Conversation message that supplied the input. output_message_id: type: string format: uuid description: Conversation message containing the result. batch_id: type: string format: uuid description: Batch containing the run. trigger: $ref: '#/components/schemas/RunTrigger' usage: $ref: '#/components/schemas/Usage' descendants: type: object properties: total: type: integer minimum: 0 description: Total descendants at every depth. active: type: integer minimum: 0 description: Descendants that are pending, running or waiting. has_failures: type: boolean description: Whether any descendant has failed. usage: allOf: - $ref: '#/components/schemas/Usage' - description: Aggregate usage of every descendant, excluding this run. x-ref-description: Aggregate usage of every descendant, excluding this run. required: - total - active - has_failures description: Counts and usage across all descendant runs, excluding this run. artifacts: type: array items: $ref: '#/components/schemas/RunArtifact' description: Files produced by the run. schemas: type: object properties: input: type: - object - 'null' properties: schema: anyOf: - type: boolean - type: object additionalProperties: description: A JSON value. description: >- JSON Schema captured for this run; object schemas and boolean schemas are supported. sha256: type: string pattern: ^[a-f0-9]{64}$ description: SHA-256 digest of the pinned schema. required: - schema - sha256 output: type: - object - 'null' properties: schema: anyOf: - type: boolean - type: object additionalProperties: description: A JSON value. description: >- JSON Schema captured for this run; object schemas and boolean schemas are supported. sha256: type: string pattern: ^[a-f0-9]{64}$ description: SHA-256 digest of the pinned schema. required: - schema - sha256 required: - input - output description: >- Pinned schemas for business input and output; null means no declared schema. metadata: type: object additionalProperties: description: A JSON value. description: Additional resource metadata. required: - id - status - project_id - target - input - output - created_at - updated_at - trigger description: A newly created run with resolved target and recorded trigger. allOf: - if: properties: status: enum: - failed required: - status then: required: - error else: not: required: - error - if: properties: status: enum: - completed - failed - cancelled required: - status then: required: - finished_at else: not: required: - finished_at - if: properties: status: enum: - pending - running - waiting - failed - cancelled required: - status then: properties: output: type: 'null' else: {} - if: properties: status: enum: - waiting required: - status then: required: - control properties: control: required: - waiting else: properties: control: not: required: - waiting - if: properties: control: required: - pause required: - control then: properties: status: enum: - pending - running - waiting - if: required: - trigger properties: trigger: properties: type: enum: - agent - task - workflow required: - type then: required: - parent_run_id - root_run_id - if: properties: status: const: completed required: - status then: properties: descendants: properties: active: const: 0 dependentRequired: parent_run_id: - root_run_id root_run_id: - parent_run_id RunCreationReceipt: type: object properties: run_id: type: string format: uuid status: type: string enum: - pending - running - waiting - completed - failed - cancelled description: Current execution state. required: - run_id - status additionalProperties: false description: >- Minimal admission receipt for a caller who cannot read the created run. No private fields are disclosed. RunLabels: type: object additionalProperties: type: string maxLength: 256 description: Labels used to organize runs. maxProperties: 50 propertyNames: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z0-9_.-]+$ x-ref-description: Labels used to organize runs. RunTarget: type: object properties: type: type: string enum: - agent - task - workflow description: Kind of execution definition. id: type: string minLength: 1 maxLength: 512 pattern: ^\S+$ description: >- Definition ID without a kind prefix, such as health-check rather than task:health-check. required: - type - id additionalProperties: false description: Resolved execution definition. x-ref-description: Resolved execution definition. RunExecutionOptions: type: object properties: runtime: allOf: - $ref: '#/components/schemas/RunRuntime' - description: >- Deployment or registered runtime override; omit to use the definition default. x-ref-description: >- Deployment or registered runtime override; omit to use the definition default. timeout_seconds: type: integer exclusiveMinimum: 0 description: >- Whole-run deadline in seconds, including retries; unsupported target overrides are refused. retry_limit: type: integer minimum: 0 description: >- Maximum retries after the first attempt, restricted to retryable failures. additionalProperties: false description: Execution overrides, separate from business input and configuration. x-ref-description: Execution overrides, separate from business input and configuration. RunFailure: type: object properties: code: type: string minLength: 1 maxLength: 128 description: Stable failure code. message: type: string minLength: 1 maxLength: 4000 description: Human-readable failure message. details: type: object additionalProperties: {} description: Additional failure details. required: - code - message additionalProperties: false description: Failure details, present only when the run failed. x-ref-description: Failure details, present only when the run failed. RunRuntime: oneOf: - type: object properties: type: type: string enum: - main_branch description: Runtime selection kind. required: - type additionalProperties: false description: Selected main-branch deployment. - type: object properties: type: type: string enum: - environment description: Runtime selection kind. id: type: string format: uuid description: Environment UUID. required: - type - id additionalProperties: false description: Selected environment. - type: object properties: type: type: string enum: - preview_branch description: Runtime selection kind. id: type: string format: uuid description: Preview branch UUID. required: - type - id additionalProperties: false description: Selected preview branch. - type: object properties: type: type: string enum: - registered description: Runtime selection kind. id: type: string minLength: 1 maxLength: 128 description: Registered runtime identifier. required: - type - id additionalProperties: false description: Selected registered runtime. description: >- Resolved logical runtime selection; main_branch identifies the selected main-branch deployment, not a worker process. x-ref-description: >- Resolved logical runtime selection; main_branch identifies the selected main-branch deployment, not a worker process. RunWait: oneOf: - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - manual_pause description: Condition required to resume the run. required: - reason description: Waiting for manual resumption. - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - tool_result description: Condition required to resume the run. tool_call_id: type: string minLength: 1 maxLength: 128 description: Tool call awaiting a result. required: - reason - tool_call_id description: Waiting for a tool result. - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - integration_connected description: Condition required to resume the run. integration: type: string minLength: 1 maxLength: 128 description: Integration awaiting connection. required: - reason - integration description: Waiting for an integration connection. - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - approval description: Condition required to resume the run. wait_id: type: string minLength: 1 maxLength: 128 description: Durable wait identifier. node_ids: type: array items: type: string minLength: 1 maxLength: 128 minItems: 1 description: Workflow nodes awaiting approval. required: - reason - wait_id - node_ids description: Waiting for workflow approval. - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - event description: Condition required to resume the run. wait_id: type: string minLength: 1 maxLength: 128 description: Durable wait identifier. name: type: string minLength: 1 maxLength: 128 description: Event required to resume. required: - reason - wait_id - name description: Waiting for a named event. - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - input_request description: Condition required to resume the run. input_request_ids: type: array items: type: string format: uuid minItems: 1 description: Input requests awaiting responses. required: - reason - input_request_ids description: Waiting for input responses. - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - child_run description: Condition required to resume the run. dependencies: type: array items: type: object properties: run_id: type: string format: uuid description: Canonical UUID of the child run. correlation: oneOf: - type: object properties: type: type: string enum: - tool_call description: Child invocation kind. id: type: string minLength: 1 maxLength: 128 description: Tool call identifier. required: - type - id additionalProperties: false description: Child started by a tool call. - type: object properties: type: type: string enum: - workflow_node description: Child invocation kind. id: type: string minLength: 1 maxLength: 128 description: Workflow node identifier. required: - type - id additionalProperties: false description: Child started by a workflow node. required: - run_id - correlation additionalProperties: false minItems: 1 description: Child runs that must finish. required: - reason - dependencies description: Waiting for child runs. - type: object properties: resume_at: type: string format: date-time description: Scheduled automatic resume time. reason: type: string enum: - timer description: Condition required to resume the run. required: - resume_at - reason description: Waiting until the scheduled resume time. description: >- The current durable wait, with only the fields required to satisfy that wait. RunPause: type: object properties: requested_at: type: string format: date-time description: Time the pause was requested. required: - requested_at additionalProperties: false description: >- When a pause was requested; control.waiting confirms when execution is paused. RunCancellation: type: object properties: requested_at: type: string format: date-time description: Time cancellation was requested. stopped_at: type: - string - 'null' format: date-time description: Time the runtime confirmed its stop; null until confirmed. required: - requested_at - stopped_at RunTrigger: oneOf: - type: object properties: type: type: string enum: - user id: type: string format: uuid required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - api_key id: type: string minLength: 1 maxLength: 128 required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - service_account id: type: string minLength: 1 maxLength: 128 required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - system id: type: string minLength: 1 maxLength: 128 required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - schedule id: type: string format: uuid required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - webhook id: type: string minLength: 1 maxLength: 128 required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - agent id: type: string minLength: 1 maxLength: 512 pattern: ^\S+$ tool_call_id: type: string minLength: 1 maxLength: 128 required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - task id: type: string minLength: 1 maxLength: 512 pattern: ^\S+$ required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - workflow id: type: string minLength: 1 maxLength: 512 pattern: ^\S+$ node_id: type: string minLength: 1 maxLength: 128 required: - type - id additionalProperties: false description: How execution was initiated. x-ref-description: How execution was initiated. Usage: type: object properties: tokens: $ref: '#/components/schemas/TokenUsage' cost: $ref: '#/components/schemas/Cost' model_calls: type: - integer - 'null' minimum: 0 description: Billed provider call count. format: int64 capture_status: type: string enum: - complete - partial - missing description: Token capture coverage. required: - tokens - cost - capture_status description: Usage when available; unknown measurements are null. x-ref-description: Usage when available; unknown measurements are null. RunArtifact: type: object properties: artifact_id: type: string minLength: 1 maxLength: 128 description: Immutable artifact identifier. type: type: string minLength: 1 description: Artifact kind. media_type: type: string minLength: 1 description: File media type. size_bytes: type: integer minimum: 0 description: File size in bytes. sha256: type: string pattern: ^[a-f0-9]{64}$ description: SHA-256 digest of the file. href: type: string format: uri description: Authorized artifact URL. required: - artifact_id - type - media_type - size_bytes - sha256 - href description: >- An immutable file reference authorized through the run’s project and conversation permissions. TokenUsage: type: object properties: input: type: - integer - 'null' minimum: 0 description: Input tokens excluding cache reads and writes. format: int64 output: type: - integer - 'null' minimum: 0 description: Output tokens including reasoning. format: int64 cache: type: object properties: read: type: - integer - 'null' minimum: 0 description: Tokens read from the provider cache. format: int64 write: type: - integer - 'null' minimum: 0 description: Tokens written to the provider cache. format: int64 required: - read - write reasoning: type: - integer - 'null' minimum: 0 description: Reasoning tokens included in output. format: int64 total: type: - integer - 'null' minimum: 0 description: Sum of input, output, cache-read and cache-write tokens. format: int64 required: - input - output - cache - total description: >- Input excludes cache reads/writes; output includes reasoning. Total is input + output + cache.read + cache.write. Null means unknown, never zero. Cost: type: object properties: currency: type: string enum: - EUR description: Currency of reference usage value and provider costs. status: type: string enum: - estimated - posted - unavailable description: Whether charges are estimated, posted or unavailable. provider: type: - string - 'null' pattern: ^-?\d+(\.\d{1,8})?$ description: >- Recorded provider USD cost converted to EUR at the catalog reference rate; null when unknown. platform: type: - string - 'null' pattern: ^-?\d+(\.\d{1,8})?$ description: >- Reference usage value minus estimated provider cost; null when either amount is unknown. total: type: - string - 'null' pattern: ^-?\d+(\.\d{1,8})?$ description: >- Billed credits valued at EUR 0.10 per credit, independent of subscription or purchase discounts. credits: type: - string - 'null' pattern: ^-?\d+(\.\d{1,8})?$ description: Billed credit units. required: - currency - status - provider - platform - total - credits description: >- Estimated EUR usage value before tax: total values billed credits at EUR 0.10 each; provider converts recorded USD cost at the catalog reference rate; platform is total minus provider and can be negative. These amounts are visible to authorized run readers and do not represent invoice charges or actual purchase prices. Descendants sum the same per-run amounts. Credits are exact billed units. Signed decimal strings have at most eight fractional digits. Unknown provider costs leave provider and platform null. Status is independent of token capture; unavailable requires all amounts null. Posted amounts come from the billing ledger and may change through later adjustments. allOf: - if: properties: status: enum: - unavailable required: - status then: properties: provider: type: 'null' platform: type: 'null' total: type: 'null' credits: type: 'null' else: {} 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. runExecutionAuth: type: http scheme: bearer bearerFormat: JWT description: >- Server-issued credential bound to project, run, registered runtime, execution generation, audience, expiry, and explicitly allowed operations; user/API-key editor access is insufficient. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.