> ## 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. # Append events to a canonical durable run > Appends runtime-produced events to a durable run using a run event writer token. This run-scoped path supports conversationless runs and is limited to credentials bound to the exact run. ## OpenAPI ````yaml https://api.veryfront.com/openapi.json post /runs/{run_id}/events 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: 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: Dependencies description: >- npm dependency resolution, exact-version pinning, and signed runtime artifact registry contracts - 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 Templates description: >- Public template catalog of addable 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: Connections description: Viewer-visible project and project-user integration connections - 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/{run_id}/events: post: tags: - Runs summary: Append events to a canonical durable run description: >- Appends runtime-produced events to a durable run using a run event writer token. This run-scoped path supports conversationless runs and is limited to credentials bound to the exact run. operationId: appendRunEvents parameters: - schema: type: string minLength: 1 required: true name: run_id in: path requestBody: content: application/json: schema: type: object properties: expected_previous_event_id: type: - integer - 'null' minimum: 0 expected_previous_external_event_sequence: type: - integer - 'null' minimum: 0 external_sequence_scope: type: string enum: - agent - publish_only events: type: array items: anyOf: - oneOf: - type: object properties: type: type: string enum: - TEXT_MESSAGE_START messageId: type: string minLength: 1 contentId: type: string minLength: 1 role: type: string required: - type - messageId - contentId - type: object properties: type: type: string enum: - TEXT_MESSAGE_CONTENT messageId: type: string minLength: 1 contentId: type: string minLength: 1 delta: type: string required: - type - messageId - contentId - delta - type: object properties: type: type: string enum: - TEXT_MESSAGE_END messageId: type: string minLength: 1 contentId: type: string minLength: 1 required: - type - messageId - contentId - type: object properties: type: type: string enum: - TOOL_CALL_START toolCallId: type: string minLength: 1 toolCallName: type: string minLength: 1 required: - type - toolCallId - toolCallName - type: object properties: type: type: string enum: - TOOL_CALL_ARGS toolCallId: type: string minLength: 1 delta: type: string required: - type - toolCallId - delta - type: object properties: type: type: string enum: - TOOL_CALL_CHUNK toolCallId: type: string minLength: 1 delta: type: string required: - type - toolCallId - delta - type: object properties: type: type: string enum: - TOOL_CALL_END toolCallId: type: string minLength: 1 required: - type - toolCallId - type: object properties: type: type: string enum: - TOOL_CALL_RESULT messageId: type: string minLength: 1 parentMessageId: type: string minLength: 1 toolCallId: type: string minLength: 1 input: {} content: {} result: {} role: type: string enum: - tool isError: type: - boolean - 'null' required: - type - toolCallId - type: object properties: type: type: string enum: - MESSAGES_SNAPSHOT messages: type: array items: type: object properties: id: type: string minLength: 1 role: type: string minLength: 1 parts: type: array items: type: object properties: type: type: string minLength: 1 required: - type content: {} required: - type - messages - type: object properties: type: type: string enum: - STATE_SNAPSHOT snapshot: type: object additionalProperties: {} required: - type - snapshot - type: object properties: type: type: string enum: - STATE_DELTA delta: anyOf: - type: object additionalProperties: {} - type: array items: type: object properties: op: type: string enum: - add - remove - replace - move - copy - test path: type: string minLength: 1 from: type: string minLength: 1 value: {} required: - op - path required: - type - delta - type: object properties: type: type: string enum: - RUN_STARTED - RUN_FINISHED - RUN_ERROR - STEP_STARTED - STEP_FINISHED - REASONING_START - REASONING_MESSAGE_START - REASONING_MESSAGE_CONTENT - REASONING_MESSAGE_END - REASONING_CONTENT - REASONING_END - ACTIVITY_SNAPSHOT - ACTIVITY_DELTA required: - type - type: object properties: type: type: string enum: - TOOL_CALL_STATUS_CHANGED toolCallId: type: string minLength: 1 status: type: string minLength: 1 toolCallName: type: - string - 'null' minLength: 1 required: - type - toolCallId - status - toolCallName - type: object properties: type: type: string enum: - INPUT_REQUEST_CREATED inputRequest: type: object properties: id: type: string minLength: 1 required: - id required: - type - inputRequest - type: object properties: type: type: string enum: - INPUT_REQUEST_UPDATED inputRequest: type: object properties: id: type: string minLength: 1 required: - id required: - type - inputRequest - type: object properties: type: type: string enum: - CHILD_RUN_STATUS_CHANGED toolCallId: type: string minLength: 1 childRunId: type: string minLength: 1 status: type: string minLength: 1 childConversationId: type: - string - 'null' minLength: 1 childMessageId: type: - string - 'null' minLength: 1 childAgentId: type: - string - 'null' minLength: 1 description: type: string minLength: 1 required: - type - toolCallId - childRunId - status - type: object properties: type: type: string enum: - RUN_PARKED runId: type: string minLength: 1 reason: type: string minLength: 1 lastEventId: type: integer minimum: 0 required: - type - runId - reason - lastEventId - type: object properties: type: type: string enum: - RUN_LOG_CAPTURED logs: type: string required: - type - logs - type: object properties: type: type: string enum: - STREAM_HEARTBEAT_EMITTED runId: type: string minLength: 1 lastEventId: type: integer minimum: 0 required: - type - runId - lastEventId - type: object properties: type: type: string enum: - URL_CITED url: type: string minLength: 1 sourceId: type: string minLength: 1 title: type: string minLength: 1 required: - type - url - sourceId - type: object properties: type: type: string enum: - DOCUMENT_CITED mediaType: type: string minLength: 1 sourceId: type: string minLength: 1 title: type: string minLength: 1 filename: type: string minLength: 1 required: - type - mediaType - sourceId - type: object properties: type: type: string enum: - FILE_ATTACHED mediaType: type: string minLength: 1 url: type: string minLength: 1 filename: type: string minLength: 1 required: - type - mediaType - type: object properties: type: type: string enum: - FILES_CHANGED id: type: - string - 'null' minLength: 1 status: type: - string - 'null' minLength: 1 changes: {} required: - type - id - status - changes - type: object properties: type: type: string enum: - RUNTIME_EVENT_RECORDED runtime: type: string minLength: 1 kind: type: string minLength: 1 value: {} required: - type - runtime - kind - value - type: object properties: type: type: string enum: - AGENT_RUN_CONTEXT_COMPACTED summary: type: object properties: text: type: string minLength: 1 required: - text firstKeptEntryId: type: string minLength: 1 tokensBefore: type: integer minimum: 0 tokensAfter: type: integer minimum: 0 tokenBudget: type: integer exclusiveMinimum: 0 reserveTokens: type: integer minimum: 0 reason: type: string enum: - context_window - transport_body elapsedMs: type: number minimum: 0 emittedAt: type: integer minimum: 0 required: - type - summary - firstKeptEntryId - tokensBefore - tokensAfter - tokenBudget - reserveTokens - reason additionalProperties: false - type: object properties: type: type: string enum: - AGENT_RUN_CONTROL_PLANE_DISPATCH_ACCEPTED - AGENT_RUN_CONTROL_PLANE_DISPATCH_RECEIPT requestHash: type: string pattern: ^[A-Za-z0-9_-]{43}$ required: - type - requestHash additionalProperties: false - type: object properties: type: type: string enum: - AGENT_RUN_TOOL_EXPOSURE_CHECKPOINTED - AGENT_RUN_TOOL_EXPOSURE_CHECKPOINT version: anyOf: - type: number enum: - 1 - type: number enum: - 2 authorizedCatalogFingerprint: type: string minLength: 1 maxLength: 256 loadedToolNames: type: array items: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z][a-zA-Z0-9._:-]*$ elapsedMs: type: number minimum: 0 emittedAt: type: integer minimum: 0 required: - type - version - loadedToolNames additionalProperties: false - type: object properties: type: type: string enum: - AGENT_RUN_PROVIDER_REPLAY_CHECKPOINTED - AGENT_RUN_PROVIDER_REPLAY_CHECKPOINT version: type: number enum: - 1 messageId: type: string minLength: 1 maxLength: 256 provider: type: string enum: - anthropic - openai-responses providerBlocks: type: array items: type: object properties: type: type: string enum: - provider-block provider: type: string enum: - anthropic - openai-responses block: type: object additionalProperties: {} required: - type - provider - block additionalProperties: false minItems: 1 maxItems: 100 providerBlockPositions: type: array items: type: integer minimum: 0 maximum: 10000 minItems: 1 maxItems: 100 providerMessageBlockCounts: type: array items: type: integer minimum: 1 maximum: 100 minItems: 1 maxItems: 100 totalPartCount: type: integer minimum: 1 maximum: 10000 elapsedMs: type: number minimum: 0 emittedAt: type: integer minimum: 0 required: - type - version - messageId - provider - providerBlocks - providerBlockPositions - totalPartCount additionalProperties: false - type: object properties: type: type: string enum: - AGENT_RUN_MODEL_CALL_CONTEXT_RECORDED - AGENT_RUN_MODEL_CALL_CONTEXT model: type: object properties: id: type: string minLength: 1 modelProvider: type: string minLength: 1 required: - id additionalProperties: false request: type: object properties: maxOutputTokens: type: number minimum: 0 temperature: type: number topP: type: number topK: type: number stopSequences: type: array items: type: string seed: type: number presencePenalty: type: number frequencyPenalty: type: number reasoning: type: object properties: enabled: type: boolean effort: type: string enum: - low - medium - high - max budgetTokens: type: integer minimum: 0 additionalProperties: false additionalProperties: false messages: type: array items: oneOf: - type: object properties: role: type: string enum: - system content: type: string providerOptions: type: object additionalProperties: type: object properties: cacheControl: type: object properties: type: type: string enum: - ephemeral ttl: type: string enum: - 5m - 1h required: - type additionalProperties: false required: - cacheControl additionalProperties: false required: - role - content additionalProperties: false - type: object properties: role: type: string enum: - user content: type: array items: anyOf: - type: object properties: type: type: string enum: - text text: type: string required: - type - text additionalProperties: false - type: object properties: type: type: string enum: - image - file mediaType: type: string url: type: string filename: type: string required: - type - mediaType - url additionalProperties: false required: - role - content additionalProperties: false - type: object properties: role: type: string enum: - assistant content: type: array items: anyOf: - type: object properties: type: type: string enum: - text text: type: string required: - type - text additionalProperties: false - type: object properties: type: type: string enum: - tool-call toolCallId: type: string toolName: type: string input: {} providerExecuted: type: boolean required: - type - toolCallId - toolName - input additionalProperties: false required: - role - content additionalProperties: false - type: object properties: role: type: string enum: - tool content: type: array items: type: object properties: type: type: string enum: - tool-result toolCallId: type: string toolName: type: string output: type: object properties: type: type: string enum: - json value: {} required: - type - value additionalProperties: false required: - type - toolCallId - toolName - output additionalProperties: false required: - role - content additionalProperties: false tools: type: array items: anyOf: - type: object properties: type: type: string enum: - function name: type: string description: type: string inputSchema: {} required: - type - name - inputSchema additionalProperties: false - type: object properties: type: type: string enum: - provider name: type: string id: type: string args: type: object additionalProperties: {} required: - type - name - id - args additionalProperties: false elapsedMs: type: number minimum: 0 emittedAt: type: integer minimum: 0 required: - type - messages additionalProperties: false minItems: 1 maxItems: 100 required: - events responses: '200': description: Updated run cursor after appending events content: application/json: schema: type: object properties: run: type: object properties: run_id: type: string minLength: 1 conversation_id: type: - string - 'null' format: uuid message_id: type: - string - 'null' format: uuid project_id: type: - string - 'null' format: uuid requested_by_user_id: type: string format: uuid trigger_principal_type: type: - string - 'null' enum: - system - user - api_key - service_account - null trigger_principal_id: type: - string - 'null' agent_id: type: string minLength: 1 maxLength: 128 status: anyOf: - type: string enum: - completed - failed - cancelled - type: string enum: - pending - running - waiting_for_tool implementation_kind: type: - string - 'null' minLength: 1 maxLength: 64 worker_key: type: - string - 'null' minLength: 1 maxLength: 128 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 description: Provide the runtime target kind. runtime_target_environment_id: type: - string - 'null' format: uuid runtime_target_branch_id: type: - string - 'null' format: uuid parent_conversation_id: type: - string - 'null' format: uuid parent_run_id: type: - string - 'null' minLength: 1 spawned_from_message_id: type: - string - 'null' format: uuid spawned_from_tool_call_id: type: - string - 'null' minLength: 1 maxLength: 128 input_anchor_message_id: type: - string - 'null' format: uuid handoff_message_id: type: - string - 'null' format: uuid resolved_deployment_id: type: - string - 'null' format: uuid latest_event_id: type: integer minimum: 0 latest_external_event_sequence: type: integer minimum: 0 waiting_tool_call_id: type: - string - 'null' minLength: 1 maxLength: 128 waiting_tool_name: type: - string - 'null' terminal_error_code: type: - string - 'null' terminal_error_message: type: - string - 'null' created_at: type: string started_at: type: - string - 'null' finished_at: type: - string - 'null' run_snapshot: type: object properties: project_agent: oneOf: - type: object properties: kind: type: string enum: - source project_id: type: string format: uuid agent_id: type: string minLength: 1 maxLength: 128 required: - kind - project_id - agent_id - type: object properties: kind: type: string enum: - installed project_id: type: string format: uuid agent_id: type: string minLength: 1 maxLength: 128 catalog_entry_id: type: string minLength: 1 agent_access_grant_id: type: string format: uuid service_account_id: type: string format: uuid required: - kind - project_id - agent_id - catalog_entry_id - agent_access_grant_id - service_account_id - type: 'null' source: type: object properties: type: type: - string - 'null' enum: - project - catalog_entry - null path: type: - string - 'null' hash: type: - string - 'null' catalog_entry_id: type: - string - 'null' required: - type - path - hash - catalog_entry_id runtime_target: type: object properties: kind: type: - string - 'null' enum: - main_branch - environment - preview_branch - null description: Provide the runtime target kind. environment_id: type: - string - 'null' format: uuid branch_id: type: - string - 'null' format: uuid resolved_target_id: type: - string - 'null' format: uuid resolved_target_kind: type: - string - 'null' deployment_id: type: - string - 'null' format: uuid required: - kind - environment_id - branch_id - resolved_target_id - resolved_target_kind - deployment_id requester: type: object properties: user_id: type: string format: uuid required: - user_id required: - project_agent - source - runtime_target - requester required: - run_id - conversation_id - message_id - project_id - requested_by_user_id - agent_id - status - runtime_target_kind - latest_event_id - created_at - run_snapshot latest_event_id: type: integer minimum: 0 latest_external_event_sequence: type: integer minimum: 0 appended_count: type: integer minimum: 0 required: - run - latest_event_id - appended_count '401': description: A run event writer token is required security: - runEventWriterAuth: [] 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. runEventWriterAuth: type: http scheme: bearer bearerFormat: Run Event Writer JWT description: >- A run-bound Veryfront runtime event-writer token in the Authorization header. ````