openapi: 3.0.1
info:
  title: ShuttleAI API
  description: OpenAI-compatible AI API with access to multiple providers.
  version: '1.0'
servers:
  - url: https://api.shuttleai.com
security:
  - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key prefixed with shuttle-
paths:
  /v1/chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create Chat Completion
      description: Generate a text completion for a conversation.
      tags:
        - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - messages
              properties:
                model:
                  type: string
                  description: Model ID (e.g., shuttleai, gpt-5.2, claude-opus-4.6)
                  example: shuttleai/auto
                messages:
                  type: array
                  description: Conversation messages
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - system
                          - user
                          - assistant
                          - tool
                        description: Message role
                      content:
                        type: string
                        description: Message content
                      tool_call_id:
                        type: string
                        description: Tool call ID (required for tool role)
                stream:
                  type: boolean
                  default: false
                  description: Enable streaming (SSE)
                stream_options:
                  type: object
                  properties:
                    include_usage:
                      type: boolean
                      description: Include usage stats in the final stream chunk
                max_tokens:
                  type: integer
                  description: Maximum tokens in the response
                temperature:
                  type: number
                  minimum: 0
                  maximum: 2
                  default: 1
                  description: Sampling temperature (0-2)
                top_p:
                  type: number
                  minimum: 0
                  maximum: 1
                  default: 1
                  description: Nucleus sampling parameter
                frequency_penalty:
                  type: number
                  minimum: -2
                  maximum: 2
                  default: 0
                  description: Frequency penalty (-2 to 2)
                presence_penalty:
                  type: number
                  minimum: -2
                  maximum: 2
                  default: 0
                  description: Presence penalty (-2 to 2)
                stop:
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
                  description: Stop sequence(s)
                tools:
                  type: array
                  description: Tool definitions (function or MCP)
                  items:
                    oneOf:
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - function
                          function:
                            type: object
                            properties:
                              name:
                                type: string
                              description:
                                type: string
                              parameters:
                                type: object
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - mcp
                          server_url:
                            type: string
                          server_label:
                            type: string
                          allowed_tools:
                            type: array
                            items:
                              type: string
                          require_approval:
                            type: string
                          headers:
                            type: object
                tool_choice:
                  description: Tool selection strategy
                  oneOf:
                    - type: string
                      enum:
                        - auto
                        - none
                        - required
                    - type: object
                      properties:
                        type:
                          type: string
                        function:
                          type: object
                          properties:
                            name:
                              type: string
                response_format:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - text
                        - json_object
                  description: Response format (text or JSON)
                reasoning_effort:
                  type: string
                  enum:
                    - none
                    - minimal
                    - low
                    - medium
                    - high
                  description: Extended thinking depth
      responses:
        '200':
          description: Chat completion response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  object:
                    type: string
                    enum:
                      - chat.completion
                  created:
                    type: integer
                  model:
                    type: string
                  choices:
                    type: array
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                        message:
                          type: object
                          properties:
                            role:
                              type: string
                            content:
                              type: string
                            tool_calls:
                              type: array
                              items:
                                type: object
                            reasoning_content:
                              type: string
                        finish_reason:
                          type: string
                  usage:
                    type: object
                    properties:
                      prompt_tokens:
                        type: integer
                      completion_tokens:
                        type: integer
                      total_tokens:
                        type: integer
  /v1/models:
    get:
      operationId: listModels
      summary: List Models
      description: List all available models.
      tags:
        - Models
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum:
              - verbose
          description: Use 'verbose' for detailed model info
      responses:
        '200':
          description: List of models
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        object:
                          type: string
                        plan:
                          type: string
                        request_multiplier:
                          type: number
                        permission:
                          type: object
                          properties:
                            context_length:
                              type: integer
                            max_output:
                              type: integer
                            tool_calling:
                              type: boolean
  /v1/models/{id}:
    get:
      operationId: getModel
      summary: Get Model
      description: Get details for a specific model.
      tags:
        - Models
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Model ID
      responses:
        '200':
          description: Model details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  object:
                    type: string
                  plan:
                    type: string
                  request_multiplier:
                    type: number
                  permission:
                    type: object