openapi.yaml

# Generated by Phase 1.5 (TODO-02) | solution-architect + python-backend-engineer + business-analyst-agent + api-testing-engineer + consensus-agent
# Source of truth: docs/phase-1-architecture/hld.md (APPROVED) + PRD.md v2.0 + docs/execution/_common_context.md (ADR-1..ADR-10, AGREED CONTRACTS)
# Do not edit by hand outside the Phase 1.5 pipeline. Idempotent overwrite.
openapi: 3.1.0

info:
  title: RAG Refinement System API
  version: 1.0.0
  summary: TOC-routed retrieval-refinement layer — routing-only enterprise API plus a streaming personal-tool Q&A surface.
  description: |
    # RAG Refinement System API

    A document-structure-aware retrieval layer that selects relevant document
    sections (via a TOC-based Router Agent) **before** vector retrieval. Two
    product surfaces share one contract (HLD §1.1):

    - **Enterprise Refinement API** — `POST /v1/route` is **routing-only**:
      it returns the optimal retrieval scope `{relevant_sections[], page_ranges[],
      confidence[], fallback, ...}` and **never calls the generation LLM**
      (binding AGREED CONTRACT: ai-engineer <-> python-backend-engineer).
      Authenticated with an API key (ADR-7).
    - **Personal Tool** — `POST /v1/answer` streams a generated, cited answer
      token-by-token over Server-Sent Events (SSE), ending with a final event
      carrying `{answer, citations[], routing{}}`. Authenticated with an
      OAuth2 / JWT bearer token (ADR-7).

    `section_id` is the universal join/filter key across the Document -> Section
    -> Chunk hierarchy (HLD §4, §7.5).

    ## Versioning strategy
    The API is versioned in the **URL path** (`/v1/...`). The version increments
    on breaking changes only (per global API standard: version APIs in the URL
    path). Backwards-compatible additions (new optional fields, new endpoints,
    new enum values) ship within the same major version. The `info.version`
    field uses semantic versioning (`MAJOR.MINOR.PATCH`) for the document
    revision; the **path** version (`v1`) is the wire-compatibility contract.

    ## Deprecation policy
    A deprecated operation is marked `deprecated: true` in this spec and returns
    a `Deprecation: true` and `Sunset: <RFC1123 date>` response header for at
    least **180 days** before removal. A successor endpoint is documented in the
    operation description before the old one is sunset. No operation is removed
    without a prior minor release marking it deprecated.

    ## Error model
    All errors use **RFC 7807** `application/problem+json`. The machine-readable
    error code lives in the `code` extension member and is cataloged in
    `error_catalog.json`. See the `Problem` schema.

    ## Compliance annotations (custom extensions)
    - `x-pii: true` marks a field that may carry personal data (DPDP Act 2023 §4 / FR-029).
    - `x-audit-log: true` marks a write operation that emits a CERT-In-format audit record (NFR-007).
    - `x-rate-limit` documents the per-key/per-token rate limit on an operation.
    - `x-fr` lists the PRD FR ids an operation realizes (traceability).
  contact:
    name: RAG Refinement System API Team
    url: https://github.com/techdeveloper-org/rag-refinement-system
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  - url: https://api.rag-refinement.example.com
    description: Production (enterprise + personal tool)
  - url: https://staging.api.rag-refinement.example.com
    description: Staging (DAST target, pre-Phase-G)
  - url: http://localhost:8000
    description: Local development (ChromaDB / Postgres)

tags:
  - name: Routing
    description: Routing-only enterprise endpoints. No generation (HLD §7.2).
  - name: Answers
    description: Streaming cited answers for the personal tool (HLD §7.3).
  - name: Documents
    description: Document ingestion, listing, retrieval, and management.
  - name: Compliance
    description: DPDP Act 2023 erasure and access endpoints (HLD §7.4).
  - name: Operations
    description: Liveness and readiness probes (NFR-009).

