openapi: 3.0.3
info:
  title: SOAT Model Routes API
  version: 1.0.0
  description: API for managing model routes (ordered provider failover)
  contact:
    name: SOAT Team
    url: https://github.com/ttoss/soat
servers:
  - url: '{baseUrl}'
    description: Base URL of your SOAT deployment (e.g. https://your-soat.com or http://localhost:5047)
    variables:
      baseUrl:
        description: The base URL of your SOAT deployment
        default: http://localhost:5047
tags:
  - name: Model Routes
    description: Manage ordered provider+model failover routes
security:
  - bearerAuth: []
paths:
  /api/v1/model-routes:
    get:
      tags:
        - Model Routes
      summary: List model routes
      description: Returns the model routes defined in a project
      operationId: listModelRoutes
      parameters:
        - name: project_id
          in: query
          description: Project ID (required if not using project key auth)
          schema:
            type: string
            example: proj_V1StGXR8Z5jdHi6B
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return
          schema:
            type: integer
            default: 50
        - name: offset
          in: query
          required: false
          description: Number of results to skip
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of model routes
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - total
                  - limit
                  - offset
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ModelRoute'
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
    post:
      tags:
        - Model Routes
      summary: Create a model route
      description: >-
        Creates a project-scoped model route: a named, ordered list of
        provider+model targets tried in array order. Every target must reference
        an AI provider in the same project (400 otherwise), and the total attempt
        budget — the sum of `1 + max_retries` over all targets — may not exceed
        10 (400 naming the computed total). A duplicate `name` in the project is
        rejected with 409.
      operationId: createModelRoute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - targets
              properties:
                project_id:
                  x-soat-ref: projects
                  type: string
                  description: Project ID (required if not using project key auth)
                  example: proj_V1StGXR8Z5jdHi6B
                name:
                  type: string
                  description: Human-readable name, unique per project
                  example: primary-with-fallback
                targets:
                  type: array
                  minItems: 1
                  description: >-
                    Ordered failover targets. Position is priority: target 0 is
                    tried first, and a retryable failure falls through to the
                    next target.
                  items:
                    $ref: '#/components/schemas/ModelRouteTarget'
                retry_on:
                  type: array
                  description: >-
                    Which failure classes are failover-eligible. A failure whose
                    class is not listed (and every deterministic failure —
                    400-class, auth, content policy) fails the generation
                    immediately instead of spending another target's budget.
                  items:
                    type: string
                    enum: [provider_error, timeout, rate_limited]
                  default: [provider_error, timeout, rate_limited]
                failure_threshold:
                  type: integer
                  default: 3
                  description: >-
                    Consecutive retryable failures after which a target is
                    skipped for `cooldown_seconds`. Breaker state is in-process
                    per node and keyed by (provider, model), so it is shared by
                    every route pointing at the same backend.
                  example: 3
                cooldown_seconds:
                  type: integer
                  default: 60
                  description: How long a tripped target is skipped before being probed again
                  example: 60
      responses:
        '201':
          description: Model route created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelRoute'
        '400':
          description: Bad request (invalid targets, attempt cap exceeded, unknown provider)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '409':
          description: A model route with this name already exists in the project
        '500':
          description: Internal server error
  /api/v1/model-routes/{route_id}:
    get:
      tags:
        - Model Routes
      summary: Get a model route
      description: Returns a specific model route
      operationId: getModelRoute
      parameters:
        - name: route_id
          in: path
          required: true
          description: Model route ID
          schema:
            type: string
            example: route_V1StGXR8Z5jdHi6B
      responses:
        '200':
          description: Model route details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelRoute'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Model route not found
    put:
      tags:
        - Model Routes
      summary: Update a model route
      description: >-
        Updates a model route's name, targets, retry classes, or breaker
        configuration. Omitted fields are left unchanged.
      operationId: updateModelRoute
      parameters:
        - name: route_id
          in: path
          required: true
          description: Model route ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: New name (unique per project)
                targets:
                  type: array
                  minItems: 1
                  description: Replacement target list (ordered)
                  items:
                    $ref: '#/components/schemas/ModelRouteTarget'
                retry_on:
                  type: array
                  items:
                    type: string
                    enum: [provider_error, timeout, rate_limited]
                failure_threshold:
                  type: integer
                cooldown_seconds:
                  type: integer
      responses:
        '200':
          description: Model route updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelRoute'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Model route not found
        '409':
          description: A model route with this name already exists in the project
    delete:
      tags:
        - Model Routes
      summary: Delete a model route
      description: >-
        Deletes a model route. Returns 409 when an agent still references it —
        a routed agent has no pinned provider to fall back on, so the reference
        must be repointed or the agent deleted first.
      operationId: deleteModelRoute
      parameters:
        - name: route_id
          in: path
          required: true
          description: Model route ID
          schema:
            type: string
      responses:
        '204':
          description: Model route deleted successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Model route not found
        '409':
          description: The model route is still referenced by one or more agents
components:
  schemas:
    ModelRouteTarget:
      type: object
      required:
        - ai_provider_id
        - model
      properties:
        ai_provider_id:
          x-soat-ref: ai-providers
          type: string
          description: AI provider in the route's project
          example: aip_V1StGXR8Z5jdHi6B
        model:
          type: string
          description: Model name to call on that provider
          example: gpt-4o-mini
        timeout_seconds:
          type: integer
          description: >-
            Per-attempt deadline, enforced with an AbortSignal composed with the
            caller's signal. A timeout classifies as `timeout`; the caller's own
            signal firing aborts the run without failover. Omitted means no
            per-target deadline.
          example: 30
        max_retries:
          type: integer
          default: 0
          description: >-
            Retries on this target before falling through to the next one. The
            route is the only retry authority — routed calls pass `maxRetries:
            0` to the AI SDK so its own retry loop cannot multiply these.
          example: 1
    ModelRoute:
      type: object
      properties:
        id:
          type: string
          example: route_V1StGXR8Z5jdHi6B
        project_id:
          x-soat-ref: projects
          type: string
        name:
          type: string
          example: primary-with-fallback
        targets:
          type: array
          items:
            $ref: '#/components/schemas/ModelRouteTarget'
        retry_on:
          type: array
          items:
            type: string
            enum: [provider_error, timeout, rate_limited]
        failure_threshold:
          type: integer
          example: 3
        cooldown_seconds:
          type: integer
          example: 60
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: JWT token or sk_ api key