> ## 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. # Update agent config > Replaces an active agent's config without restarting its conversation and returns the new agent_config. Model, instruction, and tool changes apply at the agent's next model call; machine changes apply immediately, stopping processes on removed machines and deleting the agent's machines from removed pools. Send the complete config, not a patch. ## OpenAPI ````yaml /api-reference/openapi.yaml post /orgs/{orgID}/projects/{projectID}/agents/{agentID}/config openapi: 3.1.2 info: title: Omnara API version: 0.1.0 description: Public HTTP API contract for Omnara. servers: - url: https://api.omnara.com/v1 description: Hosted Omnara - url: /api/v1 description: Self-hosted Omnara, relative to the deployment origin security: - bearerAuth: [] - browserSessionCookie: [] tags: - name: Agents description: >- Launch agents, send inputs, manage the input backlog, and work with tool calls. externalDocs: description: Guide url: https://docs.omnara.com/agents/overview - name: Interactions description: List and resolve the approvals and questions that pause an agent. externalDocs: description: Guide url: https://docs.omnara.com/events/interactions - name: Actors description: Attribute agent inputs and interaction responses to external users. externalDocs: description: Guide url: >- https://docs.omnara.com/events/sending-input#who-said-that-actors-and-attribution - name: Events description: Read or stream the agent timeline, list turns, and download artifacts. externalDocs: description: Guide url: https://docs.omnara.com/events/streaming - name: Configs and Profiles description: >- Create agent configs, manage reusable launch profiles, and set up integrations. externalDocs: description: Guide url: https://docs.omnara.com/agents/configuration - name: Integrations description: >- Connect project integrations, route conversations, and manage launch settings. externalDocs: description: Guide url: https://docs.omnara.com/integrations/overview - name: Models description: Configure model providers and models, and grant projects access to them. externalDocs: description: Guide url: https://docs.omnara.com/organization/model-providers - name: Machines description: Register machines, control project access, and manage daemon tokens. externalDocs: description: Guide url: https://docs.omnara.com/machines/connect - name: Machine Pools description: Define machine pools and grant projects access to them. externalDocs: description: Guide url: https://docs.omnara.com/machines/pools - name: Secrets description: >- Manage secret ownership and versions, and inspect or grant project availability. externalDocs: description: Guide url: https://docs.omnara.com/organization/secrets - name: Skills description: Manage versioned skill ownership and load skill instructions on demand. externalDocs: description: Guide url: https://docs.omnara.com/tools/skills - name: Organizations and Projects description: Create organizations and projects and manage membership. externalDocs: description: Guide url: https://docs.omnara.com/organization/members - name: Users and API Keys description: >- The authenticated user, personal and organization API keys, and invitations. externalDocs: description: Guide url: https://docs.omnara.com/api/authentication - name: Machine Daemon description: Routes the Omnara machine daemon uses to connect a machine. paths: /orgs/{orgID}/projects/{projectID}/agents/{agentID}/config: parameters: - name: orgID in: path description: Organization ID (org_...). required: true schema: type: string pattern: ^org_[a-z2-7]{26}$ - name: projectID in: path description: Project ID (proj_...). required: true schema: type: string pattern: ^proj_[a-z2-7]{26}$ - name: agentID in: path description: Agent ID (agt_...). required: true schema: type: string pattern: ^agt_[a-z2-7]{26}$ post: tags: - Agents summary: Update agent config description: >- Replaces an active agent's config without restarting its conversation and returns the new agent_config. Model, instruction, and tool changes apply at the agent's next model call; machine changes apply immediately, stopping processes on removed machines and deleting the agent's machines from removed pools. Send the complete config, not a patch. operationId: updateAgentConfig parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAgentConfigRequest' responses: '200': description: Agent config updated. content: application/json: schema: $ref: '#/components/schemas/UpdateAgentConfigResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '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: UpdateAgentConfigRequest: description: >- Replaces a live agent's config. expected_current_config_id makes the change conditional on the agent still running that config, so concurrent editors get a conflict instead of silently overwriting each other. 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 expected_current_config_id: $ref: '#/components/schemas/AgentConfigID' UpdateAgentConfigResponse: type: object additionalProperties: false required: - agent_config - agent_input - event_id properties: agent_config: $ref: '#/components/schemas/AgentConfig' agent_input: $ref: '#/components/schemas/AgentInput' event_id: $ref: '#/components/schemas/AgentEventID' 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 AgentConfigID: description: Agent config ID (acfg_...). type: string pattern: ^acfg_[a-z2-7]{26}$ 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' 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' AgentEventID: type: string pattern: ^evt_[a-z2-7]{26}$ Error: type: object additionalProperties: false required: - error - code properties: error: type: string description: Human-readable error message. Do not match on it programmatically. current_digest: type: string pattern: ^sha256:[0-9a-f]{64}$ description: >- Current file digest for file_content_conflict or expected_digest_required; absent if the file no longer exists. A replacement must be confirmed before retrying with this digest. issues: type: array description: >- Field-level problems when a submitted document (such as an agent config source) failed validation. Absent for errors that are not about a specific field. items: $ref: '#/components/schemas/AgentConfigErrorIssue' code: type: string description: Stable error code for programmatic handling. x-go-type: ErrorCode x-extensible-enum: - invalid_request - unauthorized - forbidden - not_found - conflict - file_content_conflict - file_read_only - expected_digest_required - not_a_file - gone - request_too_large - unsupported_media_type - unprocessable - upstream_unavailable - rate_limited - internal_error - service_unavailable - idempotency_key_conflict - agent_backlog_full - state_transition_conflict - managed_work_admission_denied - pending_work - not_wake_capable - daemon_runtime_unregistered - validation_failed - csrf_check_failed - authentication_unavailable ClientErrorCode: type: string description: >- Stable error code carried by 4XX statuses. Subset of the Error code enum whose statuses are client errors. x-extensible-enum: - invalid_request - validation_failed - unauthorized - forbidden - csrf_check_failed - not_found - conflict - file_content_conflict - file_read_only - expected_digest_required - not_a_file - idempotency_key_conflict - agent_backlog_full - state_transition_conflict - pending_work - not_wake_capable - gone - daemon_runtime_unregistered - request_too_large - unsupported_media_type - unprocessable - upstream_unavailable - rate_limited ServerErrorCode: type: string description: >- Stable error code carried by 5XX statuses. Subset of the Error code enum whose statuses are server errors. x-extensible-enum: - internal_error - service_unavailable - authentication_unavailable 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 OrganizationID: type: string pattern: ^org_[a-z2-7]{26}$ ProjectID: description: Project ID (proj_...). type: string pattern: ^proj_[a-z2-7]{26}$ 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 Timestamp: type: string format: date-time 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 AgentInputID: type: string pattern: ^ain_[a-z2-7]{26}$ AgentID: type: string pattern: ^agt_[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' 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. 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 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. 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' TextContentBlock: type: object additionalProperties: false required: - type - text properties: type: type: string enum: - text text: type: string metadata: $ref: '#/components/schemas/ContentBlockMetadata' MediaRefContentBlock: type: object additionalProperties: false required: - type - artifact_id properties: type: type: string enum: - media_ref artifact_id: $ref: '#/components/schemas/ArtifactID' exclude_from_model_context: type: boolean description: >- Whether the referenced artifact is excluded from later model context. metadata: $ref: '#/components/schemas/ContentBlockMetadata' 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 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 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 CompiledModelReasoning: type: object additionalProperties: false required: - effort properties: effort: type: string MachineID: description: Machine ID (mch_...). type: string pattern: ^mch_[a-z2-7]{26}$ MachinePoolID: description: Machine pool ID (mpo_...). type: string pattern: ^mpo_[a-z2-7]{26}$ SecretID: description: Secret ID (sec_...). type: string pattern: ^sec_[a-z2-7]{26}$ IntegrationID: type: string pattern: ^itg_[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 ContentBlockMetadata: $ref: '#/components/schemas/Metadata' description: >- Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 characters, values must be strings of up to 512 characters. Keys beginning with `omnara_` are reserved for Omnara and may affect product behavior; use them only when intentionally invoking Omnara-defined behavior. ArtifactID: type: string pattern: ^art_[a-z2-7]{26}$ 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 AgentConfigDefinitionToolPermission: type: object additionalProperties: false required: - mode properties: mode: type: string minLength: 1 pattern: \S parameters: type: object 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 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 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' AgentProfileID: type: string pattern: ^aprf_[a-z2-7]{26}$ Metadata: type: object description: >- Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 characters, values must be strings of up to 512 characters. x-go-type: resourcemeta.Metadata x-go-type-import: path: github.com/omnara-ai/omnara/internal/resourcemeta x-go-type-skip-optional-pointer: true maxProperties: 16 propertyNames: minLength: 1 maxLength: 64 additionalProperties: type: string maxLength: 512 responses: BadRequest: description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication is required or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The authenticated principal is not authorized. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource was not found or is not visible. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: >- The request conflicts with current resource state or idempotency history. 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.