openapi: 3.1.0
info:
  title: Allecta API
  version: 2.0.0
  description: |
    Multi-model AI arbitration and trust layer.

    Allecta fans your queries out to multiple AI models, cross-verifies their outputs,
    synthesizes a consensus answer, and returns it with a truth_score and citations.

    ## OpenAI Compatible

    The `/v1/chat/completions` endpoint accepts the standard OpenAI request format.
    Any OpenAI SDK client works out of the box — just change the base_url:

    ```python
    from openai import OpenAI
    client = OpenAI(base_url="https://api.allecta.ai/v1", api_key="allecta_...")
    response = client.chat.completions.create(model="allecta-1", messages=[...])
    ```

    ## Authentication

    Use Bearer token authentication:
    ```
    Authorization: Bearer allecta_...
    ```
    Get your API key at https://allecta.ai/dashboard

  contact:
    name: Allecta
    url: https://allecta.ai
    email: hello@allecta.ai
  license:
    name: Proprietary

servers:
  - url: https://api.allecta.ai/v1
    description: Production

security:
  - BearerAuth: []

tags:
  - name: Chat
    description: OpenAI-compatible chat completions
  - name: Reasoning
    description: Allecta-native multi-model reasoning
  - name: Enterprise
    description: Arbitration and trust verification
  - name: Evaluation
    description: Ranking and evaluation
  - name: Management
    description: Keys, webhooks, usage, and configuration

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: "API key: `Authorization: Bearer allecta_...`"

  schemas:
    ChatCompletionRequest:
      type: object
      required: [model, messages]
      properties:
        model:
          type: string
          default: allecta-1
          description: Model ID. Use "allecta-1" for multi-model arbitration.
        messages:
          type: array
          minItems: 1
          items:
            type: object
            required: [role, content]
            properties:
              role:
                type: string
                enum: [system, user, assistant]
              content:
                type: string
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 0.7
        max_tokens:
          type: integer
          minimum: 1
        stream:
          type: boolean
          default: false
        stop:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        allecta:
          type: object
          description: Allecta-specific extensions (optional, non-breaking).
          properties:
            domain:
              type: string
              enum: [general, code, legal, finance, medical-lite]
            deep_research:
              type: boolean
            think_mode:
              type: boolean

    ChatCompletionResponse:
      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
              finish_reason:
                type: string
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer
        allecta:
          type: object
          description: Allecta-specific metadata.
          properties:
            truth_score:
              type: number
              description: Factual accuracy confidence (0-1).
            consensus_strength:
              type: number
              description: Model agreement level (0-1).
            trace_id:
              type: string
            citations:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                  url:
                    type: string
            uncertainty_flags:
              type: array
              items:
                type: string

    ReasonRequest:
      type: object
      required: [input]
      properties:
        input:
          type: object
          required: [messages]
          properties:
            messages:
              type: array
              minItems: 1
              items:
                type: object
                properties:
                  role:
                    type: string
                    enum: [user, assistant, system]
                  content:
                    type: string
        domain:
          type: string
          enum: [general, code, legal, finance, medical-lite]
        budget:
          type: object
          properties:
            tokens:
              type: integer
            maxModels:
              type: integer
            timeoutMs:
              type: integer

    AllectaResponse:
      type: object
      properties:
        id:
          type: string
        model:
          type: string
          enum: [allecta-1]
        output:
          type: object
          properties:
            role:
              type: string
            content:
              type: string
        confidence:
          type: object
          properties:
            truth_score:
              type: number
            consensus_strength:
              type: number
            uncertainty_flags:
              type: array
              items:
                type: string
        citations:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              url:
                type: string
        trace_id:
          type: string
        latency_ms:
          type: integer
        tokens_used:
          type: integer

    ArbitrateRequest:
      type: object
      required: [task, risk_level, arbitration_mode]
      properties:
        task:
          type: string
          maxLength: 10000
        agent_output:
          type: string
          maxLength: 50000
        risk_level:
          type: string
          enum: [low, medium, high]
        domain:
          type: string
        arbitration_mode:
          type: string
          enum: [light, standard, strict]
        request_id:
          type: string

    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            param:
              type: string
              nullable: true
            code:
              type: string
              nullable: true

paths:
  /chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create chat completion (OpenAI-compatible)
      description: |
        Standard OpenAI chat completions format. Works with any OpenAI SDK.
        Allecta-specific metadata returned in the `allecta` extension field.
      tags: [Chat]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Chat completion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              description: SSE stream when stream=true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid API key
        '429':
          description: Rate limit exceeded

  /reason:
    post:
      operationId: reason
      summary: Multi-model reasoning (Allecta native format)
      tags: [Reasoning]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReasonRequest'
      responses:
        '200':
          description: Allecta response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllectaResponse'

  /reason/stream:
    get:
      operationId: streamReason
      summary: Stream reasoning via SSE
      tags: [Reasoning]
      parameters:
        - name: prompt
          in: query
          required: true
          schema:
            type: string
        - name: domain
          in: query
          schema:
            type: string
            enum: [general, code, legal, finance, medical-lite]
      responses:
        '200':
          description: SSE event stream
          content:
            text/event-stream: {}

  /rank:
    post:
      operationId: rank
      summary: Rank candidate answers
      tags: [Evaluation]
      responses:
        '200':
          description: Ranked results

  /synthesize:
    post:
      operationId: synthesize
      summary: Synthesize from candidate outputs
      tags: [Evaluation]
      responses:
        '200':
          description: Synthesized output

  /evaluate:
    post:
      operationId: evaluate
      summary: Evaluate against dataset
      tags: [Evaluation]
      responses:
        '200':
          description: Evaluation results

  /arbitrate:
    post:
      operationId: arbitrate
      summary: Enterprise arbitration
      description: Verify and score AI agent outputs with multi-model consensus.
      tags: [Enterprise]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArbitrateRequest'
      responses:
        '200':
          description: Arbitration result

  /usage:
    get:
      operationId: getUsage
      summary: Get usage metrics
      tags: [Management]
      parameters:
        - name: startDate
          in: query
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          schema:
            type: string
            format: date
        - name: groupBy
          in: query
          schema:
            type: string
            enum: [day, hour, endpoint]
      responses:
        '200':
          description: Usage records

  /keys:
    post:
      operationId: createKey
      summary: Create API key
      tags: [Management]
      responses:
        '200':
          description: New API key
    get:
      operationId: listKeys
      summary: List API keys
      tags: [Management]
      responses:
        '200':
          description: API keys

  /webhooks:
    post:
      operationId: createWebhook
      summary: Create webhook
      tags: [Management]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url, events]
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    type: string
                    enum: [usage.created, turn.completed, eval.completed, billing.threshold_reached, error.raised, arbitration.completed]
      responses:
        '200':
          description: Webhook created
    get:
      operationId: listWebhooks
      summary: List webhooks
      tags: [Management]
      responses:
        '200':
          description: Webhooks

  /models/providers:
    post:
      operationId: registerProvider
      summary: Register BYOM provider
      tags: [Management]
      responses:
        '200':
          description: Provider registered
    get:
      operationId: listProviders
      summary: List providers
      tags: [Management]
      responses:
        '200':
          description: Providers

externalDocs:
  description: Full Documentation
  url: https://docs.allecta.ai