openapi: 3.0.3
info:
  title: Drug Interaction API
  version: "1.0.0"
  description: >
    Educational drug-drug interaction lookup and a drop-in replacement for the
    discontinued NLM RxNav interaction API. Submit a list of drug names; get back
    pairwise interactions in the NLM-mirrored response shape, each with severity,
    description, source, and an always-present educational disclaimer. Informational
    only — not clinical decision support. Distributed via RapidAPI.
servers:
  - url: https://mortar.rgtz.dev
    description: Production base URL (use as the RapidAPI Base URL)
security:
  - rapidApiKey: []
paths:
  /interactions:
    post:
      operationId: checkInteractions
      summary: Pairwise interactions for a list of drugs
      description: >
        Provide 2-50 drug names (generic or brand). Names are normalized to RxNorm
        RxCUIs (typos and brands handled) and matched at the ingredient level.
        Set explain:true to attach a 1-2 sentence plain-language explanation per
        interaction (cached server-side).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InteractionRequest'
            examples:
              basic:
                value:
                  drugs: ["warfarin", "aspirin", "simvastatin"]
              withExplanation:
                value:
                  drugs: ["simvastatin", "clarithromycin"]
                  explain: true
      responses:
        "200":
          description: NLM-mirrored interaction report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionResponse'
        "400": { $ref: '#/components/responses/Error' }
        "403": { $ref: '#/components/responses/Error' }
        "500": { $ref: '#/components/responses/Error' }
        "502": { $ref: '#/components/responses/Error' }
  /v1/manifest:
    get:
      operationId: getManifest
      summary: Machine-readable capabilities (no auth)
      responses:
        "200": { description: Manifest. }
  /health:
    get:
      operationId: getHealth
      summary: Liveness + dataset readiness
      responses:
        "200": { description: OK. }
components:
  securitySchemes:
    rapidApiKey:
      type: apiKey
      in: header
      name: X-RapidAPI-Key
  parameters: {}
  schemas:
    InteractionRequest:
      type: object
      required: [drugs]
      properties:
        drugs:
          type: array
          minItems: 2
          maxItems: 50
          items: { type: string }
          description: Drug names (generic or brand).
        explain:
          type: boolean
          default: false
          description: Attach a plain-language explanation to each interaction.
    InteractionResponse:
      type: object
      properties:
        disclaimer:
          type: string
          description: Educational-use disclaimer (always present).
        resolved:
          type: array
          items:
            type: object
            properties:
              input: { type: string }
              found: { type: boolean }
              rxcui: { type: string, nullable: true }
              name: { type: string, nullable: true }
              tty: { type: string, nullable: true }
              match: { type: string, enum: [exact, approximate, none] }
        unresolved:
          type: array
          items: { type: string }
        fullInteractionTypeGroup:
          type: array
          description: Interaction groups, one per source (NLM-mirrored).
          items:
            type: object
            properties:
              sourceName: { type: string, description: "ONCHigh | openFDA" }
              sourceDisclaimer: { type: string }
              fullInteractionType:
                type: array
                items:
                  type: object
                  properties:
                    comment: { type: string }
                    minConcept:
                      type: array
                      items: { $ref: '#/components/schemas/Concept' }
                    interactionPair:
                      type: array
                      items: { $ref: '#/components/schemas/InteractionPair' }
    Concept:
      type: object
      properties:
        rxcui: { type: string }
        name: { type: string }
        tty: { type: string }
    InteractionPair:
      type: object
      properties:
        severity: { type: string, description: "high (ONCHigh) | N/A (openFDA)" }
        description: { type: string }
        explanation: { type: string, description: "Only present when explain:true." }
        interactionConcept:
          type: array
          items:
            type: object
            properties:
              minConceptItem: { $ref: '#/components/schemas/Concept' }
              sourceConceptItem:
                type: object
                properties:
                  id: { type: string }
                  name: { type: string }
                  url: { type: string }
  responses:
    Error:
      description: Structured error envelope.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code: { type: string }
                  message: { type: string }
                  hint: { type: string, nullable: true }
                  request_id: { type: string }
