openapi: 3.1.0
info:
  title: NextSchaden Public Market & Action API
  version: "1.0.0"
  description: |
    Öffentliche, agent-freundliche Schnittstelle von NextSchaden.
    Read-Endpoints liefern aggregierte, anonymisierte Marktdaten ohne Auth.
    Action-Endpoints leiten den Nutzer per Deep-Link in den passenden Flow
    (z. B. Reparatur-Auktion, Pannenhilfe, Online-Zulassung).
  contact:
    name: NextSchaden Engineering
    email: kontakt@nextschaden.de
  license:
    name: Proprietary
servers:
  - url: https://www.nextschaden.de
    description: Production
tags:
  - name: Market
    description: Öffentliche, aggregierte Marktdaten (read-only)
  - name: Actions
    description: Agent-fähige Deep-Link-Endpunkte für Nutzer-Intents
paths:
  /api/public/market/auktionen-live:
    get:
      tags: [Market]
      summary: Aktuell live laufende Reparatur-Auktionen (aggregiert, anonymisiert)
      operationId: getLiveAuctions
      responses:
        '200':
          description: Aggregierte Stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  open_count: { type: integer }
                  median_savings_pct: { type: number }
                  active_workshops: { type: integer }
                  refreshed_at: { type: string, format: date-time }
  /api/public/market/preise:
    get:
      tags: [Market]
      summary: Aggregierte Reparatur-Preisindex pro Schadenklasse (DE-weit, anonymisiert)
      operationId: getPriceIndex
      responses:
        '200':
          description: Preis-Statistiken
  /api/public/market/werkstaetten:
    get:
      tags: [Market]
      summary: Anzahl geprüfter Werkstätten pro PLZ-Bereich (anonymisiert)
      operationId: getWorkshopCoverage
      parameters:
        - in: query
          name: plz
          schema: { type: string, pattern: '^[0-9]{2,5}$' }
          description: Deutsche PLZ (2–5 Stellen)
      responses:
        '200':
          description: Coverage-Information
  /reparatur-auktion:
    get:
      tags: [Actions]
      summary: Startseite Reparatur-Auktion (Deep-Link für Nutzer)
      operationId: openRepairAuction
      x-openai-isConsequential: false
      responses:
        '200': { description: HTML-Landingpage mit JSON-LD Action }
  /werkstatt-finden:
    get:
      tags: [Actions]
      summary: Werkstatt-Finder (Deep-Link für Nutzer)
      operationId: openWorkshopFinder
      x-openai-isConsequential: false
      responses:
        '200': { description: HTML-Landingpage }
  /kfz-zulassung:
    get:
      tags: [Actions]
      summary: Online-Kfz-Zulassung starten (Deep-Link)
      operationId: openVehicleRegistration
      x-openai-isConsequential: false
      responses:
        '200': { description: HTML-Landingpage mit JSON-LD Action }
  /melden:
    get:
      tags: [Actions]
      summary: Schaden melden (Deep-Link in den Erstmelder-Wizard)
      operationId: openDamageReport
      x-openai-isConsequential: false
      responses:
        '200': { description: HTML-Wizard }
