> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stream events



## OpenAPI

````yaml /api-reference/openapi.yaml get /orgs/{orgID}/projects/{projectID}/agents/{agentID}/events/stream
openapi: 3.1.2
info:
  title: Omnara API
  version: 0.1.0
  description: Public HTTP API contract for Omnara.
servers:
  - url: https://api.omnara.com/v1
    description: Hosted Omnara
  - url: /api/v1
    description: Self-hosted Omnara, relative to the deployment origin
security:
  - bearerAuth: []
  - browserSessionCookie: []
tags:
  - name: Agents
    description: >-
      Launch agents, send inputs, manage the input backlog, and work with tool
      calls.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/agents/overview
  - name: Interactions
    description: List and resolve the approvals and questions that pause an agent.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/events/interactions
  - name: Actors
    description: Attribute agent inputs and interaction responses to external users.
    externalDocs:
      description: Guide
      url: >-
        https://docs.omnara.com/events/sending-input#who-said-that-actors-and-attribution
  - name: Events
    description: Read or stream the agent timeline, list turns, and download artifacts.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/events/streaming
  - name: Configs and Profiles
    description: >-
      Create agent configs, manage reusable launch profiles, and set up
      integrations.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/agents/configuration
  - name: Integrations
    description: >-
      Connect project integrations, route conversations, and manage launch
      settings.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/integrations/overview
  - name: Models
    description: Configure model providers and models, and grant projects access to them.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/model-providers
  - name: Machines
    description: Register machines, control project access, and manage daemon tokens.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/machines/connect
  - name: Machine Pools
    description: Define machine pools and grant projects access to them.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/machines/pools
  - name: Secrets
    description: >-
      Manage secret ownership and versions, and inspect or grant project
      availability.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/secrets
  - name: Skills
    description: Manage versioned skill ownership and load skill instructions on demand.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/tools/skills
  - name: Organizations and Projects
    description: Create organizations and projects and manage membership.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/members
  - name: Users and API Keys
    description: >-
      The authenticated user, personal and organization API keys, and
      invitations.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/api/authentication
  - name: Machine Daemon
    description: Routes the Omnara machine daemon uses to connect a machine.