paths:

  /v1/route:
    post:
      tags: [Routing]
      operationId: routeQuery
      summary: Route a query to relevant document sections (routing-only, no generation).
      description: |
        Routing-only enterprise endpoint. Returns the sections a downstream RAG
        should retrieve from, with per-section confidence and an interpretable
        rationale. **Performs no generation and never calls the generation LLM**
        (HLD §7.2 invariant; AGREED CONTRACT). If every section confidence falls
        below the threshold, `fallback` is `true` (full-document retrieval is
        recommended to the caller).
      x-fr: [FR-005, FR-009, FR-010, FR-011, FR-012, FR-016]
      x-audit-log: true
      x-rate-limit:
        scope: api-key
        starter: 50000/month
        growth: 250000/month
        burst: 20/second
      security:
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RouteRequest'
      responses:
        '200':
          description: Routing decision produced (scoped or fallback).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/DocumentNotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /v1/answer:
    post:
      tags: [Answers]
      operationId: answerQuery
      summary: Stream a generated, cited answer over Server-Sent Events (personal tool).
      description: |
        Personal-tool endpoint. Routes the query, performs targeted retrieval,
        optionally reranks, then **streams** the generated answer token-by-token
        as Server-Sent Events (`text/event-stream`). The stream emits:

        - repeated `event: token` messages whose `data` is a `TokenEvent`
          (incremental answer text);
        - a terminal `event: final` message whose `data` is an `AnswerFinalEvent`
          carrying `{answer, citations[], routing{}}`;
        - on error, an `event: error` message whose `data` is a `Problem`.

        A non-streaming error (auth, validation, not-found) is returned as a
        normal RFC-7807 response **before** the stream begins. Errors that occur
        mid-stream are delivered as an SSE `error` event.
      x-fr: [FR-007, FR-008, FR-009, FR-011, FR-012, FR-018, FR-016]
      x-audit-log: true
      x-rate-limit:
        scope: jwt-subject
        free: 50/month
        pro: 1000/month
        power: 10000/month
        burst: 5/second
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnswerRequest'
      responses:
        '200':
          description: |
            SSE stream opened. The body is `text/event-stream`. See the schemas
            `TokenEvent`, `AnswerFinalEvent`, and `Problem` for the `data`
            payloads of the `token`, `final`, and `error` events respectively.
          headers:
            Cache-Control:
              schema: { type: string, const: 'no-cache' }
            Connection:
              schema: { type: string, const: 'keep-alive' }
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/SseAnswerStream'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/DocumentNotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

  /v1/documents:
    post:
      tags: [Documents]
      operationId: ingestDocument
      summary: Upload and ingest a PDF (parse -> TOC -> chunk -> embed -> index).
      description: |
        Uploads a PDF and runs the ingestion pipeline (`ingest_document`):
        parse + TOC extraction (Scenario A/B/C, ADR-4), section-aware chunking,
        embedding, and upsert to the vector store + Postgres section rows.
        **Idempotent on content hash** — re-uploading identical content reuses
        the existing `doc_id` and returns `200` instead of `201` (AGREED
        CONTRACT). Set `no_retention=true` to purge raw + chunks + sections
        after processing (FR-027); in that mode the document is not listable.
      x-fr: [FR-001, FR-002, FR-003, FR-004, FR-017, FR-023, FR-027, FR-028]
      x-audit-log: true
      x-rate-limit:
        scope: api-key-or-jwt
        burst: 10/minute
      security:
        - apiKey: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/IngestRequest'
            encoding:
              file:
                contentType: application/pdf
      responses:
        '201':
          description: Document ingested for the first time.
          headers:
            Location:
              description: URI of the created document.
              schema: { type: string, format: uri }
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestResponse'
        '200':
          description: Identical content already ingested; existing doc_id reused (idempotent).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

    get:
      tags: [Documents]
      operationId: listDocuments
      summary: List ingested documents (paginated).
      description: |
        Returns a paginated list of documents owned by the authenticated caller
        (tenant-scoped). Supports page-based pagination. No-retention documents
        are never listed (they do not persist).
      x-fr: [FR-024]
      security:
        - apiKey: []
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
        - name: domain
          in: query
          description: Optional filter on document domain.
          required: false
          schema: { type: string, maxLength: 64 }
      responses:
        '200':
          description: A page of documents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/documents/{id}:
    parameters:
      - $ref: '#/components/parameters/DocumentIdPath'
    get:
      tags: [Documents]
      operationId: getDocument
      summary: Retrieve document metadata.
      description: Returns metadata for a single document the caller owns (tenant-scoped, IDOR-guarded).
      x-fr: [FR-024]
      security:
        - apiKey: []
        - bearerAuth: []
      responses:
        '200':
          description: Document metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/DocumentNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags: [Compliance]
      operationId: deleteDocument
      summary: Erase a document and all derived data (DPDP Act 2023 right to erasure).
      description: |
        Erasure cascade (HLD §7.4, OAQ-2): tombstones the Postgres `documents`
        row, then deletes its sections, chunk vectors (Qdrant), and raw upload
        (object store) via outbox + reconciliation sweep. The document becomes
        **immediately invisible** (subsequent `GET` returns 404). Idempotent: a
        second delete of an already-erased document returns 404.
      x-fr: [FR-025]
      x-audit-log: true
      security:
        - apiKey: []
        - bearerAuth: []
      responses:
        '202':
          description: Erasure accepted; cascade in progress, document already invisible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErasureReceipt'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/DocumentNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/documents/{id}/toc:
    parameters:
      - $ref: '#/components/parameters/DocumentIdPath'
    get:
      tags: [Documents]
      operationId: getDocumentToc
      summary: Retrieve the extracted (or pseudo-generated) table of contents.
      description: |
        Returns the document's TOC (native bookmarks for Scenario A, or the
        LLM pseudo-TOC for Scenarios B/C). `section_id` is the universal key;
        `page_start`/`page_end` are the Postgres page-range authority (OAQ-3).
        For `fallback_only` documents (Scenario C, no usable structure) the
        `toc` array is empty and `fallback_only` is `true`.
      x-fr: [FR-002, FR-003]
      security:
        - apiKey: []
        - bearerAuth: []
      responses:
        '200':
          description: Document TOC.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TocResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/DocumentNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/documents/{id}/data:
    parameters:
      - $ref: '#/components/parameters/DocumentIdPath'
    get:
      tags: [Compliance]
      operationId: exportDocumentData
      summary: Export the personal data held for a document (DPDP Act 2023 right to access).
      description: |
        Returns the personal data the system holds for the document (HLD §7.4,
        FR-026). PII fields are annotated `x-pii: true`. This is the DPDP §8
        data-subject access export.
      x-fr: [FR-026, FR-029]
      x-audit-log: true
      security:
        - apiKey: []
        - bearerAuth: []
      responses:
        '200':
          description: Personal-data export for the document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAccessExport'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/DocumentNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /health:
    get:
      tags: [Operations]
      operationId: getHealth
      summary: Liveness probe.
      description: Returns 200 if the process is alive (NFR-009). No auth.
      security: []
      responses:
        '200':
          description: Service is alive.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
        '500':
          $ref: '#/components/responses/InternalError'

  /ready:
    get:
      tags: [Operations]
      operationId: getReadiness
      summary: Readiness probe.
      description: Returns 200 if all dependencies (Postgres, vector DB, providers) are reachable (NFR-009).
      security: []
      responses:
        '200':
          description: Service is ready to serve traffic.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadinessStatus'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'

