openapi: 3.0.3
info:
  title: N28s Generation API
  version: "0.1.0"
  description: >
    Minimal spec for /healthz and /generate. Responses include a structured `why`
    object with validator outcomes and timing. No secrets included here.
servers:
  - url: https://api.n28s.com
paths:
  /healthz:
    get:
      summary: Health check
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  mode: { type: string }
  /generate:
    post:
      summary: Generate two bullets (policy-enforced)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt: { type: string }
                strict: { type: boolean, default: false }
                context: { type: string }
                stream: { type: boolean, default: false }
      responses:
        "200":
          description: Result
          content:
            application/json:
              schema:
                type: object
                properties:
                  answer: { type: string }
                  refused: { type: boolean }
                  why:
                    type: object
                    properties:
                      scores:
                        type: object
                        properties:
                          latency_ms: { type: number }
                      config:
                        type: object
                        properties:
                          strict: { type: boolean }
                          temperature: { type: number }
                          top_p: { type: number }
                          seed: { type: number }
                          model: { type: string }
                      support:
                        type: object
                        properties:
                          validators:
                            type: array
                            items:
                              type: object
                              properties:
                                validator: { type: string }
                                ok: { type: boolean }
                                note: { type: string }
                                meta: { type: object }