paths:
  /orgs/{orgID}/projects/{projectID}/agents/{agentID}/events/stream:
    parameters:
      - name: orgID
        in: path
        description: Organization ID (org_...).
        required: true
        schema:
          type: string
          pattern: ^org_[a-z2-7]{26}$
      - name: projectID
        in: path
        description: Project ID (proj_...).
        required: true
        schema:
          type: string
          pattern: ^proj_[a-z2-7]{26}$
      - name: agentID
        in: path
        description: Agent ID (agt_...).
        required: true
        schema:
          type: string
          pattern: ^agt_[a-z2-7]{26}$
    get:
      tags:
        - Events
      summary: Stream events
      operationId: streamEvents
      parameters:
        - name: after_sequence
          in: query
          required: false
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: stream_deltas
          in: query
          required: false
          description: >-
            Opt in to ephemeral delta streamed frames while a model call is in
            flight. This includes partial assistant text, tool call, and
            reasoning output. Each frame carries the public `turn_id` and
            `model_call_context_id` it belongs to, and `tool_use` block starts
            carry the same public `tool_call_id` the durable `model_output`
            content block and `tool_result` event will use. Deltas are
            best-effort: they are not persisted and are not replayed on
            reconnect. The durable `model_output` event remains the source of
            truth. Default false.
          schema:
            type: boolean
        - name: Last-Event-ID
          in: header
          required: false
          schema:
            type: integer
            format: int64
            minimum: 0
      responses:
        '200':
          description: >-
            Server-sent event stream. Durable frames use `agent_input`,
            `model_output`, `tool_result`, or `context_checkpoint` as the SSE
            event name and set the SSE `id` field to the event's `sequence`,
            which reconnects can replay via `Last-Event-ID`. Best-effort tool
            lifecycle updates use `tool_call_update` and cover this agent and
            every subagent beneath it, model previews use `model_output_delta`,
            and stream-closing errors use `error`; none carries an SSE `id`, so
            reconnects resume from the last durable event. The response closes
            after every `error` frame. Raw clients reconnect when the error's
            stable code is `service_unavailable` and treat other current codes
            as terminal. Heartbeats are SSE comments and carry no JSON payload.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/AgentEventStreamData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    AgentEventStreamData:
      description: >-
        One JSON payload from the event stream: an authoritative durable event,
        a best-effort tool-call update, a best-effort model-output preview, or a
        stream-closing error. The wire response ends after an error payload;
        `service_unavailable` is retryable and other current codes are terminal.
      oneOf:
        - $ref: '#/components/schemas/AgentEvent'
        - $ref: '#/components/schemas/ToolCallUpdate'
        - $ref: '#/components/schemas/ModelOutputDelta'
        - $ref: '#/components/schemas/Error'
    AgentEvent:
      oneOf:
        - $ref: '#/components/schemas/AgentInputEvent'
        - $ref: '#/components/schemas/ModelOutputEvent'
        - $ref: '#/components/schemas/ToolResultEvent'
        - $ref: '#/components/schemas/ContextCheckpointEvent'
      discriminator:
        propertyName: event_kind
        mapping:
          agent_input: '#/components/schemas/AgentInputEvent'
          model_output: '#/components/schemas/ModelOutputEvent'
          tool_result: '#/components/schemas/ToolResultEvent'
          context_checkpoint: '#/components/schemas/ContextCheckpointEvent'
    ToolCallUpdate:
      description: >-
        A notification that a tool call entered a lifecycle state. On the event
        stream, this is ephemeral and sent for the streamed agent and every
        subagent beneath it, so questions, permission requests, and custom tool
        calls anywhere in the tree surface here; query the list endpoints with
        `include_subagents` for the current rows.
      type: object
      additionalProperties: false
      required:
        - tool_call_id
        - state
      properties:
        tool_call_id:
          $ref: '#/components/schemas/ToolCallID'
        agent_id:
          $ref: '#/components/schemas/AgentID'
          description: >-
            The agent that made the call. Differs from the streamed agent when
            the call belongs to a subagent.
        state:
          $ref: '#/components/schemas/ToolCallState'
        interaction_update:
          $ref: '#/components/schemas/AgentInteractionUpdate'
          description: >-
            Only present when this transition opens, resolves, or cancels an
            interaction.
    ModelOutputDelta:
      type: object
      additionalProperties: false
      required:
        - turn_id
        - model_call_context_id
        - seq
        - source_seq_start
        - source_seq_end
        - coalesced_count
        - event
      properties:
        turn_id:
          $ref: '#/components/schemas/AgentTurnID'
        model_call_context_id:
          $ref: '#/components/schemas/ModelCallContextID'
        seq:
          $ref: '#/components/schemas/AgentSequence'
          description: >-
            Monotonic frame sequence within this model call context's preview
            stream, starting at 1. Delta frames carry no SSE id; gaps in seq
            mean dropped best-effort frames.
        source_seq_start:
          $ref: '#/components/schemas/AgentSequence'
          description: First provider stream event coalesced into this frame.
        source_seq_end:
          $ref: '#/components/schemas/AgentSequence'
          description: Last provider stream event coalesced into this frame.
        coalesced_count:
          $ref: '#/components/schemas/AgentCount'
          description: >-
            Number of provider stream events coalesced into this frame. A frame
            is intact only when this equals source_seq_end - source_seq_start +
            1; a smaller count means events inside the range were dropped before
            coalescing.
        event:
          $ref: '#/components/schemas/ModelOutputStreamDelta'
    Error:
      type: object
      additionalProperties: false
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Human-readable error message. Do not match on it programmatically.
        current_digest:
          type: string
          pattern: ^sha256:[0-9a-f]{64}$
          description: >-
            Current file digest for file_content_conflict or
            expected_digest_required; absent if the file no longer exists. A
            replacement must be confirmed before retrying with this digest.
        issues:
          type: array
          description: >-
            Field-level problems when a submitted document (such as an agent
            config source) failed validation. Absent for errors that are not
            about a specific field.
          items:
            $ref: '#/components/schemas/AgentConfigErrorIssue'
        code:
          type: string
          description: Stable error code for programmatic handling.
          x-go-type: ErrorCode
          x-extensible-enum:
            - invalid_request
            - unauthorized
            - forbidden
            - not_found
            - conflict
            - file_content_conflict
            - file_read_only
            - expected_digest_required
            - not_a_file
            - gone
            - request_too_large
            - unsupported_media_type
            - unprocessable
            - upstream_unavailable
            - rate_limited
            - internal_error
            - service_unavailable
            - idempotency_key_conflict
            - agent_backlog_full
            - state_transition_conflict
            - managed_work_admission_denied
            - pending_work
            - not_wake_capable
            - daemon_runtime_unregistered
            - validation_failed
            - csrf_check_failed
            - authentication_unavailable
    ClientErrorCode:
      type: string
      description: >-
        Stable error code carried by 4XX statuses. Subset of the Error code enum
        whose statuses are client errors.
      x-extensible-enum:
        - invalid_request
        - validation_failed
        - unauthorized
        - forbidden
        - csrf_check_failed
        - not_found
        - conflict
        - file_content_conflict
        - file_read_only
        - expected_digest_required
        - not_a_file
        - idempotency_key_conflict
        - agent_backlog_full
        - state_transition_conflict
        - pending_work
        - not_wake_capable
        - gone
        - daemon_runtime_unregistered
        - request_too_large
        - unsupported_media_type
        - unprocessable
        - upstream_unavailable
        - rate_limited
    ServerErrorCode:
      type: string
      description: >-
        Stable error code carried by 5XX statuses. Subset of the Error code enum
        whose statuses are server errors.
      x-extensible-enum:
        - internal_error
        - service_unavailable
        - authentication_unavailable
    AgentInputEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - org_id
        - project_id
        - agent_id
        - turn_id
        - turn_sequence
        - is_opening_event
        - sequence
        - event_kind
        - agent_input_id
        - input_kind
        - content_blocks
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/AgentEventID'
        org_id:
          $ref: '#/components/schemas/OrganizationID'
        project_id:
          $ref: '#/components/schemas/ProjectID'
        agent_id:
          $ref: '#/components/schemas/AgentID'
        turn_id:
          $ref: '#/components/schemas/AgentTurnID'
        turn_sequence:
          $ref: '#/components/schemas/AgentSequence'
        is_opening_event:
          type: boolean
        sequence:
          $ref: '#/components/schemas/AgentSequence'
        event_kind:
          type: string
          enum:
            - agent_input
        agent_input_id:
          $ref: '#/components/schemas/AgentInputID'
          description: >-
            Matches the input that produced this event, allowing clients to
            correlate an input submission with its durable timeline admission.
        input_kind:
          $ref: '#/components/schemas/AgentInputKind'
        actor_id:
          $ref: '#/components/schemas/ActorID'
          description: >-
            Actor attributed to the input. Resolve details through the project
            actors endpoints.
        input_idempotency_key:
          type: string
          description: >-
            Echoes the Idempotency-Key of a content-input request so its sender
            can recognize the durable admission. Absent for other input kinds.
        control_type:
          $ref: '#/components/schemas/AgentControlType'
        interaction_id:
          $ref: '#/components/schemas/AgentInteractionID'
          description: Interaction answered by an interaction_response input.
        agent_config_id:
          $ref: '#/components/schemas/AgentConfigID'
          description: Configuration selected by a config_change input.
        content_blocks:
          type: array
          items:
            $ref: '#/components/schemas/AgentInputContentBlock'
        created_at:
          $ref: '#/components/schemas/Timestamp'
    ModelOutputEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - org_id
        - project_id
        - agent_id
        - turn_id
        - turn_sequence
        - is_opening_event
        - sequence
        - event_kind
        - model_call_context_id
        - stop_reason
        - content_blocks
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/AgentEventID'
        org_id:
          $ref: '#/components/schemas/OrganizationID'
        project_id:
          $ref: '#/components/schemas/ProjectID'
        agent_id:
          $ref: '#/components/schemas/AgentID'
        turn_id:
          $ref: '#/components/schemas/AgentTurnID'
        turn_sequence:
          $ref: '#/components/schemas/AgentSequence'
        is_opening_event:
          type: boolean
          enum:
            - false
          x-enum-varnames:
            - ModelOutputEventIsOpeningEventFalse
        sequence:
          $ref: '#/components/schemas/AgentSequence'
        event_kind:
          type: string
          enum:
            - model_output
        model_call_context_id:
          $ref: '#/components/schemas/ModelCallContextID'
        stop_reason:
          $ref: '#/components/schemas/ModelOutputStopReason'
        content_blocks:
          type: array
          items:
            $ref: '#/components/schemas/ModelOutputContentBlock'
        usage:
          $ref: '#/components/schemas/ModelUsage'
        provider_metadata:
          type: object
          description: >-
            Facts the provider reported about this call, keyed by provider (for
            example `openrouter.provider` names the upstream that served an
            OpenRouter request). Present only when the provider reported
            something.
          x-go-type: json.RawMessage
          x-go-type-skip-optional-pointer: true
        created_at:
          $ref: '#/components/schemas/Timestamp'
    ToolResultEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - org_id
        - project_id
        - agent_id
        - turn_id
        - turn_sequence
        - is_opening_event
        - sequence
        - event_kind
        - tool_call_id
        - outcome
        - content_blocks
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/AgentEventID'
        org_id:
          $ref: '#/components/schemas/OrganizationID'
        project_id:
          $ref: '#/components/schemas/ProjectID'
        agent_id:
          $ref: '#/components/schemas/AgentID'
        turn_id:
          $ref: '#/components/schemas/AgentTurnID'
        turn_sequence:
          $ref: '#/components/schemas/AgentSequence'
        is_opening_event:
          type: boolean
          enum:
            - false
          x-enum-varnames:
            - ToolResultEventIsOpeningEventFalse
        sequence:
          $ref: '#/components/schemas/AgentSequence'
        event_kind:
          type: string
          enum:
            - tool_result
        tool_call_id:
          $ref: '#/components/schemas/ToolCallID'
        outcome:
          $ref: '#/components/schemas/ToolCallOutcome'
        content_blocks:
          type: array
          items:
            $ref: '#/components/schemas/ToolResultContentBlock'
        created_at:
          $ref: '#/components/schemas/Timestamp'
    ContextCheckpointEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - org_id
        - project_id
        - agent_id
        - turn_id
        - turn_sequence
        - is_opening_event
        - sequence
        - event_kind
        - context_checkpoint_id
        - summarized_through_event_sequence
        - summary
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/AgentEventID'
        org_id:
          $ref: '#/components/schemas/OrganizationID'
        project_id:
          $ref: '#/components/schemas/ProjectID'
        agent_id:
          $ref: '#/components/schemas/AgentID'
        turn_id:
          $ref: '#/components/schemas/AgentTurnID'
        turn_sequence:
          $ref: '#/components/schemas/AgentSequence'
        is_opening_event:
          type: boolean
          enum:
            - false
          x-enum-varnames:
            - ContextCheckpointEventIsOpeningEventFalse
        sequence:
          $ref: '#/components/schemas/AgentSequence'
        event_kind:
          type: string
          enum:
            - context_checkpoint
        context_checkpoint_id:
          $ref: '#/components/schemas/ContextCheckpointID'
        summarized_through_event_sequence:
          $ref: '#/components/schemas/AgentSequence'
        summary:
          type: string
        created_at:
          $ref: '#/components/schemas/Timestamp'
    ToolCallID:
      type: string
      pattern: ^tcl_[a-z2-7]{26}$
    AgentID:
      type: string
      pattern: ^agt_[a-z2-7]{26}$
    ToolCallState:
      description: >-
        Current lifecycle state. awaiting_authorization has not evaluated its
        permission mode; awaiting_permission has an open authorization prompt;
        ready is authorized and eligible to run; running has an active worker;
        waiting has durable work that will complete the call independently;
        completed is terminal and includes outcome and completed_at. Custom
        calls remain ready until a consumer submits their result.
      type: string
      enum:
        - awaiting_authorization
        - awaiting_permission
        - ready
        - running
        - waiting
        - completed
      x-enum-varnames:
        - ToolCallStateAwaitingAuthorization
        - ToolCallStateAwaitingPermission
        - ToolCallStateReady
        - ToolCallStateRunning
        - ToolCallStateWaiting
        - ToolCallStateCompleted
    AgentInteractionUpdate:
      type: object
      additionalProperties: false
      required:
        - id
        - interaction_kind
        - state
      properties:
        id:
          $ref: '#/components/schemas/AgentInteractionID'
        interaction_kind:
          $ref: '#/components/schemas/AgentInteractionKind'
        state:
          $ref: '#/components/schemas/AgentInteractionState'
    AgentTurnID:
      type: string
      pattern: ^trn_[a-z2-7]{26}$
    ModelCallContextID:
      type: string
      pattern: ^mcc_[a-z2-7]{26}$
    AgentSequence:
      description: Positive per-agent event, turn, or live-frame sequence.
      type: integer
      minimum: 1
      maximum: 9007199254740991
      x-go-type: int64
    AgentCount:
      description: Positive count within an agent timeline.
      type: integer
      minimum: 1
      maximum: 9007199254740991
      x-go-type: int64
    ModelOutputStreamDelta:
      oneOf:
        - $ref: '#/components/schemas/ModelOutputBlockStartDelta'
        - $ref: '#/components/schemas/ModelOutputTextDelta'
        - $ref: '#/components/schemas/ModelOutputThinkingDelta'
        - $ref: '#/components/schemas/ModelOutputToolArgumentsDelta'
        - $ref: '#/components/schemas/ModelOutputBlockStopDelta'
        - $ref: '#/components/schemas/ModelOutputMessageStopDelta'
        - $ref: '#/components/schemas/ModelOutputErrorDelta'
      discriminator:
        propertyName: kind
        mapping:
          block_start: '#/components/schemas/ModelOutputBlockStartDelta'
          text_delta: '#/components/schemas/ModelOutputTextDelta'
          thinking_delta: '#/components/schemas/ModelOutputThinkingDelta'
          tool_arguments_delta: '#/components/schemas/ModelOutputToolArgumentsDelta'
          block_stop: '#/components/schemas/ModelOutputBlockStopDelta'
          message_stop: '#/components/schemas/ModelOutputMessageStopDelta'
          error: '#/components/schemas/ModelOutputErrorDelta'
    AgentConfigErrorIssue:
      type: object
      additionalProperties: false
      required:
        - path
        - message
      properties:
        path:
          type: string
          description: >-
            JSON Pointer (RFC 6901) to the offending field in the submitted
            document. An empty string refers to the whole document.
        message:
          type: string
          description: Human-readable description of the problem with this field.
        line:
          type: integer
          minimum: 1
          description: >-
            1-based line of the offending field in the submitted source, when it
            can be located.
        column:
          type: integer
          minimum: 1
          description: >-
            1-based column of the offending field in the submitted source, when
            it can be located.
    AgentEventID:
      type: string
      pattern: ^evt_[a-z2-7]{26}$
    OrganizationID:
      type: string
      pattern: ^org_[a-z2-7]{26}$
    ProjectID:
      description: Project ID (proj_...).
      type: string
      pattern: ^proj_[a-z2-7]{26}$
    AgentInputID:
      type: string
      pattern: ^ain_[a-z2-7]{26}$
    AgentInputKind:
      type: string
      enum:
        - content
        - control
        - interaction_response
        - config_change
      x-enum-varnames:
        - AgentInputKindContent
        - AgentInputKindControl
        - AgentInputKindInteractionResponse
        - AgentInputKindConfigChange
    ActorID:
      type: string
      pattern: ^actr_[a-z2-7]{26}$
    AgentControlType:
      type: string
      enum:
        - cancel_current
      x-enum-varnames:
        - AgentControlTypeCancelCurrent
    AgentInteractionID:
      type: string
      pattern: ^int_[a-z2-7]{26}$
    AgentConfigID:
      description: Agent config ID (acfg_...).
      type: string
      pattern: ^acfg_[a-z2-7]{26}$
    AgentInputContentBlock:
      oneOf:
        - $ref: '#/components/schemas/TextContentBlock'
        - $ref: '#/components/schemas/MediaRefContentBlock'
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/TextContentBlock'
          media_ref: '#/components/schemas/MediaRefContentBlock'
    Timestamp:
      type: string
      format: date-time
    ModelOutputStopReason:
      description: Stop reasons admitted as durable model-output events.
      type: string
      enum:
        - end_turn
        - tool_use
        - max_tokens
        - refusal
        - content_filter
        - error
      x-enum-varnames:
        - ModelOutputStopReasonEndTurn
        - ModelOutputStopReasonToolUse
        - ModelOutputStopReasonMaxTokens
        - ModelOutputStopReasonRefusal
        - ModelOutputStopReasonContentFilter
        - ModelOutputStopReasonError
    ModelOutputContentBlock:
      oneOf:
        - $ref: '#/components/schemas/TextContentBlock'
        - $ref: '#/components/schemas/MediaRefContentBlock'
        - $ref: '#/components/schemas/ReasoningContentBlock'
        - $ref: '#/components/schemas/ModelToolCallContentBlock'
        - $ref: '#/components/schemas/ErrorContentBlock'
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/TextContentBlock'
          media_ref: '#/components/schemas/MediaRefContentBlock'
          reasoning: '#/components/schemas/ReasoningContentBlock'
          tool_call: '#/components/schemas/ModelToolCallContentBlock'
          error: '#/components/schemas/ErrorContentBlock'
    ModelUsage:
      type: object
      additionalProperties: false
      description: >-
        Token counts the provider reported for one model call. Cache and
        reasoning counts are omitted when the provider reported none.
      properties:
        input_tokens_total:
          type: integer
          minimum: 0
        uncached_input_tokens:
          type: integer
          minimum: 0
        output_tokens_total:
          type: integer
          minimum: 0
        reasoning_output_tokens:
          type: integer
          minimum: 0
        cache_read_input_tokens:
          type: integer
          minimum: 0
        cache_write_input_tokens:
          type: integer
          minimum: 0
    ToolCallOutcome:
      description: Terminal outcome, present only when state is completed.
      type: string
      enum:
        - succeeded
        - failed
        - denied
        - canceled
      x-enum-varnames:
        - ToolCallOutcomeSucceeded
        - ToolCallOutcomeFailed
        - ToolCallOutcomeDenied
        - ToolCallOutcomeCanceled
    ToolResultContentBlock:
      oneOf:
        - $ref: '#/components/schemas/TextContentBlock'
        - $ref: '#/components/schemas/MediaRefContentBlock'
        - $ref: '#/components/schemas/StructuredDataContentBlock'
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/TextContentBlock'
          media_ref: '#/components/schemas/MediaRefContentBlock'
          structured_data: '#/components/schemas/StructuredDataContentBlock'
    ContextCheckpointID:
      type: string
      pattern: ^ccp_[a-z2-7]{26}$
    AgentInteractionKind:
      type: string
      enum:
        - permission
        - question
      x-enum-varnames:
        - AgentInteractionKindPermission
        - AgentInteractionKindQuestion
    AgentInteractionState:
      type: string
      enum:
        - open
        - resolved
        - canceled
      x-enum-varnames:
        - AgentInteractionStateOpen
        - AgentInteractionStateResolved
        - AgentInteractionStateCanceled
    ModelOutputBlockStartDelta:
      type: object
      additionalProperties: false
      required:
        - kind
        - block_index
        - block
      properties:
        kind:
          type: string
          enum:
            - block_start
        block_index:
          type: integer
          minimum: 0
        block:
          $ref: '#/components/schemas/ModelOutputStreamBlock'
    ModelOutputTextDelta:
      type: object
      additionalProperties: false
      required:
        - kind
        - block_index
        - delta
      properties:
        kind:
          type: string
          enum:
            - text_delta
        block_index:
          type: integer
          minimum: 0
        delta:
          type: string
    ModelOutputThinkingDelta:
      type: object
      additionalProperties: false
      required:
        - kind
        - block_index
        - delta
      properties:
        kind:
          type: string
          enum:
            - thinking_delta
        block_index:
          type: integer
          minimum: 0
        delta:
          type: string
    ModelOutputToolArgumentsDelta:
      type: object
      additionalProperties: false
      required:
        - kind
        - block_index
        - delta
      properties:
        kind:
          type: string
          enum:
            - tool_arguments_delta
        block_index:
          type: integer
          minimum: 0
        delta:
          type: string
    ModelOutputBlockStopDelta:
      type: object
      additionalProperties: false
      required:
        - kind
        - block_index
      properties:
        kind:
          type: string
          enum:
            - block_stop
        block_index:
          type: integer
          minimum: 0
    ModelOutputMessageStopDelta:
      type: object
      additionalProperties: false
      required:
        - kind
        - stop
      properties:
        kind:
          type: string
          enum:
            - message_stop
        stop:
          type: object
          additionalProperties: false
          required:
            - reason
            - usage
          properties:
            reason:
              $ref: '#/components/schemas/ModelStopReason'
            usage:
              $ref: '#/components/schemas/ModelUsage'
    ModelOutputErrorDelta:
      type: object
      additionalProperties: false
      required:
        - kind
        - error
      properties:
        kind:
          type: string
          enum:
            - error
        error:
          type: object
          additionalProperties: false
          required:
            - message
          properties:
            message:
              type: string
    TextContentBlock:
      type: object
      additionalProperties: false
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
        metadata:
          $ref: '#/components/schemas/ContentBlockMetadata'
    MediaRefContentBlock:
      type: object
      additionalProperties: false
      required:
        - type
        - artifact_id
      properties:
        type:
          type: string
          enum:
            - media_ref
        artifact_id:
          $ref: '#/components/schemas/ArtifactID'
        exclude_from_model_context:
          type: boolean
          description: >-
            Whether the referenced artifact is excluded from later model
            context.
        metadata:
          $ref: '#/components/schemas/ContentBlockMetadata'
    ReasoningContentBlock:
      type: object
      additionalProperties: false
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - reasoning
        text:
          type: string
        metadata:
          $ref: '#/components/schemas/ContentBlockMetadata'
    ModelToolCallContentBlock:
      type: object
      additionalProperties: false
      required:
        - type
        - tool_call_id
        - tool_type
        - name
        - input
      properties:
        type:
          type: string
          enum:
            - tool_call
        tool_call_id:
          $ref: '#/components/schemas/ToolCallID'
        tool_type:
          $ref: '#/components/schemas/ToolCallType'
        name:
          type: string
        input:
          $ref: '#/components/schemas/ToolInput'
        metadata:
          $ref: '#/components/schemas/ContentBlockMetadata'
    ErrorContentBlock:
      type: object
      additionalProperties: false
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - error
        text:
          type: string
        metadata:
          $ref: '#/components/schemas/ContentBlockMetadata'
    StructuredDataContentBlock:
      type: object
      additionalProperties: false
      required:
        - type
        - value
      properties:
        type:
          type: string
          enum:
            - structured_data
        value:
          $ref: '#/components/schemas/JSONBlob'
        metadata:
          $ref: '#/components/schemas/ContentBlockMetadata'
    ModelOutputStreamBlock:
      oneOf:
        - $ref: '#/components/schemas/ModelOutputTextStreamBlock'
        - $ref: '#/components/schemas/ModelOutputThinkingStreamBlock'
        - $ref: '#/components/schemas/ModelOutputToolUseStreamBlock'
      discriminator:
        propertyName: kind
        mapping:
          text: '#/components/schemas/ModelOutputTextStreamBlock'
          thinking: '#/components/schemas/ModelOutputThinkingStreamBlock'
          tool_use: '#/components/schemas/ModelOutputToolUseStreamBlock'
    ModelStopReason:
      type: string
      enum:
        - end_turn
        - tool_use
        - max_tokens
        - refusal
        - content_filter
        - pause
        - context_window
        - unknown
      x-enum-varnames:
        - ModelStopReasonEndTurn
        - ModelStopReasonToolUse
        - ModelStopReasonMaxTokens
        - ModelStopReasonRefusal
        - ModelStopReasonContentFilter
        - ModelStopReasonPause
        - ModelStopReasonContextWindow
        - ModelStopReasonUnknown
    ContentBlockMetadata:
      $ref: '#/components/schemas/Metadata'
      description: >-
        Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64
        characters, values must be strings of up to 512 characters. Keys
        beginning with `omnara_` are reserved for Omnara and may affect product
        behavior; use them only when intentionally invoking Omnara-defined
        behavior.
    ArtifactID:
      type: string
      pattern: ^art_[a-z2-7]{26}$
    ToolCallType:
      description: >-
        Identifies who manages execution. Built-in and MCP calls are
        platform-managed; custom calls wait for an external consumer to submit
        their result.
      type: string
      enum:
        - built_in
        - custom
        - mcp
      x-enum-varnames:
        - ToolCallTypeBuiltIn
        - ToolCallTypeCustom
        - ToolCallTypeMCP
    ToolInput:
      description: Non-null JSON object containing the arguments emitted for a tool call.
      type: object
      additionalProperties: true
      x-go-type: json.RawMessage
      x-go-type-skip-optional-pointer: true
    JSONBlob:
      description: >-
        Public JSON payload whose shape is determined by the event or
        interaction kind.
    ModelOutputTextStreamBlock:
      type: object
      additionalProperties: false
      required:
        - kind
      properties:
        kind:
          type: string
          enum:
            - text
    ModelOutputThinkingStreamBlock:
      type: object
      additionalProperties: false
      required:
        - kind
      properties:
        kind:
          type: string
          enum:
            - thinking
    ModelOutputToolUseStreamBlock:
      type: object
      additionalProperties: false
      required:
        - kind
        - tool_call_id
        - tool_name
      properties:
        kind:
          type: string
          enum:
            - tool_use
        tool_call_id:
          $ref: '#/components/schemas/ToolCallID'
          description: >-
            Stable public ID shared with the eventual durable ToolCall when this
            is a tool_use block.
        tool_name:
          type: string
    Metadata:
      type: object
      description: >-
        Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64
        characters, values must be strings of up to 512 characters.
      x-go-type: resourcemeta.Metadata
      x-go-type-import:
        path: github.com/omnara-ai/omnara/internal/resourcemeta
      x-go-type-skip-optional-pointer: true
      maxProperties: 16
      propertyNames:
        minLength: 1
        maxLength: 64
      additionalProperties:
        type: string
        maxLength: 512
  responses:
    BadRequest:
      description: The request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication is required or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The authenticated principal is not authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found or is not visible.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: The service dependency required to satisfy the request is unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ClientError:
      description: >-
        Any other client error. The body carries the shared Error envelope
        restricted to client error codes; statuses with a dedicated response
        above are documented precisely.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            required:
              - error
              - code
            properties:
              error:
                type: string
                description: >-
                  Human-readable error message. Do not match on it
                  programmatically.
              code:
                $ref: '#/components/schemas/ClientErrorCode'
    ServerError:
      description: >-
        Any other server error. The body carries the shared Error envelope
        restricted to server error codes.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            required:
              - error
              - code
            properties:
              error:
                type: string
                description: >-
                  Human-readable error message. Do not match on it
                  programmatically.
              code:
                $ref: '#/components/schemas/ServerErrorCode'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Omnara personal or organization access token
      description: An opaque Omnara personal or organization bearer token.
    browserSessionCookie:
      type: apiKey
      in: cookie
      name: __Host-omnara_session
      description: >-
        Browser session cookie. HTTPS deployments use __Host-omnara_session;
        local HTTP development uses omnara_session.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.