> ## 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 run events > Append run events. ## OpenAPI ````yaml /cloud/rest/openapi.json post /runs/{run_id}/events 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/{run_id}/events: post: tags: - execution/Runs/Run Events summary: Append run events description: Append run events. operationId: appendRunEvents parameters: - schema: type: string format: uuid required: true example: 11111111-1111-4111-8111-111111111111 name: run_id in: path - schema: type: string minLength: 1 maxLength: 128 description: >- Stable retry key required for Task and Workflow appends; optional for Agent appends. required: false description: >- Stable retry key required for Task and Workflow appends; optional for Agent appends. name: Idempotency-Key in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AppendRunEventsRequest' examples: text_message: summary: Start an assistant message value: events: - type: TEXT_MESSAGE_START messageId: message_example contentId: content_example role: assistant responses: '200': description: Persisted event cursor content: application/json: schema: $ref: '#/components/schemas/AppendRunEventsResponse' examples: model_call: summary: Record completed model call value: run_id: 11111111-1111-4111-8111-111111111111 latest_event_id: 42 appended_count: 1 '400': description: Bad request headers: X-Run-Latest-Event-Id: schema: type: integer minimum: 0 description: Current durable cursor after an authenticated append mismatch. required: true X-Run-Latest-External-Sequence: schema: type: integer minimum: 0 description: >- Current external sequence after an authenticated append mismatch. required: true 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 '503': description: Service unavailable content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/TargetRunProblem' - properties: status: const: 503 security: - runEventWriterAuth: [] x-codeSamples: - lang: json label: Request JSON example: text_message contentType: application/json source: |- { "events": [ { "type": "TEXT_MESSAGE_START", "messageId": "message_example", "contentId": "content_example", "role": "assistant" } ] } components: schemas: AppendRunEventsRequest: 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: oneOf: - $ref: '#/components/schemas/TextMessageStartPayload' - $ref: '#/components/schemas/TextMessageContentPayload' - $ref: '#/components/schemas/TextMessageEndPayload' - $ref: '#/components/schemas/ToolCallStartPayload' - $ref: '#/components/schemas/ToolCallArgsPayload' - $ref: '#/components/schemas/ToolCallChunkPayload' - $ref: '#/components/schemas/ToolCallEndPayload' - $ref: '#/components/schemas/ToolCallResultPayload' - $ref: '#/components/schemas/MessagesSnapshotPayload' - $ref: '#/components/schemas/StateSnapshotPayload' - $ref: '#/components/schemas/StateDeltaPayload' - $ref: '#/components/schemas/RunStartedPayload' - $ref: '#/components/schemas/RunFinishedPayload' - $ref: '#/components/schemas/RunErrorPayload' - $ref: '#/components/schemas/StepStartedPayload' - $ref: '#/components/schemas/StepFinishedPayload' - $ref: '#/components/schemas/ReasoningStartPayload' - $ref: '#/components/schemas/ReasoningMessageStartPayload' - $ref: '#/components/schemas/ReasoningMessageContentPayload' - $ref: '#/components/schemas/ReasoningMessageEndPayload' - $ref: '#/components/schemas/ReasoningContentPayload' - $ref: '#/components/schemas/ReasoningEndPayload' - $ref: '#/components/schemas/ActivitySnapshotPayload' - $ref: '#/components/schemas/ActivityDeltaPayload' - $ref: '#/components/schemas/ToolCallStatusChangedPayload' - $ref: '#/components/schemas/InputRequestCreatedPayload' - $ref: '#/components/schemas/InputRequestUpdatedPayload' - $ref: '#/components/schemas/ChildRunStatusChangedPayload' - $ref: '#/components/schemas/ModelCallCompletedPayload' - $ref: '#/components/schemas/RunParkedPayload' - $ref: '#/components/schemas/RunLogCapturedPayload' - $ref: '#/components/schemas/StreamHeartbeatEmittedPayload' - $ref: '#/components/schemas/UrlCitedPayload' - $ref: '#/components/schemas/DocumentCitedPayload' - $ref: '#/components/schemas/FileAttachedPayload' - $ref: '#/components/schemas/FilesChangedPayload' - $ref: '#/components/schemas/RuntimeEventRecordedPayload' - $ref: '#/components/schemas/AgentRunContextCompactedPayload' - $ref: >- #/components/schemas/AgentRunControlPlaneDispatchAcceptedPayload - $ref: >- #/components/schemas/AgentRunControlPlaneDispatchReceiptPayload - $ref: '#/components/schemas/AgentRunToolExposureCheckpointedPayload' - $ref: '#/components/schemas/AgentRunToolExposureCheckpointPayload' - $ref: '#/components/schemas/AgentRunProviderReplayCheckpointedPayload' - $ref: '#/components/schemas/AgentRunProviderReplayCheckpointPayload' - $ref: '#/components/schemas/AgentRunModelCallContextRecordedPayload' - $ref: '#/components/schemas/AgentRunModelCallContextPayload' minItems: 1 maxItems: 100 runtime_observations: type: object properties: version: type: number enum: - 1 observations: type: array items: oneOf: - type: object properties: kind: type: string enum: - execution_entry occurrence_id: type: string format: uuid event_index: type: integer minimum: 0 maximum: 99 required: - kind - occurrence_id - event_index additionalProperties: false - type: object properties: kind: type: string enum: - step_started step_id: type: string format: uuid event_index: type: integer minimum: 0 maximum: 99 required: - kind - step_id - event_index additionalProperties: false - type: object properties: kind: type: string enum: - step_ended step_id: type: string format: uuid event_index: type: integer minimum: 0 maximum: 99 required: - kind - step_id - event_index additionalProperties: false - type: object properties: kind: type: string enum: - step_message step_id: type: string format: uuid message_span_id: type: string format: uuid event_index: type: integer minimum: 0 maximum: 99 required: - kind - step_id - message_span_id - event_index additionalProperties: false minItems: 1 maxItems: 100 required: - version - observations additionalProperties: false required: - events AppendRunEventsResponse: type: object properties: latest_event_id: type: integer minimum: 0 latest_external_event_sequence: type: integer minimum: 0 appended_count: type: integer minimum: 0 run_id: type: string format: uuid model_call_captures: type: array items: type: object properties: event_id: type: string minLength: 1 project_id: type: string format: uuid run_id: type: string format: uuid model_call_id: type: string format: uuid required: - event_id - project_id - run_id - model_call_id additionalProperties: false required: - latest_event_id - appended_count - run_id 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 TextMessageStartPayload: 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 allOf: - 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 TextMessageContentPayload: 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 - delta allOf: - 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 TextMessageEndPayload: type: object properties: type: type: string enum: - TEXT_MESSAGE_END messageId: type: string minLength: 1 contentId: type: string minLength: 1 required: - type - messageId allOf: - type: object properties: type: type: string enum: - TEXT_MESSAGE_END messageId: type: string minLength: 1 contentId: type: string minLength: 1 required: - type - messageId - contentId ToolCallStartPayload: type: object properties: type: type: string enum: - TOOL_CALL_START toolCallId: type: string minLength: 1 toolCallName: type: string minLength: 1 parentMessageId: type: string minLength: 1 required: - type - toolCallId - toolCallName allOf: - type: object properties: type: type: string enum: - TOOL_CALL_START toolCallId: type: string minLength: 1 toolCallName: type: string minLength: 1 required: - type - toolCallId - toolCallName ToolCallArgsPayload: type: object properties: type: type: string enum: - TOOL_CALL_ARGS toolCallId: type: string minLength: 1 delta: type: string required: - type - toolCallId - delta allOf: - type: object properties: type: type: string enum: - TOOL_CALL_ARGS toolCallId: type: string minLength: 1 delta: type: string required: - type - toolCallId - delta ToolCallChunkPayload: type: object properties: type: type: string enum: - TOOL_CALL_CHUNK toolCallId: type: string minLength: 1 delta: type: string required: - type - toolCallId - delta allOf: - type: object properties: type: type: string enum: - TOOL_CALL_CHUNK toolCallId: type: string minLength: 1 delta: type: string required: - type - toolCallId - delta ToolCallEndPayload: type: object properties: type: type: string enum: - TOOL_CALL_END toolCallId: type: string minLength: 1 required: - type - toolCallId allOf: - type: object properties: type: type: string enum: - TOOL_CALL_END toolCallId: type: string minLength: 1 required: - type - toolCallId ToolCallResultPayload: type: object properties: type: type: string enum: - TOOL_CALL_RESULT toolCallId: type: string minLength: 1 messageId: type: string minLength: 1 parentMessageId: type: string minLength: 1 content: {} isError: type: - boolean - 'null' role: type: string enum: - tool required: - type - toolCallId - isError allOf: - 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 MessagesSnapshotPayload: type: object properties: type: type: string enum: - MESSAGES_SNAPSHOT messages: type: array items: type: object additionalProperties: {} required: - type - messages allOf: - 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 StateSnapshotPayload: type: object properties: type: type: string enum: - STATE_SNAPSHOT snapshot: type: object additionalProperties: {} required: - type - snapshot allOf: - type: object properties: type: type: string enum: - STATE_SNAPSHOT snapshot: type: object additionalProperties: {} required: - type - snapshot StateDeltaPayload: type: object properties: type: type: string enum: - STATE_DELTA delta: {} required: - type allOf: - 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 RunStartedPayload: type: object properties: type: type: string enum: - RUN_STARTED runId: type: string minLength: 1 required: - type allOf: - type: object properties: type: type: string enum: - RUN_STARTED required: - type RunFinishedPayload: type: object properties: type: type: string enum: - RUN_FINISHED runId: type: string minLength: 1 metadata: type: object additionalProperties: {} required: - type allOf: - type: object properties: type: type: string enum: - RUN_FINISHED required: - type RunErrorPayload: type: object properties: type: type: string enum: - RUN_ERROR runId: type: string minLength: 1 code: type: string minLength: 1 message: type: string metadata: type: object additionalProperties: {} required: - type allOf: - type: object properties: type: type: string enum: - RUN_ERROR required: - type StepStartedPayload: type: object properties: type: type: string enum: - STEP_STARTED stepId: type: string minLength: 1 stepName: type: string minLength: 1 runtime: type: string minLength: 1 required: - type allOf: - type: object properties: type: type: string enum: - STEP_STARTED required: - type StepFinishedPayload: type: object properties: type: type: string enum: - STEP_FINISHED stepId: type: string minLength: 1 stepName: type: string minLength: 1 runtime: type: string minLength: 1 status: type: string minLength: 1 required: - type allOf: - type: object properties: type: type: string enum: - STEP_FINISHED required: - type ReasoningStartPayload: type: object properties: type: type: string enum: - REASONING_START messageId: type: string minLength: 1 required: - type allOf: - type: object properties: type: type: string enum: - REASONING_START required: - type ReasoningMessageStartPayload: type: object properties: type: type: string enum: - REASONING_MESSAGE_START messageId: type: string minLength: 1 required: - type - messageId allOf: - type: object properties: type: type: string enum: - REASONING_MESSAGE_START required: - type ReasoningMessageContentPayload: type: object properties: type: type: string enum: - REASONING_MESSAGE_CONTENT messageId: type: string minLength: 1 delta: type: string required: - type - messageId - delta allOf: - type: object properties: type: type: string enum: - REASONING_MESSAGE_CONTENT required: - type ReasoningMessageEndPayload: type: object properties: type: type: string enum: - REASONING_MESSAGE_END messageId: type: string minLength: 1 required: - type - messageId allOf: - type: object properties: type: type: string enum: - REASONING_MESSAGE_END required: - type ReasoningContentPayload: type: object properties: type: type: string enum: - REASONING_CONTENT messageId: type: string minLength: 1 delta: type: string required: - type - delta allOf: - type: object properties: type: type: string enum: - REASONING_CONTENT required: - type ReasoningEndPayload: type: object properties: type: type: string enum: - REASONING_END messageId: type: string minLength: 1 required: - type allOf: - type: object properties: type: type: string enum: - REASONING_END required: - type ActivitySnapshotPayload: type: object properties: type: type: string enum: - ACTIVITY_SNAPSHOT required: - type allOf: - type: object properties: type: type: string enum: - ACTIVITY_SNAPSHOT required: - type ActivityDeltaPayload: type: object properties: type: type: string enum: - ACTIVITY_DELTA required: - type allOf: - type: object properties: type: type: string enum: - ACTIVITY_DELTA required: - type ToolCallStatusChangedPayload: 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 allOf: - 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 InputRequestCreatedPayload: type: object properties: type: type: string enum: - INPUT_REQUEST_CREATED inputRequest: type: object properties: id: type: string minLength: 1 required: - id required: - type - inputRequest allOf: - type: object properties: type: type: string enum: - INPUT_REQUEST_CREATED inputRequest: type: object properties: id: type: string minLength: 1 required: - id required: - type - inputRequest InputRequestUpdatedPayload: type: object properties: type: type: string enum: - INPUT_REQUEST_UPDATED inputRequest: type: object properties: id: type: string minLength: 1 required: - id required: - type - inputRequest allOf: - type: object properties: type: type: string enum: - INPUT_REQUEST_UPDATED inputRequest: type: object properties: id: type: string minLength: 1 required: - id required: - type - inputRequest ChildRunStatusChangedPayload: 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 allOf: - 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 ModelCallCompletedPayload: type: object properties: type: type: string enum: - MODEL_CALL_COMPLETED provider: type: string minLength: 1 model: type: string minLength: 1 inputTokens: type: integer minimum: 0 outputTokens: type: integer minimum: 0 cacheCreationTokens: type: integer minimum: 0 cacheReadTokens: type: integer minimum: 0 totalTokens: type: integer minimum: 0 costCredits: type: string minLength: 1 latencyMs: type: - integer - 'null' minimum: 0 usageCaptureStatus: type: string enum: - complete - partial - missing providerRequestId: type: - string - 'null' minLength: 1 modelCallContextEventId: type: - integer - 'null' exclusiveMinimum: 0 required: - type - provider - model - inputTokens - outputTokens - cacheCreationTokens - cacheReadTokens - totalTokens - costCredits - latencyMs - usageCaptureStatus - providerRequestId - modelCallContextEventId allOf: - type: object properties: type: type: string enum: - MODEL_CALL_COMPLETED provider: type: string minLength: 1 model: type: string minLength: 1 inputTokens: type: integer minimum: 0 outputTokens: type: integer minimum: 0 cacheCreationTokens: type: integer minimum: 0 cacheReadTokens: type: integer minimum: 0 totalTokens: type: integer minimum: 0 costCredits: type: string minLength: 1 latencyMs: type: - integer - 'null' minimum: 0 usageCaptureStatus: type: string enum: - complete - partial - missing providerRequestId: type: - string - 'null' minLength: 1 modelCallContextEventId: type: - integer - 'null' exclusiveMinimum: 0 required: - type - provider - model - inputTokens - outputTokens - cacheCreationTokens - cacheReadTokens - totalTokens - costCredits - latencyMs - usageCaptureStatus - providerRequestId - modelCallContextEventId RunParkedPayload: 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 allOf: - 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 RunLogCapturedPayload: type: object properties: type: type: string enum: - RUN_LOG_CAPTURED logs: type: string required: - type - logs allOf: - type: object properties: type: type: string enum: - RUN_LOG_CAPTURED logs: type: string required: - type - logs StreamHeartbeatEmittedPayload: type: object properties: type: type: string enum: - STREAM_HEARTBEAT_EMITTED runId: type: string minLength: 1 lastEventId: type: integer minimum: 0 required: - type - runId - lastEventId allOf: - type: object properties: type: type: string enum: - STREAM_HEARTBEAT_EMITTED runId: type: string minLength: 1 lastEventId: type: integer minimum: 0 required: - type - runId - lastEventId UrlCitedPayload: 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 allOf: - 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 DocumentCitedPayload: 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 allOf: - 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 FileAttachedPayload: 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 allOf: - 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 FilesChangedPayload: 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 allOf: - 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 RuntimeEventRecordedPayload: 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 allOf: - 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 AgentRunContextCompactedPayload: type: object properties: type: type: string enum: - AGENT_RUN_CONTEXT_COMPACTED required: - type allOf: - 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 AgentRunControlPlaneDispatchAcceptedPayload: type: object properties: type: type: string enum: - AGENT_RUN_CONTROL_PLANE_DISPATCH_ACCEPTED required: - type allOf: - type: object properties: type: type: string enum: - AGENT_RUN_CONTROL_PLANE_DISPATCH_ACCEPTED requestHash: type: string pattern: ^[A-Za-z0-9_-]{43}$ required: - type - requestHash additionalProperties: false AgentRunControlPlaneDispatchReceiptPayload: type: object properties: type: type: string enum: - AGENT_RUN_CONTROL_PLANE_DISPATCH_RECEIPT required: - type allOf: - type: object properties: type: type: string enum: - AGENT_RUN_CONTROL_PLANE_DISPATCH_RECEIPT requestHash: type: string pattern: ^[A-Za-z0-9_-]{43}$ required: - type - requestHash additionalProperties: false AgentRunToolExposureCheckpointedPayload: type: object properties: type: type: string enum: - AGENT_RUN_TOOL_EXPOSURE_CHECKPOINTED required: - type allOf: - type: object properties: type: type: string enum: - AGENT_RUN_TOOL_EXPOSURE_CHECKPOINTED 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 AgentRunToolExposureCheckpointPayload: type: object properties: type: type: string enum: - AGENT_RUN_TOOL_EXPOSURE_CHECKPOINT required: - type allOf: - type: object properties: type: type: string enum: - 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 AgentRunProviderReplayCheckpointedPayload: type: object properties: type: type: string enum: - AGENT_RUN_PROVIDER_REPLAY_CHECKPOINTED required: - type allOf: - type: object properties: type: type: string enum: - AGENT_RUN_PROVIDER_REPLAY_CHECKPOINTED 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 AgentRunProviderReplayCheckpointPayload: type: object properties: type: type: string enum: - AGENT_RUN_PROVIDER_REPLAY_CHECKPOINT required: - type allOf: - type: object properties: type: type: string enum: - 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 AgentRunModelCallContextRecordedPayload: type: object properties: type: type: string enum: - AGENT_RUN_MODEL_CALL_CONTEXT_RECORDED required: - type allOf: - type: object properties: type: type: string enum: - AGENT_RUN_MODEL_CALL_CONTEXT_RECORDED 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 parallelToolCalls: type: boolean 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 modelCallId: type: string format: uuid required: - type - messages additionalProperties: false AgentRunModelCallContextPayload: type: object properties: type: type: string enum: - AGENT_RUN_MODEL_CALL_CONTEXT required: - type allOf: - type: object properties: type: type: string enum: - 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 parallelToolCalls: type: boolean 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 modelCallId: type: string format: uuid required: - type - messages additionalProperties: false 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.