openapi: 3.1.0
info:
  title: Pioneer Inference anthropic-compat API
  version: 1.0.0
  description: Public inference API for Pioneer AI. Covers the Pioneer-native endpoint, OpenAI-compatible endpoints (/v1/chat/completions, /v1/completions, /v1/models), the Anthropic-compatible endpoint (/v1/messages), and inference history. Authenticate with an X-API-Key header (keys begin with pio_sk_).
  contact:
    name: Pioneer AI
    url: https://docs.pioneer.ai
    email: support@pioneer.ai
servers:
- url: https://api.pioneer.ai
  description: Production
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: anthropic-compat
  description: Anthropic-compatible endpoints. Use with the Anthropic SDK by setting base_url=https://api.pioneer.ai.
paths:
  /v1/models:
    get:
      operationId: list_models
      summary: List available models
      description: Returns the Pioneer model catalog including base encoder models (GLiNER), base decoder LLMs, and any fine-tuned models you have deployed. Compatible with both Anthropic and OpenAI model-list consumers.
      tags:
      - anthropic-compat
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
        description: Maximum number of models to return. Omit for the full catalog.
      - name: before_id
        in: query
        schema:
          type: string
        description: Cursor for paginating backward (Anthropic-style).
      - name: after_id
        in: query
        schema:
          type: string
        description: Cursor for paginating forward (Anthropic-style).
      responses:
        '200':
          description: Combined Anthropic-compatible and OpenAI-compatible model catalog.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/messages:
    post:
      operationId: create_message
      summary: Messages (Anthropic-compatible)
      description: Anthropic Messages API compatible endpoint. Works with the Anthropic Python SDK by setting `base_url="https://api.pioneer.ai"`. Set `stream=true` for SSE streaming in Anthropic event format. Extended-thinking is supported via the `thinking` field.
      tags:
      - anthropic-compat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnthropicMessagesRequest'
            examples:
              simple:
                summary: Simple message
                value:
                  model: claude-sonnet-4-6
                  max_tokens: 1024
                  messages:
                  - role: user
                    content: Hello, Claude!
              with_system:
                summary: Message with system prompt
                value:
                  model: claude-sonnet-4-6
                  max_tokens: 512
                  system: You are a helpful assistant.
                  messages:
                  - role: user
                    content: What is the weather like?
              streaming:
                summary: Streaming message
                value:
                  model: claude-sonnet-4-6
                  max_tokens: 1024
                  stream: true
                  messages:
                  - role: user
                    content: Write a haiku about inference routing.
      responses:
        '200':
          description: Message response. `application/json` when `stream=false`, `text/event-stream` SSE (Anthropic event format) when `stream=true`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnthropicMessagesResponse'
            text/event-stream:
              schema:
                type: string
              example: 'event: message_start

                data: {"type":"message_start","message":{"id":"msg_abc","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-6","stop_reason":null,"usage":{"input_tokens":10,"output_tokens":0}}}


                event: content_block_delta

                data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}


                event: message_stop

                data: {"type":"message_stop"}


                '
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/ModelNotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    RateLimited:
      description: Rate limit exceeded. Retry after the duration in the `Retry-After` response header.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentRequired:
      description: Insufficient credits or no active billing plan.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Request body failed schema validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
    ModelNotFound:
      description: Model ID not found or not yet deployed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ModelListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Model identifier used in API requests.
              type:
                type: string
                enum:
                - model
              display_name:
                type: string
              created_at:
                type: string
                format: date-time
        has_more:
          type: boolean
        first_id:
          type: string
        last_id:
          type: string
    AnthropicMessagesRequest:
      type: object
      required:
      - model
      - messages
      - max_tokens
      properties:
        model:
          type: string
          description: Model ID (e.g. `claude-sonnet-4-6`, `claude-opus-4-8`).
        messages:
          type: array
          minItems: 1
          items:
            type: object
            required:
            - role
            - content
            properties:
              role:
                type: string
                enum:
                - user
                - assistant
              content:
                oneOf:
                - type: string
                - type: array
                  items:
                    type: object
        max_tokens:
          type: integer
          minimum: 1
          maximum: 131072
          default: 1024
        system:
          oneOf:
          - type: string
          - type: array
            items:
              type: object
          description: System prompt. Accepts a plain string or list of Anthropic system content blocks (with cache_control support).
        temperature:
          type: number
          minimum: 0.0
          maximum: 1.0
        top_p:
          type: number
          minimum: 0.0
          maximum: 1.0
        top_k:
          type: integer
          minimum: 1
        stream:
          type: boolean
          default: false
        stop_sequences:
          type: array
          items:
            type: string
        tools:
          type: array
          items:
            type: object
        tool_choice:
          type: object
        thinking:
          type: object
          description: 'Anthropic-native extended-thinking config. Examples: `{"type": "enabled", "budget_tokens": 8000}` for manual mode; `{"type": "adaptive", "effort": "high"}` for adaptive mode (required on Opus 4.7+); `{"type": "disabled"}` to turn off. Pioneer auto-upgrades manual configs on models that require adaptive.'
        store:
          type: boolean
          default: true
          description: Persist to inference history. Set false to opt out.
        schema:
          oneOf:
          - type: object
          - type: array
            items:
              type: string
          description: 'Pioneer encoder extension: extraction schema dict.'
    ValidationErrorResponse:
      type: object
      properties:
        detail:
          type: array
          items:
            type: object
            properties:
              loc:
                type: array
                items:
                  oneOf:
                  - type: string
                  - type: integer
              msg:
                type: string
              type:
                type: string
    ErrorResponse:
      type: object
      properties:
        detail:
          oneOf:
          - type: string
          - type: object
          description: Human-readable error message or structured detail object.
    AnthropicMessagesResponse:
      type: object
      required:
      - id
      - type
      - role
      - content
      - model
      - stop_reason
      - usage
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - message
        role:
          type: string
          enum:
          - assistant
        content:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - text
                - tool_use
                - thinking
              text:
                type: string
        model:
          type: string
        stop_reason:
          type: string
          enum:
          - end_turn
          - max_tokens
          - stop_sequence
          - tool_use
        stop_sequence:
          type: string
        usage:
          type: object
          properties:
            input_tokens:
              type: integer
            output_tokens:
              type: integer
            cache_read_input_tokens:
              type: integer
            cache_creation_input_tokens:
              type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Pioneer API key. Generate one at https://agent.pioneer.ai/settings/api-keys. Keys begin with `pio_sk_`.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Supabase access token or Pioneer API key as a Bearer token.