components:

  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Enterprise API key (with rotation, ADR-7 / FR-010 / NFR-015).
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth2 / JWT bearer token for the personal tool (ADR-7 / FR-007 / NFR-015).
    oauth2:
      type: oauth2
      description: OAuth2 authorization-code flow backing the personal-tool JWT (ADR-7).
      flows:
        authorizationCode:
          authorizationUrl: https://auth.rag-refinement.example.com/oauth2/authorize
          tokenUrl: https://auth.rag-refinement.example.com/oauth2/token
          refreshUrl: https://auth.rag-refinement.example.com/oauth2/token
          scopes:
            documents:read: Read documents and TOCs.
            documents:write: Upload and delete documents.
            answers:read: Stream answers.

  parameters:
    DocumentIdPath:
      name: id
      in: path
      required: true
      description: Document identifier (doc_id).
      schema:
        $ref: '#/components/schemas/DocumentId'
    PageParam:
      name: page
      in: query
      required: false
      description: 1-based page number for pagination.
      schema: { type: integer, minimum: 1, default: 1 }
    PageSizeParam:
      name: page_size
      in: query
      required: false
      description: Number of items per page.
      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }

  responses:
    BadRequest:
      description: Malformed request.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          example:
            type: https://api.rag-refinement.example.com/problems/bad-request
            title: Bad Request
            status: 400
            code: BAD_REQUEST
            detail: The request body could not be parsed as JSON.
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          example:
            type: https://api.rag-refinement.example.com/problems/unauthorized
            title: Unauthorized
            status: 401
            code: UNAUTHORIZED
            detail: API key or bearer token is missing or invalid.
    Forbidden:
      description: Authenticated but not permitted (e.g. cross-tenant access / IDOR).
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          example:
            type: https://api.rag-refinement.example.com/problems/forbidden
            title: Forbidden
            status: 403
            code: FORBIDDEN
            detail: The caller does not own this document.
    DocumentNotFound:
      description: Document does not exist (or has been erased).
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          example:
            type: https://api.rag-refinement.example.com/problems/document-not-found
            title: Not Found
            status: 404
            code: DOCUMENT_NOT_FOUND
            detail: No document with the given id exists.
    ValidationError:
      description: Request body failed schema validation.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/ValidationProblem' }
          example:
            type: https://api.rag-refinement.example.com/problems/validation-error
            title: Unprocessable Entity
            status: 422
            code: VALIDATION_ERROR
            detail: One or more fields failed validation.
            errors:
              - field: confidence_threshold
                message: must be between 0.0 and 1.0
    PayloadTooLarge:
      description: Uploaded file exceeds the size/page cap.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          example:
            type: https://api.rag-refinement.example.com/problems/payload-too-large
            title: Payload Too Large
            status: 413
            code: PAYLOAD_TOO_LARGE
            detail: The uploaded PDF exceeds the maximum allowed size.
    UnsupportedMediaType:
      description: Uploaded file is not a supported PDF.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          example:
            type: https://api.rag-refinement.example.com/problems/unsupported-media-type
            title: Unsupported Media Type
            status: 415
            code: UNSUPPORTED_MEDIA_TYPE
            detail: Only application/pdf uploads are accepted.
    RateLimited:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds until the caller may retry.
          schema: { type: integer, minimum: 0 }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          example:
            type: https://api.rag-refinement.example.com/problems/rate-limited
            title: Too Many Requests
            status: 429
            code: RATE_LIMITED
            detail: The rate limit for this API key has been exceeded.
    InternalError:
      description: Unexpected server error.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          example:
            type: https://api.rag-refinement.example.com/problems/internal-error
            title: Internal Server Error
            status: 500
            code: INTERNAL_ERROR
            detail: An unexpected error occurred. The incident has been logged.
    ServiceUnavailable:
      description: A required dependency is unavailable; routing may degrade to fallback.
      headers:
        Retry-After:
          schema: { type: integer, minimum: 0 }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          example:
            type: https://api.rag-refinement.example.com/problems/service-unavailable
            title: Service Unavailable
            status: 503
            code: SERVICE_UNAVAILABLE
            detail: A required dependency (vector DB or LLM provider) is unreachable.

  schemas:

    DocumentId:
      type: string
      pattern: '^doc_[A-Za-z0-9]{6,}$'
      examples: [doc_abc123]
      description: Stable document identifier.

    SectionId:
      type: string
      pattern: '^sec_[A-Za-z0-9]{1,}$'
      examples: [sec_warranty]
      description: Universal section identifier — the join/filter key (HLD §7.5).

    QueryId:
      type: string
      pattern: '^qry_[A-Za-z0-9]{1,}$'
      examples: [qry_xyz789]
      description: Correlation id for a routing/answer request (NFR-009 tracing).

    Confidence:
      type: number
      format: float
      minimum: 0.0
      maximum: 1.0
      description: Router confidence that a section is relevant (PRD 8.3).

    PageRange:
      type: array
      description: A [page_start, page_end] inclusive page interval.
      minItems: 2
      maxItems: 2
      items: { type: integer, minimum: 1 }
      examples: [[142, 148]]

    RouteRequest:
      type: object
      additionalProperties: false
      required: [query]
      properties:
        document_id:
          $ref: '#/components/schemas/DocumentId'
        document_ids:
          type: array
          description: Optional multi-document routing (FR-014, OAQ-4). Mutually exclusive with document_id.
          items: { $ref: '#/components/schemas/DocumentId' }
          minItems: 1
          maxItems: 25
        query:
          type: string
          minLength: 1
          maxLength: 4000
          description: The user's natural-language query (untrusted input).
          x-pii: true
        confidence_threshold:
          allOf: [ { $ref: '#/components/schemas/Confidence' } ]
          default: 0.7
          description: Sections scoring below this are excluded (PRD 8.3).
        max_sections:
          type: integer
          minimum: 1
          maximum: 20
          default: 3
          description: Maximum number of sections to return.
        rerank:
          type: boolean
          default: false
          description: Reserved — advisory hint that the caller intends to rerank (FR-016).
      oneOf:
        - required: [document_id]
        - required: [document_ids]

    RelevantSection:
      type: object
      additionalProperties: false
      required: [section_id, title, page_start, page_end, confidence]
      properties:
        section_id: { $ref: '#/components/schemas/SectionId' }
        document_id: { $ref: '#/components/schemas/DocumentId' }
        title:
          type: string
          description: Section title from the TOC.
          x-pii: true
        page_start: { type: integer, minimum: 1 }
        page_end: { type: integer, minimum: 1 }
        confidence: { $ref: '#/components/schemas/Confidence' }

    RouteResponse:
      type: object
      additionalProperties: false
      required: [query_id, relevant_sections, page_ranges, confidence, fallback, routing_time_ms]
      properties:
        query_id: { $ref: '#/components/schemas/QueryId' }
        relevant_sections:
          type: array
          items: { $ref: '#/components/schemas/RelevantSection' }
        page_ranges:
          type: array
          description: Display-only page intervals; Postgres sections are the authority (OAQ-3).
          items: { $ref: '#/components/schemas/PageRange' }
        confidence:
          type: array
          items: { $ref: '#/components/schemas/Confidence' }
        fallback:
          type: boolean
          description: True when all section confidences fell below threshold (FR-009).
        routing_time_ms:
          type: integer
          minimum: 0
          description: Router latency in milliseconds (NFR-001).
        rationale:
          type: string
          description: Interpretable "why did you look here?" explanation (FR-012, NFR-011).
        estimated_token_reduction:
          type: string
          pattern: '^[0-9]{1,3}%$'
          examples: ['87%']
          description: Estimated token saving vs. full-document RAG.

    AnswerRequest:
      type: object
      additionalProperties: false
      required: [document_id, query]
      properties:
        document_id: { $ref: '#/components/schemas/DocumentId' }
        query:
          type: string
          minLength: 1
          maxLength: 4000
          description: The user's natural-language question (untrusted input).
          x-pii: true
        confidence_threshold:
          allOf: [ { $ref: '#/components/schemas/Confidence' } ]
          default: 0.7
        max_sections:
          type: integer
          minimum: 1
          maximum: 20
          default: 3
        rerank:
          type: boolean
          default: false
          description: Apply Cohere Rerank-3 post-route (FR-016, ADR-8).
        no_retention:
          type: boolean
          default: false
          description: Purge any per-request artifacts after the answer (FR-027).

    Citation:
      type: object
      additionalProperties: false
      required: [section_title, page_start, page_end]
      properties:
        section_id: { $ref: '#/components/schemas/SectionId' }
        section_title:
          type: string
          x-pii: true
        page_start: { type: integer, minimum: 1 }
        page_end: { type: integer, minimum: 1 }

    RoutingSummary:
      type: object
      additionalProperties: false
      required: [sections, confidence, fallback]
      properties:
        sections:
          type: array
          items: { $ref: '#/components/schemas/SectionId' }
        confidence:
          type: array
          items: { $ref: '#/components/schemas/Confidence' }
        fallback: { type: boolean }
        rationale:
          type: string
          description: Interpretability rationale (FR-012, NFR-011).

    TokenEvent:
      type: object
      additionalProperties: false
      required: [token]
      description: "SSE `event: token` data payload - an incremental answer fragment."
      properties:
        query_id: { $ref: '#/components/schemas/QueryId' }
        token:
          type: string
          x-pii: true
          description: A fragment of the streamed answer text.

    AnswerFinalEvent:
      type: object
      additionalProperties: false
      required: [answer, citations, routing]
      description: "SSE `event: final` data payload - the completed cited answer."
      properties:
        query_id: { $ref: '#/components/schemas/QueryId' }
        answer:
          type: string
          x-pii: true
          description: The complete generated answer.
        citations:
          type: array
          items: { $ref: '#/components/schemas/Citation' }
        routing:
          $ref: '#/components/schemas/RoutingSummary'

    SseAnswerStream:
      type: object
      description: |
        Documentation-only envelope describing the union of SSE `data` payloads
        on the `/v1/answer` stream. The wire format is `text/event-stream`; each
        message's `data` is one of these JSON objects keyed by its `event` name
        (`token` -> TokenEvent, `final` -> AnswerFinalEvent, `error` -> Problem).
      oneOf:
        - $ref: '#/components/schemas/TokenEvent'
        - $ref: '#/components/schemas/AnswerFinalEvent'
        - $ref: '#/components/schemas/Problem'

    IngestRequest:
      type: object
      additionalProperties: false
      required: [file]
      properties:
        file:
          type: string
          format: binary
          description: The PDF to ingest (application/pdf).
          x-pii: true
        title:
          type: string
          maxLength: 512
          description: Optional human title; defaults to the PDF metadata title.
        domain:
          type: string
          maxLength: 64
          description: Optional domain label (e.g. legal, finance).
        no_retention:
          type: boolean
          default: false
          description: Ephemeral processing — purge raw + chunks + sections after ingest (FR-027).
        residency_region:
          type: string
          enum: [IN, EU, US, GLOBAL]
          default: GLOBAL
          description: Data-residency region for tenant storage (FR-028).
        ocr:
          type: boolean
          default: false
          description: Force OCR fallback (Azure Document Intelligence, Scenario C, FR-017).

    IngestResponse:
      type: object
      additionalProperties: false
      required: [doc_id, toc, ingest_status, deduplicated]
      properties:
        doc_id: { $ref: '#/components/schemas/DocumentId' }
        title: { type: string, x-pii: true }
        total_pages: { type: integer, minimum: 0 }
        toc:
          type: array
          items: { $ref: '#/components/schemas/TocEntry' }
        ingest_status:
          type: string
          enum: [indexed, fallback_only, ephemeral]
          description: indexed (A/B), fallback_only (Scenario C, FR-009), or ephemeral (no_retention, FR-027).
        deduplicated:
          type: boolean
          description: True when identical content already existed and doc_id was reused.

    TocEntry:
      type: object
      additionalProperties: false
      required: [section_id, level, title, page_start, page_end]
      properties:
        section_id: { $ref: '#/components/schemas/SectionId' }
        level:
          type: integer
          minimum: 1
          description: Hierarchy level (1 = L1 chapter, 2 = L2 subsection).
        title:
          type: string
          x-pii: true
        page_start: { type: integer, minimum: 1 }
        page_end: { type: integer, minimum: 1 }
        summary:
          type: string
          x-pii: true
          description: Optional section summary used by the router.

    TocResponse:
      type: object
      additionalProperties: false
      required: [document_id, fallback_only, toc]
      properties:
        document_id: { $ref: '#/components/schemas/DocumentId' }
        fallback_only:
          type: boolean
          description: True for Scenario-C documents with no usable structure (OAQ-6).
        toc:
          type: array
          items: { $ref: '#/components/schemas/TocEntry' }

    Document:
      type: object
      additionalProperties: false
      required: [doc_id, total_pages, residency_region, fallback_only, created_at]
      properties:
        doc_id: { $ref: '#/components/schemas/DocumentId' }
        title:
          type: string
          x-pii: true
        total_pages: { type: integer, minimum: 0 }
        domain: { type: string }
        tenant_id:
          type: string
          description: Owning tenant (server-assigned; not client-settable).
        residency_region:
          type: string
          enum: [IN, EU, US, GLOBAL]
        fallback_only: { type: boolean }
        created_at:
          type: string
          format: date-time

    DocumentListResponse:
      type: object
      additionalProperties: false
      required: [data, pagination]
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Document' }
        pagination:
          $ref: '#/components/schemas/Pagination'

    Pagination:
      type: object
      additionalProperties: false
      required: [page, page_size, total_count, total_pages]
      properties:
        page: { type: integer, minimum: 1 }
        page_size: { type: integer, minimum: 1 }
        total_count: { type: integer, minimum: 0 }
        total_pages: { type: integer, minimum: 0 }

    PiiField:
      type: object
      additionalProperties: false
      required: [field, location]
      description: A PII field located within the document's stored data (DPDP §4).
      properties:
        field:
          type: string
          x-pii: true
          description: Name/path of the PII-bearing field.
        location:
          type: string
          description: Where it occurs (e.g. section_id or page).
        category:
          type: string
          description: PII category (e.g. name, email, identifier).

    DataAccessExport:
      type: object
      additionalProperties: false
      required: [doc_id, generated_at, document, sections, pii_fields]
      description: DPDP §8 access export of personal data held for a document (FR-026).
      properties:
        doc_id: { $ref: '#/components/schemas/DocumentId' }
        generated_at: { type: string, format: date-time }
        document:
          $ref: '#/components/schemas/Document'
        sections:
          type: array
          items: { $ref: '#/components/schemas/TocEntry' }
        pii_fields:
          type: array
          description: Inventory of PII fields held for this document (FR-029).
          items: { $ref: '#/components/schemas/PiiField' }

    ErasureReceipt:
      type: object
      additionalProperties: false
      required: [doc_id, erased, accepted_at]
      properties:
        doc_id: { $ref: '#/components/schemas/DocumentId' }
        erased:
          type: boolean
          description: True once the document is tombstoned and invisible (cascade may still be sweeping).
        accepted_at: { type: string, format: date-time }

    HealthStatus:
      type: object
      additionalProperties: false
      required: [status]
      properties:
        status: { type: string, enum: [ok] }
        version: { type: string }

    ReadinessStatus:
      type: object
      additionalProperties: false
      required: [status, dependencies]
      properties:
        status: { type: string, enum: [ready, degraded] }
        dependencies:
          type: object
          additionalProperties: { type: string, enum: [up, down] }

    Problem:
      type: object
      description: RFC 7807 problem detail (application/problem+json).
      additionalProperties: true
      required: [type, title, status, code]
      properties:
        type:
          type: string
          format: uri
          description: A URI identifying the problem type.
        title:
          type: string
          description: Short, human-readable summary of the problem type.
        status:
          type: integer
          minimum: 100
          maximum: 599
          description: HTTP status code.
        code:
          type: string
          description: Machine-readable error code (see error_catalog.json).
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
        instance:
          type: string
          format: uri
          description: URI reference identifying this occurrence.
        query_id:
          $ref: '#/components/schemas/QueryId'

    ValidationProblem:
      allOf:
        - $ref: '#/components/schemas/Problem'
        - type: object
          properties:
            errors:
              type: array
              items:
                type: object
                additionalProperties: false
                required: [field, message]
                properties:
                  field: { type: string }
                  message: { type: string }

security:
  - apiKey: []
  - bearerAuth: []