openapi: 3.1.0
info:
  title: Xantly Gateway API
  version: 1.0.0
  description: >
    Universal API Gateway for intelligent LLM routing, multi-agent
    orchestration, and cost-optimized inference. Production base URL
    is https://api.xantly.com/v1. All requests require a Bearer token.

servers:
  - url: https://api.xantly.com/v1
    description: Production
  - url: http://localhost:8085/v1
    description: Local development

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

  schemas:
    ChatCompletionRequest:
      type: object
      required: [model, messages]
      properties:
        model:
          type: string
          example: auto
        messages:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ChatMessage'
        stream:
          type: boolean
          default: false
        n:
          type: integer
          minimum: 1
          maximum: 8
          default: 1
        max_tokens:
          type: integer
          description: Max completion tokens. Alias accepted by backend: max_completion_tokens.
        temperature:
          type: number
          minimum: 0.0
          maximum: 2.0
        top_p:
          type: number
        frequency_penalty:
          type: number
          minimum: -2.0
          maximum: 2.0
        presence_penalty:
          type: number
          minimum: -2.0
          maximum: 2.0
        stop:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        tools:
          type: array
          items:
            type: object
        tool_choice:
          oneOf:
            - type: string
            - type: object
        parallel_tool_calls:
          type: boolean
        response_format:
          type: object
        seed:
          type: integer
        user:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        logprobs:
          type: boolean
        top_logprobs:
          type: integer
          maximum: 20
        stream_options:
          type: object
          properties:
            include_usage:
              type: boolean
        reasoning_effort:
          type: string
          enum: [low, medium, high]
        service_tier:
          type: string
        routing_hints:
          $ref: '#/components/schemas/RoutingHints'
        routing_override:
          $ref: '#/components/schemas/RoutingOverride'
        xantly:
          $ref: '#/components/schemas/XantlyOrchestration'

    ChatMessage:
      type: object
      required: [role, content]
      properties:
        role:
          type: string
        content:
          oneOf:
            - type: string
            - type: array
        name:
          type: string
        tool_calls:
          type: array
          items:
            type: object
        tool_call_id:
          type: string

    RoutingHints:
      type: object
      description: Soft routing preferences
      properties:
        mode:
          type: string
          enum: [fast, balanced, quality, cost_optimized, free_models_only]
        preference_dial:
          type: number
          minimum: 0.0
          maximum: 1.0
        prefer_latency:
          type: boolean
        prefer_quality:
          type: boolean
        max_cost_per_token:
          type: number
        max_latency_ms:
          type: integer
        max_tier:
          type: integer
          enum: [1, 2, 3]
        required_capabilities:
          type: array
          items:
            type: string
        task_complexity:
          type: string
          enum: [trivial, standard, complex, expert]
        chain_routing:
          type: string
          enum: [sticky, mixed]
        allow_free_fallback:
          type: boolean

    RoutingOverride:
      type: object
      description: Hard routing overrides
      properties:
        force_tier:
          type: string
          enum: [T1, T2, T3]
        force_lane:
          type: string
          enum: [smart, turbo]
        force_provider:
          type: string
        force_model:
          type: string

    XantlyOrchestration:
      type: object
      description: Orchestration controls
      properties:
        workflow_type:
          type: string
          enum:
            [single_turn, execution_task, multi_step_conversational, long_horizon_autonomous, voice_simple, voice_complex, creative]
        chain_id:
          type: string
        conversation_id:
          type: string
        planning_mode:
          type: string
          enum: [preact, planact]
        max_chain_steps:
          type: integer
          minimum: 1
          maximum: 65535
        chain_timeout_secs:
          type: integer
          minimum: 0
          maximum: 4294967295
        chain_routing:
          type: string
          enum: [sticky, mixed]
          description: Accepted for compatibility; prefer routing_hints.chain_routing in current handler path.
        reliability_level:
          type: string
          enum: [standard, high, critical]
        enable_memory:
          type: boolean
          default: true
        enable_speculation:
          type: boolean
        enable_hedging:
          type: boolean
        enable_cache:
          type: boolean
          default: true
        cache_ttl_secs:
          type: integer
          maximum: 86400
        output_verification:
          type: string
          enum: [none, native, schema, cross_model]
        compress_context:
          type: boolean
          description: Accepted for compatibility; reserved in current handler path.
        redact_pii:
          type: boolean
          default: false
        voice_mode:
          type: string
          description: Use "true" to activate voice request handling.
        enable_tool_reranking:
          type: boolean
          description: Accepted for compatibility; reserved in current handler path.

    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum: [chat.completion]
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatChoice'
        usage:
          $ref: '#/components/schemas/Usage'
        xantly_metadata:
          $ref: '#/components/schemas/XantlyMetadata'

    ChatChoice:
      type: object
      properties:
        index:
          type: integer
        message:
          $ref: '#/components/schemas/ChatMessage'
        finish_reason:
          type: string
          enum: [stop, length, tool_calls, content_filter]
        logprobs:
          type: object
          nullable: true

    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer

    XantlyMetadata:
      type: object
      description: Routing, cost, and execution transparency returned on every response.
      properties:
        request_id:
          type: string
          description: Correlation ID for support and audit.
        routing_decision:
          type: string
          description: Human-readable routing summary (lane + decision source).
        provider:
          type: string
          description: Provider that served the request (e.g. "deepseek", "anthropic").
        tier:
          type: string
          description: Effective execution tier ("T1", "T2", "T3").
        provider_tier:
          type: string
          nullable: true
          description: Provider-level tier when different from effective tier.
        latency_ms:
          type: integer
          description: End-to-end gateway latency in milliseconds.
        requested_model:
          type: string
          description: The model string the caller sent (e.g. "auto", "gpt-4o"). Useful for debugging routing when using "auto".
        decision_source:
          type: string
          nullable: true
          description: Machine-readable routing engine source (e.g. "BarpRouter", "Pinned", "CacheHit").
        task_family:
          type: string
          nullable: true
          description: Task category detected by the smart router (e.g. "code", "writing", "analysis").
        cost_usd:
          type: number
          nullable: true
          description: Actual cost for this specific request in USD. Present when usage data is available.
        baseline_cost_usd:
          type: number
          nullable: true
          description: GPT-4o reference cost for the same token counts. Allows computing savings without a separate analytics call.
        savings_usd:
          type: number
          nullable: true
          description: baseline_cost_usd - cost_usd. Positive means Xantly saved money vs GPT-4o.
        savings_pct:
          type: number
          nullable: true
          description: Savings as a percentage of baseline (0-100+).
        cost_attribution:
          type: string
          enum: [xantly, byok]
          description: '"xantly" when using Xantly-managed provider keys; "byok" when using your own API key.'
        estimated_cost_usd:
          type: number
          nullable: true
          description: Legacy alias for cost_usd. Kept for backward compatibility.
        healer_report:
          type: object
          nullable: true
          description: Present when JSON repair was applied.
          properties:
            original:
              type: string
            healed:
              type: string
            stage:
              type: integer
            confidence:
              type: number
            healing_time_ms:
              type: number

    EmbeddingRequest:
      type: object
      required: [model, input]
      properties:
        model:
          type: string
          description: Embedding model slug (e.g. text-embedding-3-small).
          example: text-embedding-3-small
        input:
          oneOf:
            - type: string
              description: Single text to embed.
            - type: array
              items:
                type: string
              description: Batch of texts to embed.

    EmbeddingData:
      type: object
      properties:
        object:
          type: string
          enum: [embedding]
        index:
          type: integer
          description: Position in the input array (0-indexed).
        embedding:
          type: array
          items:
            type: number
          description: Dense vector representation.

    EmbeddingResponse:
      type: object
      properties:
        object:
          type: string
          enum: [list]
        data:
          type: array
          items:
            $ref: '#/components/schemas/EmbeddingData'
        model:
          type: string
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            total_tokens:
              type: integer

    ListModelsResponse:
      type: object
      properties:
        object:
          type: string
          enum: [list]
        data:
          type: array
          items:
            $ref: '#/components/schemas/ModelObject'

    ModelObject:
      type: object
      properties:
        id:
          type: string
          description: Model slug, use as the "model" field in requests.
        object:
          type: string
          enum: [model]
        created:
          type: integer
          description: Unix epoch timestamp.
        owned_by:
          type: string
          description: Provider name (openai, anthropic, deepseek, groq, google, nvidia).

    CompletionRequest:
      type: object
      required: [model]
      properties:
        model:
          type: string
          example: auto
        prompt:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: Text prompt(s). Multiple strings are joined with newlines.
        max_tokens:
          type: integer
        temperature:
          type: number
        top_p:
          type: number
        n:
          type: integer
        stream:
          type: boolean
          description: Not supported, returns validation error. Use /chat/completions.
        logprobs:
          type: integer
        echo:
          type: boolean
        stop:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        presence_penalty:
          type: number
        frequency_penalty:
          type: number
        user:
          type: string

    CompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum: [text_completion]
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
              index:
                type: integer
              logprobs:
                type: object
                nullable: true
              finish_reason:
                type: string
        usage:
          $ref: '#/components/schemas/Usage'

    ResponsesRequest:
      type: object
      required: [model]
      properties:
        model:
          type: string
          example: auto
        input:
          description: String, array of input items, or single input object.
        instructions:
          type: string
          description: System instructions.
        stream:
          type: boolean
          default: false
        temperature:
          type: number
        top_p:
          type: number
        max_output_tokens:
          type: integer
        tools:
          type: array
          items:
            type: object
        tool_choice:
          description: Tool selection strategy.
        parallel_tool_calls:
          type: boolean
        text:
          type: object
          properties:
            format:
              type: object
        user:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        reasoning:
          type: object
          properties:
            effort:
              type: string
              enum: [low, medium, high]

    ResponsesResponse:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: integer
        model:
          type: string
        object:
          type: string
          enum: [response]
        output:
          type: array
          items:
            type: object
            description: Output items (message or function_call).
        usage:
          type: object
          properties:
            input_tokens:
              type: integer
            output_tokens:
              type: integer

    ModerationRequest:
      type: object
      required: [input]
      properties:
        input:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        model:
          type: string

    SpeechRequest:
      type: object
      required: [model, input, voice]
      properties:
        model:
          type: string
          example: tts-1
        input:
          type: string
          description: Text to convert to speech. Max 4096 characters.
        voice:
          type: string
          enum: [alloy, echo, fable, onyx, nova, shimmer]
        response_format:
          type: string
          enum: [mp3, opus, aac, flac, wav, pcm]
          default: mp3
        speed:
          type: number
          minimum: 0.25
          maximum: 4.0
          default: 1.0

    ImageGenerationRequest:
      type: object
      required: [prompt]
      properties:
        prompt:
          type: string
        model:
          type: string
          example: dall-e-3
        n:
          type: integer
          minimum: 1
          maximum: 10
        size:
          type: string
          enum: ['256x256', '512x512', '1024x1024', '1024x1792', '1792x1024']
        quality:
          type: string
          enum: [standard, hd]
        style:
          type: string
          enum: [vivid, natural]
        response_format:
          type: string
          enum: [url, b64_json]
        user:
          type: string

    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type: string
            param:
              type: string
              nullable: true

