openapi: 3.2.0 info: title: Axonflow LLM Providers API version: 11.1.0 contact: name: AxonFlow Support url: https://getaxonflow.com/support license: name: Business Source License 1.1 url: https://github.com/getaxonflow/axonflow/blob/main/LICENSE description: 'Operations tagged LLM Providers across 2 of this provider''s published API definitions: axonflow-orchestrator-api.yaml, axonflow-orchestrator-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://orchestrator.getaxonflow.com description: Production (SaaS) - url: http://localhost:8081 description: Local Development tags: - name: LLM Providers description: LLM provider management paths: /api/v1/providers/status: get: tags: - LLM Providers summary: Get LLM provider status description: Returns status and availability of all configured LLM providers operationId: getProviderStatus responses: '200': description: Provider status content: application/json: schema: $ref: '#/components/schemas/ProviderStatusResponse' example: providers: - name: openai available: true models: - gpt-4 - gpt-4o - gpt-4o-mini weight: 0.4 avg_latency_ms: 1200 - name: bedrock available: true models: - anthropic.claude-v2 - amazon.titan-text weight: 0.4 avg_latency_ms: 900 - name: ollama available: true models: - llama3.2 - mistral weight: 0.2 avg_latency_ms: 500 servers: - url: https://orchestrator.getaxonflow.com description: Production (SaaS) - url: http://localhost:8081 description: Local Development /api/v1/providers/weights: put: tags: - LLM Providers summary: Update provider routing weights description: 'Update the routing weights for LLM providers. Weights determine the probability of routing to each provider. Weights must sum to 1.0.' operationId: updateProviderWeights requestBody: required: true content: application/json: schema: type: object additionalProperties: type: number minimum: 0 maximum: 1 example: openai: 0.5 bedrock: 0.3 ollama: 0.2 responses: '200': description: Weights updated content: application/json: schema: type: object properties: status: type: string message: type: string example: status: success message: Provider weights updated '400': $ref: '#/components/responses/BadRequest' servers: - url: https://orchestrator.getaxonflow.com description: Production (SaaS) - url: http://localhost:8081 description: Local Development /api/v1/llm-provider-types: get: tags: - LLM Providers summary: List available provider types description: 'Returns a list of available LLM provider types (factory info). This endpoint helps clients discover what provider types can be configured.' operationId: listLLMProviderTypes responses: '200': description: List of available provider types content: application/json: schema: type: object properties: provider_types: type: array items: type: object properties: type: type: string enum: - openai - azure-openai - anthropic - bedrock - ollama - gemini - custom name: type: string description: Human-readable name description: type: string supports_streaming: type: boolean requires_api_key: type: boolean configuration_schema: type: object description: JSON Schema for provider configuration example: provider_types: - type: openai name: OpenAI description: OpenAI GPT models (gpt-4, gpt-4o-mini) supports_streaming: true requires_api_key: true - type: anthropic name: Anthropic description: Anthropic Claude models supports_streaming: true requires_api_key: true - type: bedrock name: AWS Bedrock description: AWS Bedrock models (Claude, Titan, Llama) supports_streaming: true requires_api_key: false - type: ollama name: Ollama description: Local Ollama models supports_streaming: true requires_api_key: false '401': $ref: '#/components/responses/CodedUnauthorized' servers: - url: https://orchestrator.getaxonflow.com description: Production (SaaS) - url: http://localhost:8081 description: Local Development /api/v1/llm-providers: get: tags: - LLM Providers summary: List LLM providers description: 'Returns a paginated list of configured LLM providers. Supports filtering by type and enabled status.' operationId: listLLMProviders parameters: - name: type in: query description: Filter by provider type schema: type: string enum: - openai - azure-openai - anthropic - bedrock - ollama - gemini - custom - name: enabled in: query description: Filter by enabled status schema: type: boolean - name: page in: query description: Page number (1-indexed) schema: type: integer default: 1 - name: page_size in: query description: Items per page schema: type: integer default: 20 maximum: 100 responses: '200': description: List of LLM providers content: application/json: schema: $ref: '#/components/schemas/LLMProviderListResponse' '401': $ref: '#/components/responses/CodedUnauthorized' post: tags: - LLM Providers summary: Create LLM provider description: 'Register a new LLM provider. API keys can be provided directly or via AWS Secrets Manager ARN for secure credential storage.' operationId: createLLMProvider requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateLLMProviderRequest' responses: '201': description: Provider created content: application/json: schema: $ref: '#/components/schemas/LLMProviderResponse' '400': $ref: '#/components/responses/CodedBadRequest' '401': $ref: '#/components/responses/CodedUnauthorized' '409': description: Provider already exists content: application/json: schema: $ref: '#/components/schemas/LLMProviderAPIError' servers: - url: https://orchestrator.getaxonflow.com description: Production (SaaS) - url: http://localhost:8081 description: Local Development /api/v1/llm-providers/{name}: get: tags: - LLM Providers summary: Get LLM provider description: Returns details for a specific LLM provider operationId: getLLMProvider parameters: - name: name in: path required: true description: Provider name schema: type: string responses: '200': description: Provider details content: application/json: schema: $ref: '#/components/schemas/LLMProviderResponse' '401': $ref: '#/components/responses/CodedUnauthorized' '404': description: Provider not found content: application/json: schema: $ref: '#/components/schemas/LLMProviderAPIError' put: tags: - LLM Providers summary: Update LLM provider description: 'Update an existing LLM provider configuration. Only provided fields are updated (partial update).' operationId: updateLLMProvider parameters: - name: name in: path required: true description: Provider name schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateLLMProviderRequest' responses: '200': description: Provider updated content: application/json: schema: $ref: '#/components/schemas/LLMProviderResponse' '400': $ref: '#/components/responses/CodedBadRequest' '401': $ref: '#/components/responses/CodedUnauthorized' '404': description: Provider not found content: application/json: schema: $ref: '#/components/schemas/LLMProviderAPIError' delete: tags: - LLM Providers summary: Delete LLM provider description: Remove an LLM provider configuration operationId: deleteLLMProvider parameters: - name: name in: path required: true description: Provider name schema: type: string responses: '204': description: Provider deleted '401': $ref: '#/components/responses/CodedUnauthorized' '404': description: Provider not found content: application/json: schema: $ref: '#/components/schemas/LLMProviderAPIError' servers: - url: https://orchestrator.getaxonflow.com description: Production (SaaS) - url: http://localhost:8081 description: Local Development /api/v1/llm-providers/{name}/health: get: tags: - LLM Providers summary: Get provider health description: Check health status of a specific LLM provider operationId: getLLMProviderHealth parameters: - name: name in: path required: true description: Provider name schema: type: string responses: '200': description: Provider health status content: application/json: schema: $ref: '#/components/schemas/LLMProviderHealthResponse' '401': $ref: '#/components/responses/CodedUnauthorized' '404': description: Provider not found content: application/json: schema: $ref: '#/components/schemas/LLMProviderAPIError' servers: - url: https://orchestrator.getaxonflow.com description: Production (SaaS) - url: http://localhost:8081 description: Local Development /api/v1/llm-providers/{name}/test: post: tags: - LLM Providers summary: Test LLM provider connection description: 'Tests a provider connection by making a simple API call. Returns success status and latency information.' operationId: testLLMProvider parameters: - name: name in: path required: true description: Provider name schema: type: string requestBody: required: false content: application/json: schema: type: object properties: prompt: type: string description: Optional test prompt (default is simple greeting) example: Say hello in one word. model: type: string description: Optional model to test with responses: '200': description: Provider test result content: application/json: schema: type: object properties: success: type: boolean provider: type: string latency_ms: type: number response: type: string description: Model response (if successful) error: type: string description: Error message (if failed) example: success: true provider: openai latency_ms: 245 response: Hello! '401': $ref: '#/components/responses/CodedUnauthorized' '404': description: Provider not found content: application/json: schema: $ref: '#/components/schemas/LLMProviderAPIError' '500': description: 'The provider connection test failed. `error.code` is `TEST_FAILED`. This replaces a documented `503` with a `{success, error}` body that the handler never emitted in any shape - handleTestProvider answers a failed connection with 500 through the same coded writeError as its other refusals. The 503 was found by the error-family guard, which reported this operation as mixing the two families; it was not mixing them, it was documenting one response that did not exist. ' content: application/json: schema: $ref: '#/components/schemas/LLMProviderAPIError' servers: - url: https://orchestrator.getaxonflow.com description: Production (SaaS) - url: http://localhost:8081 description: Local Development /api/v1/llm-providers/status: get: tags: - LLM Providers summary: Get all providers status description: 'Returns status information for all configured LLM providers. Includes enabled status, configuration summary, and last health check.' operationId: getAllLLMProvidersStatus responses: '200': description: All providers status content: application/json: schema: type: object properties: providers: type: array items: type: object properties: name: type: string type: type: string enabled: type: boolean healthy: type: boolean last_check: type: string format: date-time models_count: type: integer example: providers: - name: openai-primary type: openai enabled: true healthy: true last_check: '2025-01-03T10:30:00Z' models_count: 5 - name: anthropic-backup type: anthropic enabled: true healthy: true last_check: '2025-01-03T10:30:00Z' models_count: 3 '401': $ref: '#/components/responses/CodedUnauthorized' servers: - url: https://orchestrator.getaxonflow.com description: Production (SaaS) - url: http://localhost:8081 description: Local Development /api/v1/llm-providers/routing: get: tags: - LLM Providers summary: Get routing configuration description: Get current LLM provider routing weights operationId: getLLMRoutingConfig responses: '200': description: Routing configuration content: application/json: schema: $ref: '#/components/schemas/LLMRoutingConfigResponse' '401': $ref: '#/components/responses/CodedUnauthorized' put: tags: - LLM Providers summary: Update routing weights description: 'Update LLM provider routing weights. Weights are integers representing relative priority.' operationId: updateLLMRoutingWeights requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateLLMRoutingRequest' responses: '200': description: Routing weights updated content: application/json: schema: $ref: '#/components/schemas/LLMRoutingConfigResponse' '400': $ref: '#/components/responses/CodedBadRequest' '401': $ref: '#/components/responses/CodedUnauthorized' servers: - url: https://orchestrator.getaxonflow.com description: Production (SaaS) - url: http://localhost:8081 description: Local Development components: schemas: LLMRoutingConfigResponse: type: object properties: weights: type: object additionalProperties: type: integer description: Provider name to weight mapping example: openai: 100 anthropic: 80 bedrock: 60 LLMProviderResource: type: object description: LLM provider configuration properties: name: type: string description: Unique provider name type: type: string enum: - openai - azure-openai - anthropic - bedrock - ollama - gemini - custom description: Provider type endpoint: type: string description: API endpoint URL model: type: string description: Default model name region: type: string description: AWS region (for Bedrock) enabled: type: boolean description: Whether provider is enabled priority: type: integer description: Routing priority (lower = higher priority) weight: type: integer description: Routing weight for load balancing rate_limit: type: integer description: Max requests per second timeout_seconds: type: integer description: Request timeout in seconds has_api_key: type: boolean description: Whether API key is configured (key not exposed) settings: type: object additionalProperties: true description: Provider-specific settings health: $ref: '#/components/schemas/LLMProviderHealthInfo' UpdateLLMProviderRequest: type: object description: Partial update - only provided fields are updated properties: api_key: type: string api_key_secret_arn: type: string endpoint: type: string model: type: string region: type: string enabled: type: boolean priority: type: integer weight: type: integer rate_limit: type: integer timeout_seconds: type: integer settings: type: object additionalProperties: true CreateLLMProviderRequest: type: object required: - name - type properties: name: type: string description: Unique provider name type: type: string enum: - openai - azure-openai - anthropic - bedrock - ollama - gemini - custom api_key: type: string description: API key (mutually exclusive with api_key_secret_arn) api_key_secret_arn: type: string description: AWS Secrets Manager ARN for API key endpoint: type: string description: API endpoint URL model: type: string description: Default model name region: type: string description: AWS region (for Bedrock) enabled: type: boolean default: true priority: type: integer default: 100 weight: type: integer default: 100 rate_limit: type: integer description: Max requests per second timeout_seconds: type: integer default: 30 settings: type: object additionalProperties: true LLMProviderListResponse: type: object properties: providers: type: array items: $ref: '#/components/schemas/LLMProviderResource' pagination: $ref: '#/components/schemas/PaginationMeta' LLMProviderResponse: type: object properties: provider: $ref: '#/components/schemas/LLMProviderResource' PaginationMeta: type: object description: Pagination metadata for list responses properties: page: type: integer description: Current page number (1-indexed) example: 1 page_size: type: integer description: Number of items per page example: 20 total_items: type: integer description: Total number of items across all pages example: 42 total_pages: type: integer description: Total number of pages example: 3 ProviderStatusResponse: type: object properties: providers: type: array items: type: object properties: name: type: string available: type: boolean models: type: array items: type: string weight: type: number avg_latency_ms: type: integer CodedErrorResponse: type: object description: 'The CODED error envelope: `{error: {code, message}}`, where `code` is a screaming-snake string enum. This is what the per-handler `writeError` methods emit across the policy API, the LLM provider API, the agents, template, unified-execution and media-governance APIs, and every handler in the RBI module (362 call sites in total). It is one of TWO error SHAPES this document describes. `code` is a STRING on this envelope; it is never an HTTP status integer. `LLMProviderAPIError` is this shape with the `code` enum constrained to the five values the LLM-provider handlers emit. ' properties: error: type: object properties: code: type: string description: Machine-readable error code, screaming snake case. example: NOT_FOUND message: type: string required: - code - message required: - error LLMProviderHealthResponse: type: object properties: name: type: string health: $ref: '#/components/schemas/LLMProviderHealthInfo' LLMProviderHealthInfo: type: object description: Provider health status properties: status: type: string enum: - healthy - unhealthy - unknown message: type: string description: Health check message last_checked: type: string format: date-time description: Last health check timestamp UpdateLLMRoutingRequest: type: object required: - weights properties: weights: type: object additionalProperties: type: integer description: Provider name to weight mapping LLMProviderAPIError: description: 'A REFINEMENT OF `CodedErrorResponse`, not a third envelope: the same `{error: {code, message}}` shape with `code` constrained to the five values the LLM-provider handlers emit. It is kept rather than collapsed into `CodedErrorResponse` because the enum is real information a generated client can switch on, and deleting it to make a count come out at two would make the document less precise in order to make a sentence in it true. The error-family guard classifies it as a member of the coded family, so an operation cannot mix it with the flat family and pass. ' type: object properties: error: type: object properties: code: type: string enum: - NOT_FOUND - ALREADY_EXISTS - INVALID_REQUEST - UNAUTHORIZED - INTERNAL_ERROR message: type: string ErrorResponse: type: object description: 'The FLAT error envelope: `{success, error}`. This is what `sendErrorResponse` emits, which is the orchestrator''s dominant error writer (240 call sites), so it is the shape of every error from the core request, audit, plan, workflow, execution and connector surfaces. It is one of THREE error SHAPES this document describes. See `CodedErrorResponse` and `TripletErrorResponse` for the other two, and the note on `components.responses` for why there is more than one. `LLMProviderAPIError` is a code-constrained refinement of the coded shape, not a fourth shape. This paragraph said "TWO" until issue #3941. `TripletErrorResponse` was added by the #3901 reconciliation and this sentence was not updated with it, so the document undercounted its own families — which is the same defect one level up as the operations that named the wrong one. ' properties: success: type: boolean example: false error: type: string description: Human-readable message. There is no machine-readable code on this envelope. required: - success - error responses: CodedUnauthorized: description: Unauthorized - missing or invalid organization scope (coded envelope) content: application/json: schema: $ref: '#/components/schemas/CodedErrorResponse' example: error: code: UNAUTHORIZED message: Organization ID required BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Invalid request body CodedBadRequest: description: Invalid request (coded envelope) content: application/json: schema: $ref: '#/components/schemas/CodedErrorResponse' example: error: code: INVALID_INPUT message: connector_name is required securitySchemes: basicAuth: type: http scheme: basic description: OAuth2-style client credentials (clientId:clientSecret) BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Enterprise JWT token (see /scripts/generate-jwt.sh) x-refined-from: - axonflow-orchestrator-api.yaml - axonflow-orchestrator-openapi.yml