> ## 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 model provider config > Create a model provider config, validate the configured credential where the provider exposes a validation endpoint, then probe the provider's /models endpoint. The result is returned as model_catalog; a failed probe does not fail creation. ## OpenAPI ````yaml /api-reference/openapi.yaml post /orgs/{orgID}/model-provider-configs 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}/model-provider-configs: parameters: - name: orgID in: path description: Organization ID (org_...). required: true schema: type: string pattern: ^org_[a-z2-7]{26}$ post: tags: - Models summary: Create model provider config description: >- Create a model provider config, validate the configured credential where the provider exposes a validation endpoint, then probe the provider's /models endpoint. The result is returned as model_catalog; a failed probe does not fail creation. operationId: createModelProviderConfig requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateModelProviderConfigRequest' responses: '201': description: Created route response. content: application/json: schema: $ref: '#/components/schemas/CreateModelProviderConfigResponse' '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: schemas: CreateModelProviderConfigRequest: type: object description: >- Connect Omnara to a model API endpoint. Use a preset for built-in providers, or provide api_format and base_url for a custom endpoint. When omitted, endpoint_path and auth settings are filled from api_format. additionalProperties: false required: - name - credential_secret_id properties: name: $ref: '#/components/schemas/ResourceName' preset: description: >- Built-in provider settings: openai, openrouter, or anthropic. A preset fills in api_format, api_variant, base_url, endpoint_path, auth_kind, and auth_options, so omit those when using one. type: string enum: - openai - openrouter - anthropic api_format: $ref: '#/components/schemas/ModelAPIFormat' api_variant: $ref: '#/components/schemas/ModelProviderAPIVariant' base_url: type: string minLength: 1 description: >- Provider endpoint base URL. Normal API mode requires a public HTTPS endpoint; localhost and loopback endpoints are accepted only when the API is running in insecure dev mode. endpoint_path: type: string minLength: 1 pattern: ^/ description: >- URL path under base_url. Defaults to /responses for OpenAI Responses, /chat/completions for Chat Completions, and /messages for Anthropic Messages. request_timeout_ms: type: integer minimum: 1 maximum: 2147483647 description: >- Total deadline for one provider attempt, including reasoning and response streaming, in milliseconds. Defaults to 3600000 (60 minutes). Retries have separate deadlines. idle_timeout_ms: type: integer minimum: 1 maximum: 2147483647 description: >- Maximum wait for response headers or the next response bytes, in milliseconds. Heartbeats count as activity. Defaults to 300000 (5 minutes). Local response processing does not consume this idle budget. auth_kind: $ref: '#/components/schemas/ModelProviderAuthKind' auth_options: type: object x-go-type: json.RawMessage x-go-type-skip-optional-pointer: true description: >- Non-secret authentication settings. Use an empty object with bearer_token. With api_key_header, set {"header_name":"..."}; Anthropic Messages defaults to {"header_name":"x-api-key"}. With sigv4, set the AWS signing service and region. additionalProperties: false properties: header_name: type: string minLength: 1 service: type: string minLength: 1 maxLength: 64 region: type: string minLength: 1 maxLength: 64 credential_secret_id: $ref: '#/components/schemas/SecretID' headers: type: object description: >- Extra HTTP headers sent with every request to this provider. Values are stored and returned as plain text; use secret_headers for keys and tokens. additionalProperties: type: string secret_headers: type: object description: >- Extra HTTP headers whose values come from org-owned generic secrets, mapping header names to secret references. additionalProperties: $ref: '#/components/schemas/SecretID' CreateModelProviderConfigResponse: type: object additionalProperties: false required: - config - model_catalog properties: config: $ref: '#/components/schemas/ModelProviderConfig' model_catalog: $ref: '#/components/schemas/ModelCatalog' 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. 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 ModelProviderAPIVariant: description: >- Provider-specific flavor of the API format: default, openrouter, or bedrock. type: string enum: - default - openrouter - bedrock ModelProviderAuthKind: description: >- How the credential is sent: bearer_token, api_key_header, or sigv4 (AWS). type: string enum: - bearer_token - api_key_header - sigv4 x-enum-varnames: - BearerToken - ApiKeyHeader - ModelProviderSigV4 SecretID: description: Secret ID (sec_...). type: string pattern: ^sec_[a-z2-7]{26}$ ModelProviderConfig: type: object additionalProperties: false required: - id - org_id - management_kind - name - api_format - api_variant - base_url - endpoint_path - request_timeout_ms - idle_timeout_ms - auth_kind - auth_options - credential_secret_id - headers - secret_headers - created_at - updated_at properties: id: $ref: '#/components/schemas/ModelProviderConfigID' org_id: $ref: '#/components/schemas/OrganizationID' management_kind: $ref: '#/components/schemas/ManagementKind' name: $ref: '#/components/schemas/ResourceName' api_format: $ref: '#/components/schemas/ModelAPIFormat' api_variant: $ref: '#/components/schemas/ModelProviderAPIVariantResponse' base_url: type: string description: >- Provider endpoint base URL. Normal API mode uses public HTTPS endpoints; localhost and loopback endpoints are only for insecure dev-mode configs. endpoint_path: type: string request_timeout_ms: type: integer idle_timeout_ms: type: integer auth_kind: $ref: '#/components/schemas/ModelProviderAuthKindResponse' auth_options: type: object x-go-type: json.RawMessage x-go-type-skip-optional-pointer: true description: Non-secret authentication settings for this provider config. additionalProperties: false properties: header_name: type: string minLength: 1 service: type: string minLength: 1 maxLength: 64 region: type: string minLength: 1 maxLength: 64 credential_secret_id: $ref: '#/components/schemas/SecretID' headers: type: object description: Extra HTTP headers sent with every request to this provider. additionalProperties: type: string secret_headers: type: object description: Extra HTTP headers whose values come from the referenced secrets. additionalProperties: $ref: '#/components/schemas/SecretID' created_at: $ref: '#/components/schemas/Timestamp' updated_at: $ref: '#/components/schemas/Timestamp' ModelCatalog: type: object description: >- The provider's model catalog, obtained by validating the configured credential and probing the provider's /models endpoint. A failed probe does not affect the stored config; treat it as a warning that the base URL or API key may be invalid. additionalProperties: false required: - status properties: status: type: string enum: - ok - failed models: type: array description: >- Models advertised by the provider, newest first, filtered to text-output tool-calling models where the provider exposes enough metadata to tell. Present when status is ok. items: $ref: '#/components/schemas/DiscoveredProviderModel' error: type: string description: Why the probe failed. Present when status is failed. 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 ModelProviderConfigID: type: string pattern: ^mpc_[a-z2-7]{26}$ OrganizationID: type: string pattern: ^org_[a-z2-7]{26}$ ManagementKind: type: string description: >- Lifecycle owner. Tenant-managed resources can be changed through tenant APIs. Cluster-managed resources are installed and lifecycle-managed by the control plane; individual APIs may explicitly expose tenant-editable settings. enum: - tenant - cluster ModelProviderAPIVariantResponse: type: string x-extensible-enum: - default - openrouter - bedrock ModelProviderAuthKindResponse: type: string x-extensible-enum: - bearer_token - api_key_header - sigv4 Timestamp: type: string format: date-time DiscoveredProviderModel: type: object additionalProperties: false required: - slug properties: slug: type: string description: >- Provider model slug usable as a configured model's provider_model_slug. display_name: type: string context_window_tokens: type: integer minimum: 2 maximum: 2147483647 description: Provider-advertised context window limit in tokens, when available. max_output_tokens: type: integer minimum: 1 maximum: 2147483647 description: Provider-advertised maximum output limit in tokens, when available. supports_reasoning: type: boolean description: >- Whether Omnara can send this model a reasoning effort, when the provider or the public model catalog reports it. supported_reasoning_efforts: type: array description: Reasoning effort values the model accepts, when reported. items: type: string pricing: $ref: '#/components/schemas/DiscoveredModelPricing' 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. DiscoveredModelPricing: type: object additionalProperties: false description: >- Provider-advertised list prices in USD per million tokens, as exact decimal strings. Present only when the provider publishes pricing in its model catalog (OpenRouter). Cache prices are omitted when the provider does not publish them. required: - input_usd_per_million - output_usd_per_million properties: input_usd_per_million: type: string pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$ cache_read_input_usd_per_million: type: string pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$ cache_write_input_usd_per_million: type: string pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$ output_usd_per_million: type: string pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$ 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.