openapi: 3.2.0
info:
  description: The LocalAI Rest API.
  title: LocalAI Router API
  contact:
    name: LocalAI
    url: https://localai.io
  license:
    name: MIT
    url: https://raw.githubusercontent.com/mudler/LocalAI/master/LICENSE
  version: 2.0.0
servers:
- url: /
tags:
- name: router
paths:
  /api/router/decide:
    post:
      tags:
      - router
      summary: Classify a prompt against a router model's policies (decision oracle)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schema.RouterDecideResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/schema.RouterDecideRequest'
        description: decide params
        required: true
  /api/router/{name}/corpus:
    post:
      tags:
      - router
      summary: Seed the KNN routing corpus with labelled example prompts
      parameters:
      - description: router model name
        name: name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schema.RouterCorpusAddResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/schema.RouterCorpusAddRequest'
        description: labelled exemplars
        required: true
    delete:
      tags:
      - router
      summary: Clear a router's KNN corpus
      parameters:
      - description: router model name
        name: name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schema.RouterCorpusClearResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
  /api/router/{name}/corpus/stats:
    get:
      tags:
      - router
      summary: Inspect a router's KNN corpus (label counts only, never texts)
      parameters:
      - description: router model name
        name: name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schema.RouterCorpusStatsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
components:
  schemas:
    schema.RouterDecideNeighbor:
      type: object
      properties:
        id:
          type: string
        labels:
          type: array
          items:
            type: string
        similarity:
          type: number
    schema.RouterCorpusAddRequest:
      type: object
      properties:
        entries:
          type: array
          items:
            $ref: '#/components/schemas/schema.RouterCorpusEntry'
    schema.RouterDecideResponse:
      type: object
      properties:
        cache_similarity:
          description: 'CacheSimilarity carries the cosine similarity of the cache hit

            (0 when not cached).'
          type: number
        cached:
          description: 'Cached is true when the decision came from the L2 embedding

            cache rather than a fresh classifier run.'
          type: boolean
        candidate:
          description: 'Candidate is the model that would be routed to. Empty when no

            candidate covers Labels AND no fallback is configured.'
          type: string
        classifier:
          description: 'Classifier is the classifier name that produced the decision

            (e.g. "score").'
          type: string
        fallback:
          description: 'Fallback is true when Candidate is the router''s configured

            fallback because no candidate covered Labels. Lets callers

            distinguish "matched" from "fell back" without comparing names.'
          type: boolean
        labels:
          description: Labels is the set of active policy labels.
          type: array
          items:
            type: string
        latency_ms:
          description: LatencyMs is the classifier's wall-clock cost.
          type: integer
        nearest_similarity:
          description: 'NearestSimilarity is the cosine similarity of the closest KNN

            corpus entry — populated by the knn classifier even when the

            decision fell back because the probe was out of corpus range.

            0 for other classifiers.'
          type: number
        neighbors:
          description: 'Neighbors lists the corpus entries the knn classifier retrieved,

            by descending similarity, including ones below the similarity

            gate. Empty for other classifiers.'
          type: array
          items:
            $ref: '#/components/schemas/schema.RouterDecideNeighbor'
        router:
          description: Router echoes the requested router model.
          type: string
        score:
          description: 'Score is the top label''s softmax probability (the

            classifier-side confidence signal).'
          type: number
    schema.RouterCorpusEntry:
      type: object
      properties:
        labels:
          type: array
          items:
            type: string
        text:
          type: string
    schema.RouterDecideRequest:
      type: object
      properties:
        input:
          description: 'Input is the user-visible prompt text to classify. Required.

            Schema-shape extraction (chat-message concatenation, etc.) is

            the caller''s responsibility — matches the Probe contract used

            by the in-band middleware.'
          type: string
        router:
          description: 'Router is the name of the router model (a ModelConfig with a

            `router:` block). Required.'
          type: string
    schema.RouterCorpusStatsResponse:
      type: object
      properties:
        embedding_model:
          type: string
        embedding_models:
          description: 'EmbeddingModels lists the embedder fingerprints present in the

            persisted corpus; more than one means part of the corpus is

            pending re-embedding on the next load.'
          type: array
          items:
            type: string
        label_counts:
          type: object
          additionalProperties:
            type: integer
        router:
          type: string
        store_name:
          type: string
        total:
          type: integer
    schema.RouterCorpusClearResponse:
      type: object
      properties:
        cleared:
          type: integer
        router:
          type: string
    schema.RouterCorpusAddResponse:
      type: object
      properties:
        added:
          description: Added is how many entries were embedded, persisted, and indexed.
          type: integer
        label_counts:
          description: LabelCounts is the per-label exemplar count after the call.
          type: object
          additionalProperties:
            type: integer
        router:
          type: string
        skipped:
          description: 'Skipped counts entries whose text was already in the corpus —

            duplicates are rejected rather than double-weighted.'
          type: integer
        total:
          description: Total is the corpus size after the call.
          type: integer
  securitySchemes:
    BearerAuth:
      type: apiKey
      name: Authorization
      in: header