openapi: 3.1.0
info:
  title: RARA RAG API
  version: 0.1.0
  description: |
    Public online RAG contract. Requests resolve a knowledge base and release
    alias so responses remain attributable to a versioned retrieval policy.
servers:
  - url: http://localhost:18081
paths:
  /healthz:
    get:
      operationId: health
      responses:
        "200":
          description: Process is running.
  /readyz:
    get:
      operationId: ready
      responses:
        "200":
          description: Required dependencies are ready.
        "503":
          description: A required dependency is unavailable.
  /v1/retrieve:
    post:
      operationId: retrieve
      summary: Retrieve versioned evidence from a knowledge base.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RetrieveRequest"
      responses:
        "200":
          description: Ranked evidence.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetrieveResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/Unavailable"
  /v1/answer:
    post:
      operationId: answer
      summary: Retrieve evidence and generate an answer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnswerRequest"
      responses:
        "200":
          description: |
            JSON is returned when stream=false. When stream=true the endpoint
            returns text/event-stream with metadata, evidence, delta, completed,
            or error events.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnswerResponse"
            text/event-stream:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/Unavailable"
components:
  responses:
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: Project, knowledge base, or release was not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unavailable:
      description: The release or one of its integrations is unavailable.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    ReleaseSelector:
      type: object
      required: [project_id, knowledge_base_id]
      properties:
        project_id:
          type: string
          format: uuid
        knowledge_base_id:
          type: string
          format: uuid
        release_alias:
          type: string
          default: production
    RetrieveRequest:
      allOf:
        - $ref: "#/components/schemas/ReleaseSelector"
        - type: object
          required: [query]
          properties:
            query:
              type: string
              minLength: 1
            top_k:
              type: integer
              minimum: 1
              maximum: 100
              default: 10
            filters:
              type: object
              additionalProperties: true
            trace:
              type: boolean
              default: true
    AnswerRequest:
      allOf:
        - $ref: "#/components/schemas/RetrieveRequest"
        - type: object
          properties:
            stream:
              type: boolean
              default: false
            generation:
              type: object
              additionalProperties: true
    Evidence:
      type: object
      required: [id, rank, content]
      properties:
        id:
          type: string
        rank:
          type: integer
        score:
          type: number
        content:
          type: string
        citation:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
    ReleaseIdentity:
      type: object
      required: [release_id, release_alias, release_version]
      properties:
        release_id:
          type: string
          format: uuid
        release_alias:
          type: string
        release_version:
          type: integer
    RetrieveResponse:
      type: object
      required: [trace_id, release, evidence]
      properties:
        trace_id:
          type: string
          format: uuid
        release:
          $ref: "#/components/schemas/ReleaseIdentity"
        evidence:
          type: array
          items:
            $ref: "#/components/schemas/Evidence"
        diagnostics:
          type: object
          additionalProperties: true
    AnswerResponse:
      type: object
      required: [trace_id, release, answer, evidence]
      properties:
        trace_id:
          type: string
          format: uuid
        release:
          $ref: "#/components/schemas/ReleaseIdentity"
        answer:
          type: string
        evidence:
          type: array
          items:
            $ref: "#/components/schemas/Evidence"
        usage:
          type: object
          additionalProperties: true
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
        message:
          type: string
        trace_id:
          type: string
          format: uuid
        details:
          type: object
          additionalProperties: true