security:
  - bearerAuth: []

paths:
  /chat/completions:
    head:
      operationId: probeChatCompletion
      summary: Probe chat completion endpoint
      description: Lightweight auth/rate-limit probe. Returns no body.
      responses:
        '204':
          description: Endpoint reachable and authorized.
        '401':
          description: Authentication error.
    post:
      operationId: createChatCompletion
      summary: Create chat completion
      description: Routes to optimal model based on task complexity, cost, latency, and quality.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Successful completion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error.
        '403':
          description: Authorization error.
        '404':
          description: Referenced resource or tool not found.
        '422':
          description: Governance/tool policy rejection.
        '402':
          description: Token quota or monthly budget exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Upstream provider error.
        '503':
          description: Service unavailable (for example, circuit breaker).
        '504':
          description: Upstream timeout.
        '500':
          description: Internal server error.

  /completions:
    post:
      operationId: createCompletion
      summary: Create text completion (legacy)
      description: >
        Legacy prompt-based completions. Translates to chat completions
        internally and routes through the full Xantly pipeline. Use
        /chat/completions for new integrations.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
      responses:
        '200':
          description: Successful completion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompletionResponse'
        '400':
          description: Validation error (e.g. stream=true not supported).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error.
        '429':
          description: Rate limit exceeded.
        '500':
          description: Internal server error.

  /responses:
    post:
      operationId: createResponse
      summary: Create response (Responses API)
      description: >
        Modern OpenAI Responses API. Requests are translated to chat
        completions, routed through the full gateway pipeline, and
        converted back to the Responses format.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error.
        '429':
          description: Rate limit exceeded.
        '500':
          description: Internal server error.

  /models:
    get:
      operationId: listModels
      summary: List available models
      description: Returns all active models in the Xantly catalog. Dynamic, reflects the actual models available for routing.
      responses:
        '200':
          description: List of available models.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
        '401':
          description: Authentication error.

  /models/{model_id}:
    get:
      operationId: retrieveModel
      summary: Retrieve a model
      description: Returns details for a specific model by its slug.
      parameters:
        - name: model_id
          in: path
          required: true
          schema:
            type: string
          description: The model slug (e.g. "gpt-4o", "deepseek-chat").
      responses:
        '200':
          description: Model details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelObject'
        '401':
          description: Authentication error.
        '404':
          description: Model not found.

  /embeddings:
    post:
      operationId: createEmbedding
      summary: Create embeddings
      description: Generate vector embeddings for one or more input strings. Drop-in compatible with the OpenAI Embeddings API.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingRequest'
      responses:
        '200':
          description: Embeddings generated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingResponse'
        '400':
          description: Validation error (missing model or input).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error.
        '402':
          description: Token quota or monthly budget exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: No embedding provider available or provider error.

  /moderations:
    post:
      operationId: createModeration
      summary: Classify text for harmful content
      description: >
        Proxies to OpenAI's content moderation API with automatic BYOK
        key resolution. Returns category flags and confidence scores.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModerationRequest'
      responses:
        '200':
          description: Moderation result.
        '401':
          description: Authentication error.
        '500':
          description: No OpenAI key configured or provider error.

  /audio/transcriptions:
    post:
      operationId: createTranscription
      summary: Transcribe audio (Whisper STT)
      description: >
        Accepts multipart form data with an audio file and proxies to
        OpenAI's Whisper speech-to-text endpoint. Supports BYOK.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file, model]
              properties:
                file:
                  type: string
                  format: binary
                  description: Audio file (mp3, mp4, mpeg, mpga, m4a, wav, webm). Max 25 MB.
                model:
                  type: string
                  example: whisper-1
                language:
                  type: string
                  description: ISO 639-1 language code.
                prompt:
                  type: string
                response_format:
                  type: string
                  enum: [json, text, srt, verbose_json, vtt]
                temperature:
                  type: number
      responses:
        '200':
          description: Transcription result.
        '400':
          description: Invalid multipart data.
        '401':
          description: Authentication error.
        '500':
          description: No OpenAI key configured or provider error.

  /audio/translations:
    post:
      operationId: createTranslation
      summary: Translate audio to English (Whisper)
      description: >
        Accepts multipart form data with an audio file and proxies to
        OpenAI's Whisper translation endpoint. Always outputs English.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file, model]
              properties:
                file:
                  type: string
                  format: binary
                  description: Audio file (mp3, mp4, mpeg, mpga, m4a, wav, webm). Max 25 MB.
                model:
                  type: string
                  example: whisper-1
                prompt:
                  type: string
                response_format:
                  type: string
                  enum: [json, text, srt, verbose_json, vtt]
                temperature:
                  type: number
      responses:
        '200':
          description: Translation result (always in English).
        '400':
          description: Invalid multipart data.
        '401':
          description: Authentication error.
        '500':
          description: No OpenAI key configured or provider error.

  /audio/speech:
    post:
      operationId: createSpeech
      summary: Generate speech (TTS)
      description: >
        Generates audio from text using OpenAI's TTS models.
        Returns raw audio bytes. Supports BYOK.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpeechRequest'
      responses:
        '200':
          description: Audio binary stream.
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
        '401':
          description: Authentication error.
        '500':
          description: No OpenAI key configured or provider error.

  /images/generations:
    post:
      operationId: createImage
      summary: Generate images (DALL-E)
      description: >
        Proxies to OpenAI's DALL-E image generation API with automatic
        BYOK key resolution.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageGenerationRequest'
      responses:
        '200':
          description: Generated images.
        '400':
          description: Invalid request.
        '401':
          description: Authentication error.
        '500':
          description: No OpenAI key configured or provider error.