> ## 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 a canonical durable run > Creates a canonical durable run for an owner scope and returns the accepted run envelope. ## OpenAPI ````yaml https://api.veryfront.com/openapi.json post /runs openapi: 3.1.0 info: title: Veryfront REST API version: 1.0.0 summary: Domain-first REST reference for the maintained Veryfront HTTP API surface. description: >- Project-first HTTP API for Veryfront project resources. Root account/platform endpoints that still appear in this reference are transitional compatibility surfaces unless the canonical inventory marks them otherwise. ## Start here - **Interactive REST reference:** [/docs](/docs) - **Raw OpenAPI document:** [/openapi.json](/openapi.json) - **Canonical inventory:** `docs/api-surface-inventory.md` in this repository - **GraphQL endpoint:** [/graphql](/graphql) - **MCP playground:** [/mcp/playground](/mcp/playground) ## Authentication Use one of these request headers: - `Authorization: Bearer ` - `Authorization: Bearer vf__` - `X-API-Key: vf__` JWTs must use the Bearer token contract. API keys work in either the Bearer header or `X-API-Key`. ## Discovery model Veryfront is one platform with multiple access modes: - **REST** for resource-oriented and operational HTTP workflows - **GraphQL** for connected app-facing data and typed mutations - **MCP** for tool-style automation and agent workflows For the fastest path through the platform, start with the project-scoped domain groups. Transitional account/platform groups are retained for compatibility and follow the removal register in the canonical inventory. contact: name: Veryfront API Support url: https://veryfront.com/docs email: support@veryfront.com servers: - url: https://api.veryfront.com description: Current request origin - url: http://localhost:4000 description: Local development security: - bearerAuth: [] - apiKeyAuth: [] tags: - name: Projects description: Core project operations - name: Account description: >- Transitional account-level users and settings retained for dashboard compatibility - name: Project Users description: Project members and invites - name: Members description: Project members and invites - name: Files description: Main branch files - name: Branch Files description: Files on branches - name: Environment Files description: Files in environments - name: Release Files description: Files in releases - name: Uploads description: File uploads and assets - name: Branches description: Content branches for previews - name: Releases description: Published file snapshots - name: Deployments description: Connect releases to environments - name: Environments description: Deployment targets and variables - name: Environment Variables description: Project environment variable management - name: Domains description: Custom domains for environments - name: Project Servers description: Project-scoped dedicated server instances - name: Root Servers description: >- Transitional root dedicated-server administration retained for compatibility - name: Tasks description: Project tasks - name: Evals description: Project eval definitions and eval run projections - name: Work description: Project business-process definitions and execution state - name: Workflows description: Project workflows - name: Workflow Runs description: Workflow run history and status - name: Schedules description: Recurring project automation schedules - name: Webhooks description: Webhook-triggered automation entry points - name: Skills description: Project skills - name: Prompts description: Project prompts - name: Tools description: Project tools - name: Resources description: Project-defined resource documents and source-backed resource definitions - name: Sandboxes description: Ephemeral sandbox execution environments - name: Search description: Text and vector search - name: Knowledge description: Knowledge manifest lookup across project knowledge files - name: Chunks description: File chunks for search indexing - name: Embeddings description: Vector embeddings - name: RAG Documents description: Project retrieval-augmented knowledge documents - name: Style Artifacts description: Project style artifact state and build outputs - name: External Storage description: Transitional connected cloud-provider file operations - name: Project Cache description: Project-scoped distributed cache operations - name: User Cache description: Transitional user cache helpers retained for compatibility - name: API Keys description: >- Transitional user/account API key management; prefer project-scoped keys for public integrations - name: User description: Transitional current-user profile endpoint for first-party clients - name: Favorites description: Transitional user favorites for first-party dashboard clients - name: Subscriptions description: Transitional account billing and subscription workflows - name: Credits description: Transitional account credit balance, purchase, and insufficiency flows - name: Usage description: >- Project/account usage limits and warnings; account-level usage is transitional - name: Gates description: Transitional plan and feature gate checks for first-party clients - name: Channels description: Project channel integrations and delivery settings - name: Agents description: Project agents - name: Agent Catalog description: Public catalog of agents assembled from curated template projects - name: Agent Workers description: Internal/transitional agent worker leases and sessions - name: Agent Runtimes description: Registered push-based agent runtime services and runtime target health - name: Project Integrations description: Project-scoped integration catalog and configuration - name: Integrations description: Transitional external integration catalog for first-party clients - name: Integration Tools description: >- Transitional dynamic integration tool listing, invocation, and connection state - name: OAuth description: >- Transitional OAuth integration flows for first-party and connected-app clients - name: Templates description: Transitional starter-template discovery used during project creation - name: AI description: >- Transitional platform AI gateway/model helpers; project AI assets use project-scoped routes - name: Images description: Generated images and image assets - name: Conversations description: Transitional conversation/run-control HTTP surface for first-party clients - name: Runs description: Transitional hosted run-control endpoints for conversation execution - name: MCP description: >- MCP catalog/playground helpers; primary MCP traffic uses the streamable MCP handler - name: Logs description: Project log queries via Loki - name: Metrics description: Project metric queries via a Prometheus-compatible backend - name: Traces description: Project trace queries via Grafana Tempo - name: Errors description: Internal/public error type catalog (RFC 9457) - name: Authentication description: Transitional auth token, login, logout, magic-link, and JWKS flows externalDocs: description: Interactive REST reference url: https://api.veryfront.com/docs paths: /runs: post: tags: - Runs summary: Create a canonical durable run description: >- Creates a canonical durable run for an owner scope and returns the accepted run envelope. requestBody: content: application/json: schema: 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 conversation_mode: type: string enum: - create_new - existing - none conversation_id: type: string format: uuid request: anyOf: - type: object properties: mode: type: string enum: - agent agent_id: type: string minLength: 1 implementation_kind: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z0-9_-]+$ description: >- The implementation kind associated with this tool result. worker_key: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9_.:-]+$ description: The worker key associated with this tool result. initial_status: type: string enum: - pending - running source_target_kind: type: string nullable: true enum: - project - main_branch - environment - preview_branch - release source_target_environment_id: type: string nullable: true format: uuid source_target_branch_id: type: string nullable: true format: uuid source_target_release_version: type: string nullable: true minLength: 1 maxLength: 128 runtime_target_kind: type: string nullable: true enum: - main_branch - environment - preview_branch description: Provide the runtime target kind. runtime_target_environment_id: type: string nullable: true format: uuid runtime_target_branch_id: type: string nullable: true format: uuid required: - mode - agent_id - implementation_kind additionalProperties: false title: RuntimeAgentRequest - type: object properties: mode: type: string enum: - agent agent_id: type: string minLength: 1 initial_status: type: string enum: - pending - running source_target_kind: type: string nullable: true enum: - project - main_branch - environment - preview_branch - release source_target_environment_id: type: string nullable: true format: uuid source_target_branch_id: type: string nullable: true format: uuid source_target_release_version: type: string nullable: true minLength: 1 maxLength: 128 runtime_target_kind: type: string nullable: true enum: - main_branch - environment - preview_branch description: Provide the runtime target kind. runtime_target_environment_id: type: string nullable: true format: uuid runtime_target_branch_id: type: string nullable: true 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: nullable: true inputSchema: type: object additionalProperties: nullable: true outputSchema: type: object additionalProperties: nullable: true required: - name maxItems: 50 context: type: object properties: conversation_id: type: string format: uuid project_id: type: string nullable: true format: uuid project_reference: type: string nullable: true minLength: 1 branch_id: type: string nullable: true 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: nullable: true runtime_overrides: type: object properties: allowed_tools: type: array items: type: string minLength: 1 maxItems: 100 thinking: anyOf: - type: boolean enum: - false - type: integer minimum: 0 exclusiveMinimum: true max_steps: type: integer minimum: 0 exclusiveMinimum: true 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 input: type: object properties: agent_id: type: string minLength: 1 maxLength: 128 source_target_kind: type: string enum: - project - main_branch - environment - preview_branch description: Provide the source target kind. allow_delegation: type: boolean default: true messages: type: array items: nullable: true 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: nullable: true inputSchema: type: object additionalProperties: nullable: true outputSchema: type: object additionalProperties: nullable: true 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: nullable: true 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: nullable: true runtime_target_kind: type: string nullable: true enum: - main_branch - environment - preview_branch description: Provide the runtime target kind. target_environment_id: type: string nullable: true format: uuid target_branch_id: type: string nullable: true format: uuid required: - agent_id additionalProperties: false 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: workflow_id: type: string minLength: 1 maxLength: 255 target: type: string minLength: 1 maxLength: 512 runtime_target_kind: type: string enum: - main_branch - environment - preview_branch description: Provide the runtime target kind. runtime_target_environment_id: type: string nullable: true format: uuid runtime_target_branch_id: type: string nullable: true format: uuid input: type: object additionalProperties: nullable: true 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 task run name. target: type: string minLength: 1 maxLength: 512 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 description: Provide the runtime target kind. runtime_target_environment_id: type: string nullable: true format: uuid runtime_target_branch_id: type: string nullable: true format: uuid config: type: object additionalProperties: nullable: true timeout_seconds: type: integer minimum: 0 exclusiveMinimum: true backoff_limit: type: integer minimum: 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: target: type: string minLength: 1 maxLength: 512 runtime_target_kind: type: string enum: - main_branch - environment - preview_branch description: Provide the runtime target kind. runtime_target_environment_id: type: string nullable: true format: uuid runtime_target_branch_id: type: string nullable: true format: uuid input: type: object additionalProperties: nullable: true config: type: object additionalProperties: nullable: true 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 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 parent_run_id: type: string nullable: true minLength: 1 root_run_id: type: string minLength: 1 waiting_reason: type: string nullable: true enum: - tool - approval - event - input metadata: nullable: true target: type: string nullable: true workflow_id: type: string nullable: true schedule_id: type: string nullable: true format: uuid batch_id: type: string nullable: true format: uuid runtime_target_kind: type: string nullable: true enum: - main_branch - environment - preview_branch description: Provide the runtime target kind. runtime_target_environment_id: type: string nullable: true format: uuid runtime_target_branch_id: type: string nullable: true format: uuid input: nullable: true config: nullable: true output: nullable: true error: type: object nullable: true properties: message: type: string code: type: string required: - message logs: type: string nullable: true artifacts: type: array items: nullable: true duration_ms: type: integer nullable: true exit_code: type: integer nullable: true start_mode: type: string nullable: true timeout_seconds: type: integer nullable: true backoff_limit: type: integer nullable: true trigger_kind: type: string nullable: true enum: - manual - schedule - webhook - api trigger_id: type: string nullable: true created_by: type: string nullable: true minLength: 1 maxLength: 255 updated_at: type: string created_at: type: string started_at: type: string nullable: true completed_at: type: string nullable: true required: - run_id - kind - status - owner - parent_run_id - root_run_id - waiting_reason - 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 - trigger_kind - trigger_id - created_by - updated_at - created_at - started_at - completed_at conversation_id: type: string nullable: true format: uuid message_id: type: string nullable: true format: uuid required: - accepted - run components: 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. ````