openapi: 3.1.0
info:
  title: Pioneer anthropic-compat inference 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: inference
  description: Pioneer-native inference endpoint (encoder NER/classification/extraction and decoder text generation).
paths:
  /inference:
    post:
      operationId: run_inference
      summary: Run inference (Pioneer native)
      description: 'Unified inference endpoint for encoder tasks (NER, text classification, JSON extraction) and decoder tasks (text generation). Discriminated by the presence of a `messages` field: include `messages` for decoder generation; use `text` + `schema` for encoder tasks.'
      tags:
      - inference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/EncoderInferenceRequest'
              - $ref: '#/components/schemas/GenerateInferenceRequest'
            examples:
              encoder_ner:
                summary: NER — extract entities
                value:
                  model_id: YOUR_MODEL_ID
                  text: Apple launched the iPhone 16 in San Francisco.
                  schema:
                    entities:
                    - name: organization
                    - name: product
                    - name: location
              decoder_generate:
                summary: Decoder — text generation
                value:
                  model_id: YOUR_MODEL_ID
                  task: generate
                  messages:
                  - role: user
                    content: Summarize this document in one sentence.
                  max_tokens: 256
                  temperature: 0.7
      responses:
        '200':
          description: Inference result. `type` is `"encoder"` for encoder tasks and `"decoder"` for generation.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/EncoderInferenceResponse'
                - $ref: '#/components/schemas/GenerateInferenceResponse'
                discriminator:
                  propertyName: type
                  mapping:
                    encoder: '#/components/schemas/EncoderInferenceResponse'
                    decoder: '#/components/schemas/GenerateInferenceResponse'
        '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:
    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
    GenerateInferenceRequest:
      type: object
      required:
      - model_id
      - task
      - messages
      description: Request for decoder text generation. Discriminated from EncoderInferenceRequest by the presence of a `messages` field.
      properties:
        model_id:
          type: string
          description: Training job UUID, project name, or base decoder model ID (e.g. `Qwen/Qwen3-8B`).
        task:
          type: string
          enum:
          - generate
        messages:
          type: array
          minItems: 1
          items:
            type: object
            required:
            - role
            - content
            properties:
              role:
                type: string
                enum:
                - system
                - user
                - assistant
              content:
                type: string
          description: Chat messages. The last message must have role `"user"`.
        max_tokens:
          type: integer
          minimum: 1
          maximum: 131072
        temperature:
          type: number
          minimum: 0.0
          maximum: 2.0
        top_p:
          type: number
          minimum: 0.0
          maximum: 1.0
        reasoning:
          $ref: '#/components/schemas/ReasoningConfig'
        include_reasoning_trace:
          type: boolean
          default: false
          description: Return extracted `<think>` trace text separately in the response.
        store:
          type: boolean
          default: true
          description: Persist to inference history. Set false to opt out.
        project_id:
          type: string
    ReasoningConfig:
      type: object
      description: Opt-in reasoning / extended-thinking controls. Normalized across providers — Anthropic (`thinking`), OpenAI/Fireworks (`reasoning_effort`), OpenRouter (`reasoning`). Pioneer does not enable reasoning by default.
      properties:
        enabled:
          type: boolean
          default: true
          description: Set false to explicitly disable thinking on models that have it on by default.
        effort:
          type: string
          enum:
          - minimal
          - low
          - medium
          - high
          - xhigh
          - none
          description: OpenAI/Grok-style effort tier. Mutually exclusive with `max_tokens`.
        max_tokens:
          type: integer
          minimum: 1
          description: Anthropic-style reasoning budget in tokens. Mutually exclusive with `effort`.
        mode:
          type: string
          enum:
          - manual
          - adaptive
          description: Anthropic extended-thinking dispatch mode. Leave unset to let Pioneer pick the per-model default.
        display:
          type: string
          enum:
          - summarized
          - omitted
          description: Whether thinking text streams back (`summarized`) or is omitted to save latency (`omitted`).
        exclude:
          type: boolean
          default: false
          description: Model reasons internally but reasoning tokens are not returned to the caller.
    EncoderInferenceRequest:
      type: object
      required:
      - model_id
      - text
      - schema
      description: Request for encoder (GLiNER) tasks. Discriminated from GenerateInferenceRequest by the absence of a `messages` field.
      properties:
        model_id:
          type: string
          description: Training job UUID, project name, or base encoder model ID (e.g. `fastino/gliner2-base-v1`).
        text:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
          description: Input text or list of texts for batch processing.
        schema:
          oneOf:
          - type: object
            description: 'Unified extraction schema dict with keys: entities, classifications, structures, relations.'
          - type: array
            items:
              type: string
            description: Deprecated flat entity label list. Use the dict form instead.
          description: 'Extraction schema. Use the unified dict form: `{"entities": [{"name": "organization"}]}`.'
        threshold:
          type: number
          minimum: 0.0
          maximum: 1.0
          default: 0.5
          description: Confidence threshold for predictions.
        include_confidence:
          type: boolean
          default: true
        include_spans:
          type: boolean
          default: true
          description: Include character-level start/end positions.
        store:
          type: boolean
          default: true
          description: Persist to inference history. Set false to opt out.
        project_id:
          type: string
          description: Project ID for attribution and auto-improvement.
    ErrorResponse:
      type: object
      properties:
        detail:
          oneOf:
          - type: string
          - type: object
          description: Human-readable error message or structured detail object.
    GenerateInferenceResponse:
      type: object
      required:
      - type
      - inference_id
      - completion
      - model_id
      - latency_ms
      properties:
        type:
          type: string
          enum:
          - decoder
        inference_id:
          type: string
          description: Unique inference ID.
        completion:
          type: string
          description: Generated text.
        reasoning_trace:
          type: string
          description: Extracted `<think>` reasoning trace when `include_reasoning_trace=true`.
        model_id:
          type: string
        latency_ms:
          type: number
    EncoderInferenceResponse:
      type: object
      required:
      - type
      - inference_id
      - result
      - model_id
      - latency_ms
      - token_usage
      - model_used
      properties:
        type:
          type: string
          enum:
          - encoder
        inference_id:
          type: string
          description: Unique inference ID. Use with GET /inferences/{inference_id} or POST /inferences/{inference_id}/feedback.
        result:
          oneOf:
          - type: object
          - type: array
          description: Extraction result. Shape depends on the schema and task.
        model_id:
          type: string
        latency_ms:
          type: number
          description: Server-side inference latency in milliseconds.
        token_usage:
          type: integer
          description: Input tokens processed.
        model_used:
          type: string
          description: Resolved model identifier.
  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.