AxonFlow LLM Providers API

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