openapi: 3.1.0
info:
  title: Compliance Intelligence Hub API
  version: 1.0.0
  description: >
    Agent-ready regulatory intelligence for Medicare / PBM / healthcare compliance.
    Monitors CMS, HHS, Federal Register, eCFR and related sources; detects and
    versions changes; classifies operational impact; extracts obligations and
    deadlines; and preserves an exact source citation ledger. Built for humans
    (dashboards/briefings) and agents (callable API + MCP).
  license:
    name: Proprietary — grAIce Tech
servers:
  - url: https://cih-psi.vercel.app/api/v1
security:
  - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API key
  schemas:
    RegulatoryUpdate:
      $ref: /regulatory_update.schema.json
paths:
  /sources:
    get:
      summary: List monitored regulatory sources
      responses: { "200": { description: OK } }
    post:
      summary: Register a new source (admin)
      responses: { "201": { description: Created } }
  /updates:
    get:
      summary: List detected regulatory updates
      parameters:
        - { name: program_area, in: query, schema: { type: string }, description: "e.g. 'Medicare Part D'" }
        - { name: impact_level, in: query, schema: { type: string, enum: [low, medium, high, critical] } }
        - { name: source, in: query, schema: { type: string } }
        - { name: since, in: query, schema: { type: string, format: date-time } }
        - { name: limit, in: query, schema: { type: integer, default: 50, maximum: 200 } }
      responses:
        "200":
          description: A page of updates
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: "#/components/schemas/RegulatoryUpdate" } }
                  next_cursor: { type: string, nullable: true }
  /updates/{id}:
    get:
      summary: Get one update (with full citation ledger + diff)
      parameters: [ { name: id, in: path, required: true, schema: { type: string } } ]
      responses: { "200": { description: OK }, "404": { description: Not found } }
  /search:
    get:
      summary: Full-text + structured search across updates
      parameters:
        - { name: q, in: query, required: true, schema: { type: string } }
        - { name: program_area, in: query, schema: { type: string } }
      responses: { "200": { description: OK } }
  /briefings/daily:
    get:
      summary: Generated daily briefing (exec / compliance-team / operational / client-ready)
      parameters:
        - { name: audience, in: query, schema: { type: string, enum: [exec, compliance, operational, client], default: compliance } }
        - { name: date, in: query, schema: { type: string, format: date } }
      responses: { "200": { description: OK } }
  /impact/classify:
    post:
      summary: Classify an arbitrary document/text for compliance impact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text: { type: string }
                url: { type: string }
      responses:
        "200":
          description: A RegulatoryUpdate-shaped classification (not persisted)
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RegulatoryUpdate" }
  /agent/query:
    post:
      summary: Agent Tool API — natural-language query over the intelligence base
      description: "e.g. 'What changed this week for Part D compliance?' Returns structured updates + a synthesized answer with citations. Mirrors the MCP tool of the same name."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [question]
              properties:
                question: { type: string }
                window: { type: string, enum: [today, week, month], default: week }
      responses: { "200": { description: OK } }