> ## 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
        required: true
        schema:
          type: string
          pattern: ^org_[a-z2-7]{26}$
      - name: projectID
        in: path
        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:
      type: object
      additionalProperties: false
      required:
        - config
      properties:
        profile:
          $ref: '#/components/schemas/AgentProfileID'
        config:
          $ref: '#/components/schemas/AgentConfigID'
        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/ConfigToolSource'
          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/ConfigIntegrationCapabilitySource'
          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
            - 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:
      type: string
      pattern: ^acfg_[a-z2-7]{26}$
    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.
    ConfigToolSource:
      additionalProperties: false
      else:
        not:
          anyOf:
            - required:
                - description
              type: object
            - required:
                - input_schema
              type: object
      if:
        properties:
          type:
            const: custom
        required:
          - type
        type: object
      properties:
        deferred:
          type: boolean
        description:
          type: string
          minLength: 1
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
        input_schema:
          $ref: '#/components/schemas/ConfigAgentToolInputSchema'
        permission:
          $ref: '#/components/schemas/ConfigToolPermissionSelection'
        type:
          enum:
            - built_in
            - custom
      then:
        required:
          - description
          - input_schema
      type: object
      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'
    ConfigIntegrationCapabilitySource:
      additionalProperties: false
      type: object
      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
        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
        - 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
    ConfigAgentToolInputSchema:
      properties:
        properties:
          additionalProperties:
            type: object
          type: object
        required:
          items:
            type: string
            minLength: 1
          type: array
        type:
          const: object
      required:
        - type
      type: object
    ConfigToolPermissionSelection:
      additionalProperties: false
      properties:
        mode:
          minLength: 1
          pattern: \S
          type: string
        parameters:
          type: object
      required:
        - mode
      type: object
    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:
      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 token window after configured-model, project-grant, and
            agent-config settings are applied.
        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:
      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:
      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'
    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:
      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'
    CompiledModelReasoning:
      type: object
      additionalProperties: false
      required:
        - effort
      properties:
        effort:
          type: string
    MachinePoolID:
      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}$
    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'
  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.