> ## 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.

# Create agent

> Launch from a pinned config, optionally adding agent-local integration tools, subscriptions and interaction handlers and admitting an attributed initial text input in the same transaction. Adding integration capabilities requires project management permission; launching an existing config requires agent operate permission. Reusing an idempotency key returns the current agent even if the retry body differs. The retry body is not applied and integration references are not resolved again.



## OpenAPI

````yaml /api-reference/openapi.yaml post /orgs/{orgID}/projects/{projectID}/agents
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:
    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}$
    post:
      tags:
        - Agents
      summary: Create agent
      description: >-
        Launch from a pinned config, optionally adding agent-local integration
        tools, subscriptions and interaction handlers and admitting an
        attributed initial text input in the same transaction. Adding
        integration capabilities requires project management permission;
        launching an existing config requires agent operate permission. Reusing
        an idempotency key returns the current agent even if the retry body
        differs. The retry body is not applied and integration references are
        not resolved again.
      operationId: createAgent
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '200':
          description: Current state of the previously created agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrentAgentResponse'
        '201':
          description: Agent launched.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LaunchAgentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            The launch conflicts with current resource state for a reason other
            than a changed retry body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
        - browserSessionCookie: []
          csrfHeader: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 255
      description: Idempotency key for replay-safe mutating requests.
  schemas:
    CreateAgentRequest:
      description: >-
        Send at least one of profile, config, or config_source, and not both
        config and config_source. With only profile, the agent runs the
        profile's current config. With profile and config or config_source, the
        agent is attributed to the profile but runs the given config, which need
        not be one of the profile's versions. config_source is compiled and
        saved as a new config during the launch.
      type: object
      additionalProperties: false
      anyOf:
        - type: object
          required:
            - profile
          properties:
            profile:
              $ref: '#/components/schemas/AgentProfileID'
        - type: object
          required:
            - config
          properties:
            config:
              $ref: '#/components/schemas/AgentConfigID'
        - type: object
          required:
            - config_source
          properties:
            config_source:
              $ref: '#/components/schemas/CreateAgentConfigRequest'
      not:
        type: object
        required:
          - config
          - config_source
      properties:
        profile:
          $ref: '#/components/schemas/AgentProfileID'
        config:
          $ref: '#/components/schemas/AgentConfigID'
        config_source:
          $ref: '#/components/schemas/CreateAgentConfigRequest'
        name:
          $ref: '#/components/schemas/AgentName'
          description: >-
            Optional agent name. Omit to inherit the profile name when present;
            send an empty string to leave the agent unnamed.
        message:
          type: string
          description: >-
            Optional initial text message. Mutually exclusive with
            initial_input.
        tools:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentConfigDefinitionTool'
          description: >-
            Additional integration tool entries
            (int__<integration-name>__<operation>) and optional
            list_interaction_handlers or set_interaction_handler tools for this
            agent. Other tool names are not accepted here. Existing config
            entries win unchanged. Requires project management permission. The
            derived config is created atomically with the agent and initial
            input; the profile is unchanged.
        subscriptions:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/IntegrationSubscriptionAttachment'
          description: >-
            Integration-owned conversation subscriptions attached atomically
            with launch and initial input. Requires project management
            permission. Subscriptions alone preserve the pinned config. Launch
            replay never adds or restores subscriptions.
        interaction_handlers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentConfigDefinitionInteractionHandler'
          description: >-
            Additional integration interaction handlers, keyed by immutable
            integration name with empty object values. Slack and Discord
            handlers require an assigned conversation and accept empty runtime
            args. Adding a handler does not assign a conversation. Existing
            entries win unchanged. Requires project management permission.
        initial_input:
          $ref: '#/components/schemas/AgentLaunchInitialInput'
    CurrentAgentResponse:
      type: object
      additionalProperties: false
      required:
        - agent
      properties:
        agent:
          $ref: '#/components/schemas/Agent'
    LaunchAgentResponse:
      type: object
      additionalProperties: false
      required:
        - agent
        - agent_config
        - machine_bindings
      properties:
        agent:
          $ref: '#/components/schemas/Agent'
        agent_config:
          $ref: '#/components/schemas/AgentConfig'
        machine_bindings:
          type: array
          items:
            $ref: '#/components/schemas/AgentMachineBinding'
        agent_input:
          $ref: '#/components/schemas/AgentInput'
    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
    AgentProfileID:
      type: string
      pattern: ^aprf_[a-z2-7]{26}$
    AgentConfigID:
      description: Agent config ID (acfg_...).
      type: string
      pattern: ^acfg_[a-z2-7]{26}$
    CreateAgentConfigRequest:
      description: >-
        An agent config to compile. YAML sources are stored verbatim, so
        comments and formatting survive; JSON sources, as text or as an object,
        are stored canonicalized, so the same JSON definition always maps to the
        same config.
      type: object
      additionalProperties: false
      required:
        - source
        - source_format
      properties:
        source:
          $ref: '#/components/schemas/AgentConfigSourceInput'
        source_format:
          description: 'Format of source: yaml or json.'
          type: string
          enum:
            - yaml
            - json
    AgentName:
      type: string
      maxLength: 64
      x-omnara-unicode-normalization: NFC
      description: >-
        Agent name. Empty means the agent is unnamed; non-empty values use the
        ResourceName policy.
    AgentConfigDefinitionTool:
      type: object
      additionalProperties: false
      properties:
        deferred:
          type: boolean
        description:
          type: string
          minLength: 1
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
        input_schema:
          $ref: '#/components/schemas/AgentConfigDefinitionToolInputSchema'
        permission:
          $ref: '#/components/schemas/AgentConfigDefinitionToolPermission'
        type:
          enum:
            - built_in
            - custom
      if:
        type: object
        required:
          - type
        properties:
          type:
            const: custom
      then:
        required:
          - description
          - input_schema
      else:
        not:
          anyOf:
            - type: object
              required:
                - description
            - type: object
              required:
                - input_schema
      x-go-type: agentconfig.AgentConfigToolSource
      x-go-type-import:
        path: github.com/omnara-ai/omnara/internal/agentconfig
    IntegrationSubscriptionAttachment:
      type: object
      additionalProperties: false
      required:
        - integration_id
        - conversation
      properties:
        integration_id:
          $ref: '#/components/schemas/IntegrationID'
        conversation:
          $ref: '#/components/schemas/IntegrationConversation'
    AgentConfigDefinitionInteractionHandler:
      description: Enables an integration's interaction handler. Takes no settings.
      type: object
      additionalProperties: false
      x-go-type: agentconfig.AgentConfigIntegrationCapabilitySource
      x-go-type-import:
        path: github.com/omnara-ai/omnara/internal/agentconfig
    AgentLaunchInitialInput:
      type: object
      additionalProperties: false
      required:
        - content_blocks
      description: >-
        Initial queued text input, committed atomically with the agent and any
        derived config. Mutually exclusive with message. Initial inline media is
        not supported; upload it through the agent input endpoint after launch.
      properties:
        content_blocks:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/TextContentBlock'
        actor:
          $ref: '#/components/schemas/ExternalActorParams'
          description: >-
            Optional external actor for API key authentication.
            User-authenticated requests must omit this field. Without it, the
            authenticated user or API key is the actor.
    Agent:
      type: object
      additionalProperties: false
      required:
        - id
        - org_id
        - project_id
        - state
        - name
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/AgentID'
        org_id:
          $ref: '#/components/schemas/OrganizationID'
        project_id:
          $ref: '#/components/schemas/ProjectID'
        agent_profile_id:
          $ref: '#/components/schemas/AgentProfileID'
        state:
          type: string
          enum:
            - active
            - archived
        name:
          $ref: '#/components/schemas/AgentName'
        integration_target:
          $ref: '#/components/schemas/IntegrationTarget'
          description: >-
            Selected question/approval destination. Automatic mode updates it
            when content inputs are admitted. Prompts use it only while the
            integration and handler remain eligible. It is not launch provenance
            or permission to post.
        current_config_id:
          $ref: '#/components/schemas/AgentConfigID'
        model:
          $ref: '#/components/schemas/AgentModel'
        parent_agent_id:
          $ref: '#/components/schemas/AgentID'
          description: Set when this agent is a subagent spawned by another agent.
        subagent_key:
          description: The `subagents` key this agent was spawned from.
          type: string
        activity:
          $ref: '#/components/schemas/AgentActivity'
          description: Current activity, present on list and get responses.
        usage:
          $ref: '#/components/schemas/UsageTotals'
          description: >-
            All-time model usage by the agent and its subagents. Present when
            the list was requested with `include_usage`.
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
        archived_at:
          $ref: '#/components/schemas/Timestamp'
    AgentConfig:
      type: object
      additionalProperties: false
      required:
        - id
        - org_id
        - project_id
        - effective_definition_hash
        - model
        - created_at
        - compiled_definition
      properties:
        id:
          $ref: '#/components/schemas/AgentConfigID'
        org_id:
          $ref: '#/components/schemas/OrganizationID'
        project_id:
          $ref: '#/components/schemas/ProjectID'
        source:
          type: string
          description: >-
            Saved source text. YAML sources keep their original text; JSON
            sources are stored canonicalized.
        source_format:
          type: string
          enum:
            - yaml
            - json
        effective_definition_hash:
          type: string
        model:
          $ref: '#/components/schemas/AgentConfigModel'
        instruction_hash:
          type: string
        created_at:
          $ref: '#/components/schemas/Timestamp'
        compiled_definition:
          $ref: '#/components/schemas/CompiledAgentConfig'
    AgentMachineBinding:
      type: object
      additionalProperties: false
      required:
        - id
        - project_id
        - agent_id
        - machine_id
        - binding_kind
        - state
        - description
        - cwd
        - env_overlay
        - secret_env_overlay
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/AgentMachineBindingID'
        project_id:
          $ref: '#/components/schemas/ProjectID'
        agent_id:
          $ref: '#/components/schemas/AgentID'
        machine_id:
          $ref: '#/components/schemas/MachineID'
        binding_kind:
          $ref: '#/components/schemas/AgentMachineBindingKind'
        state:
          $ref: '#/components/schemas/AgentMachineBindingState'
        description:
          type: string
        cwd:
          type: string
        env_overlay:
          description: >-
            Env overlay applied to processes launched through this binding. For
            pool bindings it is also applied to the machine environment when the
            pool machine is provisioned, so the provider_options startup_script
            and the daemon run with it; connected machines keep their own
            environment. A null entry removes the key.
          type: object
          additionalProperties:
            type:
              - string
              - 'null'
        secret_env_overlay:
          description: >-
            Secret env overlay applied to processes launched through this
            binding. For pool bindings it is also applied to the machine
            environment when the pool machine is provisioned, so the
            provider_options startup_script and the daemon run with it;
            connected machines keep their own environment. A null entry removes
            the key.
          type: object
          additionalProperties:
            anyOf:
              - $ref: '#/components/schemas/SecretID'
              - type: 'null'
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
    AgentInput:
      type: object
      additionalProperties: false
      required:
        - id
        - agent_id
        - state
        - delivery_mode
        - input_kind
        - queued_at
      properties:
        id:
          $ref: '#/components/schemas/AgentInputID'
        agent_id:
          $ref: '#/components/schemas/AgentID'
        state:
          type: string
        delivery_mode:
          $ref: '#/components/schemas/AgentInputDeliveryMode'
        input_kind:
          $ref: '#/components/schemas/AgentInputKind'
        actor_id:
          $ref: '#/components/schemas/ActorID'
          description: >-
            Actor this input is attributed to. Absent when the input has no
            actor attribution.
        input_idempotency_key:
          type: string
          description: >-
            Idempotency key supplied when this content input was created. Absent
            for other input kinds.
        content_blocks:
          type: array
          items:
            $ref: '#/components/schemas/AgentInputContentBlock'
        queued_at:
          $ref: '#/components/schemas/Timestamp'
    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.
    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
    AgentConfigSourceInput:
      description: >-
        Agent config source as YAML or JSON text, or, with source_format json,
        as a JSON object.
      anyOf:
        - type: string
          minLength: 1
        - $ref: '#/components/schemas/AgentConfigDefinition'
      x-go-type: json.RawMessage
    AgentConfigDefinitionToolInputSchema:
      description: >-
        A JSON Schema for the tool's input. Keywords beyond those listed, such
        as additionalProperties or description, are allowed.
      type: object
      additionalProperties: true
      required:
        - type
      properties:
        properties:
          type: object
          additionalProperties:
            type: object
        required:
          type: array
          items:
            type: string
            minLength: 1
        type:
          const: object
      x-go-type: json.RawMessage
    AgentConfigDefinitionToolPermission:
      type: object
      additionalProperties: false
      required:
        - mode
      properties:
        mode:
          type: string
          minLength: 1
          pattern: \S
        parameters:
          type: object
      x-go-type: json.RawMessage
    IntegrationID:
      type: string
      pattern: ^itg_[a-z2-7]{26}$
    IntegrationConversation:
      type: object
      additionalProperties: true
      x-go-type: json.RawMessage
      x-go-type-skip-optional-pointer: true
      description: >-
        One concrete provider address, validated by the integration's
        capabilities.subscription.conversation_schema. Slack uses channel_id and
        optional thread_ts; Discord uses channel_id for a channel or thread_id
        for a thread; GitHub uses repository_id and pull_request. Discord
        accepts optional parent channel_id and guild_id alongside thread_id and
        validates their ID format, but subscription creation does not verify
        them against Discord or retain them as routing restrictions. Only
        thread_id is retained in a canonical thread address and returned by
        create/list responses. No credentials or runtime state.
    TextContentBlock:
      type: object
      additionalProperties: false
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
        metadata:
          $ref: '#/components/schemas/ContentBlockMetadata'
    ExternalActorParams:
      type: object
      description: >-
        Identity and attributes of an external actor. Actors are upserted by
        (provider_tenant_id, provider_user_id) with the external provider.
        Omitted attributes keep their stored values; provided attributes are
        overwritten, including empty values. omnara actors are implicit and
        hosted integrations own their own actor identities.
      additionalProperties: false
      required:
        - provider_user_id
      properties:
        provider_tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        provider_user_id:
          type: string
          minLength: 1
          maxLength: 128
        display_name:
          type: string
          maxLength: 256
        metadata:
          $ref: '#/components/schemas/Metadata'
    AgentID:
      type: string
      pattern: ^agt_[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}$
    IntegrationTarget:
      type: object
      additionalProperties: false
      required:
        - provider
        - conversation
        - display_name
      properties:
        provider:
          type: string
        conversation:
          $ref: '#/components/schemas/IntegrationConversation'
        display_name:
          type: string
        provider_uri:
          type: string
          format: uri
    AgentModel:
      type: object
      additionalProperties: false
      required:
        - provider_config
        - name
      properties:
        provider_config:
          $ref: '#/components/schemas/ResourceName'
        name:
          $ref: '#/components/schemas/ResourceName'
    AgentActivity:
      type: object
      additionalProperties: false
      required:
        - state
        - last_activity_at
      properties:
        state:
          description: >-
            running while the agent has work in progress, which includes a
            custom tool call awaiting its result; waiting_on_interaction while
            it has an open question or permission request; idle otherwise; and
            archived once the agent is archived.
          type: string
          enum:
            - running
            - idle
            - waiting_on_interaction
            - archived
        last_activity_at:
          $ref: '#/components/schemas/Timestamp'
          description: >-
            When the agent's latest event was recorded, or its creation time
            before any event.
    UsageTotals:
      type: object
      additionalProperties: false
      required:
        - model_calls
        - tokens
        - cost
      properties:
        model_calls:
          type: integer
          format: int64
          minimum: 0
          description: Model calls that recorded token usage or a provider-reported cost.
        tokens:
          $ref: '#/components/schemas/UsageTokenTotals'
        cost:
          $ref: '#/components/schemas/UsageCostTotals'
    Timestamp:
      type: string
      format: date-time
    AgentConfigModel:
      type: object
      additionalProperties: false
      required:
        - provider_config
        - name
        - provider_model_slug
        - configured_model_id
        - current_revision_id
        - api_format
        - api_variant
        - context_window_tokens
        - max_output_tokens
        - default_cache_retention
        - supports_tools
        - supports_reasoning
        - default_reasoning_effort
        - supported_reasoning_efforts
        - input_modalities
        - output_modalities
      properties:
        provider_config:
          $ref: '#/components/schemas/ResourceName'
        name:
          $ref: '#/components/schemas/ResourceName'
          description: >-
            Configured model name selected by this agent config, rendered from
            the current configured model record.
        provider_model_slug:
          type: string
          description: >-
            Exact provider model slug on the configured model's current revision
            at response time.
        configured_model_id:
          $ref: '#/components/schemas/ConfiguredModelID'
        current_revision_id:
          $ref: '#/components/schemas/ConfiguredModelRevisionID'
        api_format:
          $ref: '#/components/schemas/ModelAPIFormat'
        api_variant:
          $ref: '#/components/schemas/ModelProviderAPIVariantResponse'
        context_window_tokens:
          type: integer
          description: >-
            Effective context budget for input and output tokens after model,
            project, and agent settings are applied. Triggers compaction when
            estimated input exceeds the remaining budget after output and safety
            reserves. The turn fails if compaction cannot make it fit.
        max_output_tokens:
          type:
            - integer
            - 'null'
          description: >-
            Effective known output-token ceiling after model and project
            settings, or null when unknown.
        default_max_output_tokens:
          type:
            - integer
            - 'null'
          description: Effective per-request output-token cap sent to the provider.
        default_cache_retention:
          $ref: '#/components/schemas/ModelCacheRetention'
        supports_tools:
          type: boolean
        supports_reasoning:
          type: boolean
        default_reasoning_effort:
          type: string
        supported_reasoning_efforts:
          type: array
          items:
            type: string
        input_modalities:
          type: array
          items:
            type: string
        output_modalities:
          type: array
          items:
            type: string
    CompiledAgentConfig:
      type: object
      additionalProperties: false
      description: >-
        Read-only saved compiled configuration, including default tools and
        derived subagent overrides.
      required:
        - instruction
        - model
      properties:
        version:
          type: string
          x-go-type-skip-optional-pointer: true
        instruction:
          type: string
        model:
          $ref: '#/components/schemas/CompiledAgentModel'
        machine_sources:
          type: array
          x-go-type-skip-optional-pointer: true
          items:
            $ref: '#/components/schemas/CompiledMachineSource'
        tools:
          type: object
          x-go-type-skip-optional-pointer: true
          additionalProperties:
            $ref: '#/components/schemas/CompiledTool'
        mcp:
          type: object
          x-go-type-skip-optional-pointer: true
          additionalProperties:
            $ref: '#/components/schemas/CompiledMCPServer'
        event_webhook:
          $ref: '#/components/schemas/CompiledEventWebhook'
        interaction_handlers:
          type: object
          x-go-type-skip-optional-pointer: true
          additionalProperties:
            $ref: '#/components/schemas/CompiledIntegrationCapability'
        git_credentials:
          $ref: '#/components/schemas/CompiledGitCredentials'
        skills:
          type: array
          x-go-type-skip-optional-pointer: true
          items:
            $ref: '#/components/schemas/CompiledSkill'
        memory_stores:
          type: array
          x-go-type-skip-optional-pointer: true
          items:
            $ref: '#/components/schemas/CompiledMemoryStore'
        subagents:
          type: object
          x-go-type-skip-optional-pointer: true
          additionalProperties:
            $ref: '#/components/schemas/CompiledSubagent'
        max_subagents:
          type: integer
        max_depth:
          type: integer
    AgentMachineBindingID:
      type: string
      pattern: ^amb_[a-z2-7]{26}$
    MachineID:
      description: Machine ID (mch_...).
      type: string
      pattern: ^mch_[a-z2-7]{26}$
    AgentMachineBindingKind:
      type: string
      enum:
        - explicit
        - pool
      x-enum-varnames:
        - AgentMachineBindingKindExplicit
        - AgentMachineBindingKindPool
    AgentMachineBindingState:
      type: string
      enum:
        - attached
        - released
      x-enum-varnames:
        - AgentMachineBindingStateAttached
        - AgentMachineBindingStateReleased
    SecretID:
      description: Secret ID (sec_...).
      type: string
      pattern: ^sec_[a-z2-7]{26}$
    AgentInputID:
      type: string
      pattern: ^ain_[a-z2-7]{26}$
    AgentInputDeliveryMode:
      type: string
      enum:
        - queued
        - steering
        - immediate
    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}$
    AgentInputContentBlock:
      oneOf:
        - $ref: '#/components/schemas/TextContentBlock'
        - $ref: '#/components/schemas/MediaRefContentBlock'
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/TextContentBlock'
          media_ref: '#/components/schemas/MediaRefContentBlock'
    AgentConfigDefinition:
      description: >-
        An agent config as a JSON object. This schema is the source of truth for
        agent configs: the server compiles YAML and JSON configs against it.
      type: object
      additionalProperties: false
      required:
        - instruction
        - model
      properties:
        event_webhook:
          $ref: '#/components/schemas/AgentConfigDefinitionEventWebhook'
        git_credentials:
          $ref: '#/components/schemas/AgentConfigDefinitionGitCredentials'
        instruction:
          type: string
          minLength: 1
          pattern: \S
        interaction_handlers:
          $ref: '#/components/schemas/AgentConfigDefinitionInteractionHandlers'
        machine_sources:
          $ref: '#/components/schemas/AgentConfigDefinitionMachineSources'
        max_depth:
          type: integer
          minimum: 1
          maximum: 8
        max_subagents:
          type: integer
          minimum: 1
          maximum: 2147483647
        mcp:
          $ref: '#/components/schemas/AgentConfigDefinitionMCPServers'
        memory_stores:
          $ref: '#/components/schemas/AgentConfigDefinitionMemoryStores'
        model:
          $ref: '#/components/schemas/AgentConfigDefinitionModel'
        skills:
          $ref: '#/components/schemas/AgentConfigDefinitionSkills'
        subagents:
          $ref: '#/components/schemas/AgentConfigDefinitionSubagents'
        tools:
          $ref: '#/components/schemas/AgentConfigDefinitionTools'
        version:
          enum:
            - v1
      x-go-type: json.RawMessage
    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.
    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
    ResourceName:
      type: string
      minLength: 1
      maxLength: 64
      x-omnara-unicode-normalization: NFC
      description: >-
        Human-readable name. Spaces and punctuation are allowed; leading or
        trailing whitespace and invisible or control characters are not.
    UsageTokenTotals:
      type: object
      additionalProperties: false
      description: >-
        Summed token counts across the tallied model calls. Input totals are the
        sum of uncached, cache-read, and cache-write tokens; output totals
        include reasoning tokens.
      required:
        - input_tokens_total
        - uncached_input_tokens
        - cache_read_input_tokens
        - cache_write_input_tokens
        - output_tokens_total
        - reasoning_output_tokens
      properties:
        input_tokens_total:
          type: integer
          format: int64
          minimum: 0
        uncached_input_tokens:
          type: integer
          format: int64
          minimum: 0
        cache_read_input_tokens:
          type: integer
          format: int64
          minimum: 0
        cache_write_input_tokens:
          type: integer
          format: int64
          minimum: 0
        output_tokens_total:
          type: integer
          format: int64
          minimum: 0
        reasoning_output_tokens:
          type: integer
          format: int64
          minimum: 0
    UsageCostTotals:
      type: object
      additionalProperties: false
      required:
        - provider_reported_usd
        - model_calls_with_reported_cost
      properties:
        provider_reported_usd:
          type: string
          description: >-
            Exact decimal sum in USD of the costs the provider reported for the
            tallied model calls. Calls whose provider reported no cost
            contribute nothing; compare model_calls_with_reported_cost against
            model_calls to see how complete the figure is.
          pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$
        model_calls_with_reported_cost:
          type: integer
          format: int64
          minimum: 0
    ConfiguredModelID:
      type: string
      pattern: ^mdl_[a-z2-7]{26}$
    ConfiguredModelRevisionID:
      type: string
      pattern: ^mrev_[a-z2-7]{26}$
    ModelAPIFormat:
      description: >-
        Wire protocol the model endpoint speaks: openai-responses,
        openai-chat-completions, or anthropic-messages.
      type: string
      enum:
        - openai-responses
        - openai-chat-completions
        - anthropic-messages
      x-enum-varnames:
        - ModelAPIFormatOpenaiResponses
        - ModelAPIFormatOpenaiChatCompletions
        - ModelAPIFormatAnthropicMessages
    ModelProviderAPIVariantResponse:
      type: string
      x-extensible-enum:
        - default
        - openrouter
        - bedrock
    ModelCacheRetention:
      type: string
      description: >-
        Prompt-cache preference for model requests; `short` when omitted.
        `short` applies the route's default caching (explicit cache breakpoints
        where the provider requires them) and, where the route accepts one, a
        stable conversation key for cache-aware routing. `long` prefers the
        route's extended cache lifetime where one exists (currently Anthropic's
        one-hour cache, which on Bedrock requires Claude 4.5 or newer) and
        behaves like `short` elsewhere. `none` sends no Omnara-managed cache
        controls or conversation key; providers may still cache prefixes on
        their own.
      enum:
        - none
        - short
        - long
    CompiledAgentModel:
      type: object
      additionalProperties: false
      required:
        - configured_model_id
      properties:
        configured_model_id:
          $ref: '#/components/schemas/ConfiguredModelID'
          x-go-type: publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
          x-go-type-skip-optional-pointer: true
        context_window_tokens:
          type: integer
        default_max_output_tokens:
          type: integer
        cache_retention:
          $ref: '#/components/schemas/ModelCacheRetention'
          x-go-type-skip-optional-pointer: true
        reasoning:
          $ref: '#/components/schemas/CompiledModelReasoning'
    CompiledMachineSource:
      type: object
      additionalProperties: false
      properties:
        machine_id:
          $ref: '#/components/schemas/MachineID'
          x-go-type: publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
          x-go-type-skip-optional-pointer: true
        machine_pool_id:
          $ref: '#/components/schemas/MachinePoolID'
          x-go-type: publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
          x-go-type-skip-optional-pointer: true
        max_machines:
          type: integer
          x-go-type-skip-optional-pointer: true
        initial_num_machines:
          type: integer
          x-go-type-skip-optional-pointer: true
        delete_after_idle_minutes:
          type: integer
        cwd:
          type: string
          x-go-type-skip-optional-pointer: true
        machine_cpu:
          type: integer
        machine_memory_mb:
          type: integer
        env_overlay:
          type: object
          x-go-type: map[string]*string
          x-go-type-skip-optional-pointer: true
          additionalProperties:
            type:
              - string
              - 'null'
        secret_env_overlay:
          type: object
          x-go-type: map[string]*publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
          x-go-type-skip-optional-pointer: true
          additionalProperties:
            oneOf:
              - $ref: '#/components/schemas/SecretID'
              - type: 'null'
        machine_provider_options_overlay:
          type: object
          x-go-type: map[string]json.RawMessage
          x-go-type-skip-optional-pointer: true
          additionalProperties: true
        description:
          type: string
          x-go-type-skip-optional-pointer: true
    CompiledTool:
      type: object
      additionalProperties: false
      required:
        - enabled
        - permission
      properties:
        integration_id:
          $ref: '#/components/schemas/IntegrationID'
          x-go-type: publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
          x-go-type-skip-optional-pointer: true
        enabled:
          type: boolean
        type:
          type: string
          enum:
            - built_in
            - custom
          x-enum-varnames:
            - CompiledToolTypeBuiltIn
            - CompiledToolTypeCustom
          x-go-type-skip-optional-pointer: true
        permission:
          $ref: '#/components/schemas/ToolPermissionSelection'
          x-go-type: toolpermission.Selection
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/toolpermission
        deferred:
          type: boolean
          x-go-type-skip-optional-pointer: true
        description:
          type: string
          x-go-type-skip-optional-pointer: true
        input_schema:
          type: object
          additionalProperties: true
          x-go-type: json.RawMessage
          x-go-type-skip-optional-pointer: true
    CompiledMCPServer:
      type: object
      additionalProperties: false
      required:
        - url
        - default_enabled
        - permission
      properties:
        url:
          type: string
        auth:
          $ref: '#/components/schemas/CompiledMCPAuth'
        default_enabled:
          type: boolean
        permission:
          $ref: '#/components/schemas/ToolPermissionSelection'
          x-go-type: toolpermission.Selection
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/toolpermission
        deferred:
          type: boolean
          x-go-type-skip-optional-pointer: true
        tools:
          type: object
          x-go-type-skip-optional-pointer: true
          additionalProperties:
            $ref: '#/components/schemas/CompiledMCPTool'
    CompiledEventWebhook:
      type: object
      additionalProperties: false
      required:
        - url
        - events
      properties:
        url:
          type: string
        events:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            enum:
              - agent_input
              - model_output
              - tool_result
              - context_checkpoint
              - tool_call_update
        signing_secret_id:
          $ref: '#/components/schemas/SecretID'
          x-go-type: publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
          x-go-type-skip-optional-pointer: true
    CompiledIntegrationCapability:
      type: object
      additionalProperties: false
      required:
        - integration_id
      properties:
        integration_id:
          $ref: '#/components/schemas/IntegrationID'
          x-go-type: publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
    CompiledGitCredentials:
      type: object
      additionalProperties: false
      description: >-
        Pinned GitHub integration supplying machine Git credentials with the
        connected installation's granted access.
      required:
        - integration
        - integration_id
      properties:
        integration:
          $ref: '#/components/schemas/IntegrationName'
        integration_id:
          $ref: '#/components/schemas/IntegrationID'
          x-go-type: publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
    CompiledSkill:
      type: object
      additionalProperties: false
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/SkillID'
          x-go-type: publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
    CompiledMemoryStore:
      type: object
      additionalProperties: false
      required:
        - id
        - access
      properties:
        id:
          $ref: '#/components/schemas/MemoryStoreID'
          x-go-type: publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
        access:
          $ref: '#/components/schemas/MemoryStoreAccess'
    CompiledSubagent:
      oneOf:
        - $ref: '#/components/schemas/CompiledSelfSubagent'
        - $ref: '#/components/schemas/CompiledProfileSubagent'
      discriminator:
        propertyName: type
        mapping:
          self: '#/components/schemas/CompiledSelfSubagent'
          profile: '#/components/schemas/CompiledProfileSubagent'
    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'
    AgentConfigDefinitionEventWebhook:
      type: object
      additionalProperties: false
      required:
        - url
        - events
      properties:
        events:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            enum:
              - agent_input
              - model_output
              - tool_result
              - context_checkpoint
              - tool_call_update
        signing_secret_id:
          type: string
          minLength: 1
        url:
          type: string
          minLength: 1
      x-go-type: json.RawMessage
    AgentConfigDefinitionGitCredentials:
      description: Integration whose git credentials the agent's machines use.
      type: object
      additionalProperties: false
      required:
        - integration
      properties:
        integration:
          type: string
          pattern: ^[a-zA-Z][a-zA-Z0-9-]{0,31}$
      x-go-type: json.RawMessage
    AgentConfigDefinitionInteractionHandlers:
      description: Interaction handlers keyed by integration name.
      anyOf:
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentConfigDefinitionInteractionHandler'
          propertyNames:
            type: string
            pattern: ^[a-zA-Z][a-zA-Z0-9-]{0,31}$
        - type: 'null'
      x-go-type: json.RawMessage
    AgentConfigDefinitionMachineSources:
      anyOf:
        - type: array
          items:
            $ref: '#/components/schemas/AgentConfigDefinitionMachineSource'
        - type: 'null'
      x-go-type: json.RawMessage
    AgentConfigDefinitionMCPServers:
      anyOf:
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentConfigDefinitionMCPServer'
          propertyNames:
            type: string
            pattern: ^[a-zA-Z][a-zA-Z0-9-]{0,31}$
        - type: 'null'
      x-go-type: json.RawMessage
    AgentConfigDefinitionMemoryStores:
      anyOf:
        - type: array
          items:
            $ref: '#/components/schemas/AgentConfigDefinitionMemoryStore'
        - type: 'null'
      x-go-type: json.RawMessage
    AgentConfigDefinitionModel:
      type: object
      additionalProperties: false
      required:
        - provider_config
        - name
      properties:
        cache_retention:
          enum:
            - none
            - short
            - long
        context_window_tokens:
          type: integer
          minimum: 2
          maximum: 2147483647
          description: >-
            Context budget for input and output tokens. Triggers compaction when
            estimated input exceeds the remaining budget after output and safety
            reserves. The turn fails if compaction cannot make it fit.
        default_max_output_tokens:
          type: integer
          minimum: 1
        name:
          $ref: '#/components/schemas/ResourceNameReference'
        provider_config:
          $ref: '#/components/schemas/ResourceNameReference'
        reasoning:
          type: object
          additionalProperties: false
          required:
            - effort
          properties:
            effort:
              type: string
              minLength: 1
              pattern: \S
      x-go-type: json.RawMessage
    AgentConfigDefinitionSkills:
      anyOf:
        - type: array
          uniqueItems: true
          items:
            type: string
            pattern: ^skl_[a-z2-7]{26}$
        - type: 'null'
      x-go-type: json.RawMessage
    AgentConfigDefinitionSubagents:
      anyOf:
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentConfigDefinitionSubagent'
          propertyNames:
            type: string
            pattern: ^[A-Za-z_][A-Za-z0-9_]{0,63}$
        - type: 'null'
      x-go-type: json.RawMessage
    AgentConfigDefinitionTools:
      anyOf:
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentConfigDefinitionTool'
          propertyNames:
            allOf:
              - anyOf:
                  - type: string
                    pattern: ^[A-Za-z_][A-Za-z0-9_]{0,63}$
                  - type: string
                    maxLength: 64
                    pattern: ^int__[a-zA-Z][a-zA-Z0-9-]{0,31}__[a-zA-Z][a-zA-Z0-9_-]*$
              - not:
                  type: string
                  pattern: ^mcp__
        - type: 'null'
      x-go-type: json.RawMessage
    CompiledModelReasoning:
      type: object
      additionalProperties: false
      required:
        - effort
      properties:
        effort:
          type: string
    MachinePoolID:
      description: Machine pool ID (mpo_...).
      type: string
      pattern: ^mpo_[a-z2-7]{26}$
    ToolPermissionSelection:
      type: object
      additionalProperties: false
      required:
        - mode
        - parameters
      properties:
        mode:
          type: string
        parameters:
          type: object
          additionalProperties: true
    CompiledMCPAuth:
      oneOf:
        - $ref: '#/components/schemas/CompiledMCPAuthBearer'
        - $ref: '#/components/schemas/CompiledMCPAuthOAuth'
        - $ref: '#/components/schemas/CompiledMCPAuthSigV4'
      discriminator:
        propertyName: type
        mapping:
          bearer: '#/components/schemas/CompiledMCPAuthBearer'
          oauth: '#/components/schemas/CompiledMCPAuthOAuth'
          sigv4: '#/components/schemas/CompiledMCPAuthSigV4'
    CompiledMCPTool:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type: boolean
        permission:
          $ref: '#/components/schemas/ToolPermissionSelection'
          x-go-type: toolpermission.Selection
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/toolpermission
        deferred:
          type: boolean
    IntegrationName:
      type: string
      pattern: ^[a-zA-Z][a-zA-Z0-9-]{0,31}$
      description: >-
        Immutable, project-unique integration name used in config keys and
        qualified tool names.
    SkillID:
      type: string
      pattern: ^skl_[a-z2-7]{26}$
    MemoryStoreID:
      type: string
      pattern: ^mst_[a-z2-7]{26}$
    MemoryStoreAccess:
      type: string
      enum:
        - read
        - read_write
    CompiledSelfSubagent:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - self
          x-enum-varnames:
            - CompiledSelfSubagentTypeSelf
        description:
          type: string
          x-go-type-skip-optional-pointer: true
        model:
          $ref: '#/components/schemas/CompiledSubagentModel'
        instruction_append:
          type: string
          x-go-type-skip-optional-pointer: true
        max_instances:
          type: integer
        archive_after_idle_minutes:
          type: integer
    CompiledProfileSubagent:
      type: object
      additionalProperties: false
      required:
        - type
        - profile_id
      properties:
        type:
          type: string
          enum:
            - profile
          x-enum-varnames:
            - CompiledProfileSubagentTypeProfile
        profile_id:
          $ref: '#/components/schemas/AgentProfileID'
          x-go-type: publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
        description:
          type: string
          x-go-type-skip-optional-pointer: true
        model:
          $ref: '#/components/schemas/CompiledSubagentModel'
        instruction_append:
          type: string
          x-go-type-skip-optional-pointer: true
        max_instances:
          type: integer
        archive_after_idle_minutes:
          type: integer
    ArtifactID:
      type: string
      pattern: ^art_[a-z2-7]{26}$
    AgentConfigDefinitionMachineSource:
      type: object
      additionalProperties: false
      properties:
        cwd:
          type: string
          maxLength: 4096
        delete_after_idle_minutes:
          anyOf:
            - const: 0
            - type: integer
              minimum: 5
              maximum: 2147483647
        description:
          type: string
          maxLength: 4096
        env_overlay:
          anyOf:
            - type: object
              additionalProperties:
                anyOf:
                  - type: string
                  - type: 'null'
              propertyNames:
                $ref: '#/components/schemas/EnvironmentVariableName'
            - type: 'null'
        initial_num_machines:
          type: integer
          minimum: 0
        machine_cpu:
          type: integer
          minimum: 1
          maximum: 2147483647
        machine_memory_mb:
          type: integer
          minimum: 1
          maximum: 2147483647
        machine_name:
          $ref: '#/components/schemas/ResourceNameReference'
        machine_pool_name:
          $ref: '#/components/schemas/ResourceNameReference'
        machine_provider_options_overlay:
          anyOf:
            - type: object
            - type: 'null'
        max_machines:
          type: integer
          minimum: 0
        secret_env_overlay:
          anyOf:
            - type: object
              additionalProperties:
                anyOf:
                  - type: string
                    pattern: ^sec_[a-z2-7]{26}$
                  - type: 'null'
              propertyNames:
                $ref: '#/components/schemas/EnvironmentVariableName'
            - type: 'null'
      oneOf:
        - type: object
          required:
            - machine_name
        - type: object
          required:
            - machine_pool_name
      x-go-type: json.RawMessage
    AgentConfigDefinitionMCPServer:
      type: object
      additionalProperties: false
      required:
        - url
      properties:
        auth:
          $ref: '#/components/schemas/AgentConfigDefinitionMCPAuth'
        default_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
        deferred:
          type: boolean
        permission:
          $ref: '#/components/schemas/AgentConfigDefinitionToolPermission'
        tools:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentConfigDefinitionMCPTool'
          propertyNames:
            type: string
            pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$
        url:
          type: string
          minLength: 1
      x-go-type: json.RawMessage
    AgentConfigDefinitionMemoryStore:
      type: object
      additionalProperties: false
      required:
        - name
        - access
      properties:
        name:
          $ref: '#/components/schemas/MemoryStoreName'
        access:
          type: string
          enum:
            - read
            - read_write
      x-go-type: json.RawMessage
    ResourceNameReference:
      description: Name of an existing resource, resolved when the config is compiled.
      type: string
      minLength: 1
      maxLength: 64
      pattern: ^\S(?:.*\S)?$
    AgentConfigDefinitionSubagent:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        archive_after_idle_minutes:
          type: integer
          minimum: 1
          maximum: 2147483647
        description:
          type: string
        instruction:
          $ref: '#/components/schemas/AgentConfigDefinitionSubagentInstruction'
        max_instances:
          type: integer
          minimum: 1
          maximum: 2147483647
        model:
          $ref: '#/components/schemas/AgentConfigDefinitionSubagentModel'
        profile:
          $ref: '#/components/schemas/ResourceNameReference'
        type:
          enum:
            - profile
            - self
      if:
        type: object
        required:
          - type
        properties:
          type:
            const: profile
      then:
        required:
          - profile
      else:
        not:
          type: object
          required:
            - profile
      x-go-type: json.RawMessage
    CompiledMCPAuthBearer:
      type: object
      additionalProperties: false
      required:
        - type
        - secret_id
      properties:
        type:
          type: string
          enum:
            - bearer
          x-enum-varnames:
            - CompiledMCPAuthBearerTypeBearer
        secret_id:
          $ref: '#/components/schemas/SecretID'
          x-go-type: publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
    CompiledMCPAuthOAuth:
      type: object
      additionalProperties: false
      required:
        - type
        - secret_id
      properties:
        type:
          type: string
          enum:
            - oauth
          x-enum-varnames:
            - CompiledMCPAuthOAuthTypeOAuth
        secret_id:
          $ref: '#/components/schemas/SecretID'
          x-go-type: publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
    CompiledMCPAuthSigV4:
      type: object
      additionalProperties: false
      required:
        - type
        - secret_id
        - service
        - region
      properties:
        type:
          type: string
          enum:
            - sigv4
          x-enum-varnames:
            - CompiledMCPAuthSigV4TypeSigV4
        secret_id:
          $ref: '#/components/schemas/SecretID'
          x-go-type: publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
        service:
          type: string
          minLength: 1
        region:
          type: string
          minLength: 1
    CompiledSubagentModel:
      type: object
      additionalProperties: false
      properties:
        configured_model_id:
          $ref: '#/components/schemas/ConfiguredModelID'
          x-go-type: publicid.ID
          x-go-type-import:
            path: github.com/omnara-ai/omnara/internal/publicid
          x-go-type-skip-optional-pointer: true
        context_window_tokens:
          type: integer
        default_max_output_tokens:
          type: integer
        cache_retention:
          $ref: '#/components/schemas/ModelCacheRetention'
          x-go-type-skip-optional-pointer: true
        reasoning:
          $ref: '#/components/schemas/CompiledModelReasoning'
    AgentConfigDefinitionMCPAuth:
      type: object
      additionalProperties: false
      required:
        - type
        - secret_id
      properties:
        region:
          type: string
          minLength: 1
        secret_id:
          type: string
          minLength: 1
          pattern: ^sec_[a-z2-7]{26}$
        service:
          type: string
          minLength: 1
        type:
          enum:
            - bearer
            - oauth
            - sigv4
      x-go-type: json.RawMessage
    AgentConfigDefinitionMCPTool:
      type: object
      additionalProperties: false
      properties:
        deferred:
          anyOf:
            - type: boolean
            - type: 'null'
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
        permission:
          $ref: '#/components/schemas/AgentConfigDefinitionToolPermission'
      x-go-type: json.RawMessage
    MemoryStoreName:
      type: string
      minLength: 1
      maxLength: 64
      pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
      description: >-
        Machine-readable memory store identifier consisting of lowercase ASCII
        segments separated by single hyphens.
    AgentConfigDefinitionSubagentInstruction:
      type: object
      additionalProperties: false
      properties:
        append:
          type: string
      x-go-type: json.RawMessage
    AgentConfigDefinitionSubagentModel:
      type: object
      additionalProperties: false
      dependentRequired:
        name:
          - provider_config
        provider_config:
          - name
      properties:
        cache_retention:
          enum:
            - none
            - short
            - long
        context_window_tokens:
          type: integer
          minimum: 2
          maximum: 2147483647
          description: >-
            Context budget for input and output tokens. Triggers compaction when
            estimated input exceeds the remaining budget after output and safety
            reserves. The turn fails if compaction cannot make it fit.
        default_max_output_tokens:
          type: integer
          minimum: 1
        name:
          $ref: '#/components/schemas/ResourceNameReference'
        provider_config:
          $ref: '#/components/schemas/ResourceNameReference'
        reasoning:
          type: object
          additionalProperties: false
          required:
            - effort
          properties:
            effort:
              type: string
              minLength: 1
              pattern: \S
      x-go-type: json.RawMessage
  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.
    csrfHeader:
      type: apiKey
      in: header
      name: X-Omnara-Csrf
      description: >-
        CSRF token header required for browser-session mutations. The value must
        match the session's CSRF cookie.

````

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