openapi: 3.0.3
info:
  title: DatOnym API
  version: 1.0.0
  description: >
    DSGVO-konforme Anonymisierung von KI-/LLM-Prompts. Erkennt personenbezogene
    Daten, ersetzt sie durch Tokens und stellt sie auf Wunsch wieder her.
  contact:
    name: Thomas Lauer
    email: thomas@lauer.io
servers:
  - url: https://datonym.it-s.de/api/v1
security:
  - ApiKeyAuth: []
paths:
  /health:
    get:
      summary: Statusprüfung
      security: []
      responses:
        '200':
          description: Dienst läuft
  /entities:
    get:
      summary: Unterstützte Entitätstypen
      security: []
      responses:
        '200':
          description: Liste der Typen
  /anonymize:
    post:
      summary: Text anonymisieren
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text:
                  type: string
                  maxLength: 100000
      responses:
        '200':
          description: Anonymisierte Fassung mit Mapping
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnonymizeResult'
        '400': { description: Ungültige Anfrage }
        '401': { description: Nicht autorisiert }
        '413': { description: Text zu groß }
        '429': { description: Rate-Limit überschritten }
  /deanonymize:
    post:
      summary: Tokens durch Klartext ersetzen (Personalisieren)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text: { type: string, maxLength: 100000 }
                session_id: { type: string, format: uuid }
                mapping:
                  type: array
                  items:
                    type: object
                    properties:
                      token: { type: string }
                      value: { type: string }
      responses:
        '200':
          description: Personalisierter Text
          content:
            application/json:
              schema:
                type: object
                properties:
                  text: { type: string }
        '400': { description: Ungültige Anfrage }
        '404': { description: Session unbekannt/abgelaufen }
        '413': { description: Text zu groß (max. 100.000 Zeichen) }
  /session/{id}:
    delete:
      summary: Zuordnung löschen
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        '200': { description: Gelöscht }
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    AnonymizeResult:
      type: object
      properties:
        session_id: { type: string, format: uuid }
        anonymized_text: { type: string }
        entities:
          type: array
          items:
            type: object
            properties:
              entity_type: { type: string }
              start: { type: integer }
              end: { type: integer }
              score: { type: number }
              token: { type: string }
              text: { type: string }
        mapping:
          type: array
          items:
            type: object
            properties:
              token: { type: string }
              entity_type: { type: string }
              value: { type: string }
        stats:
          type: object
          properties:
            entityCount: { type: integer }
            uniqueTokens: { type: integer }
            anonymizationRate: { type: integer }
            dataLoss: { type: integer }