API-Dokumentation

Alle Endpunkte (außer /health) erfordern einen gültigen JWT-Bearer-Token aus Keycloak. Token-Lebensdauer: 5 Minuten.

# Token abrufen (Keycloak)
TOKEN=$(curl -s -X POST \
  https://auth.privago.de/realms/privago/protocol/openid-connect/token \
  -d "grant_type=password" \
  -d "client_id=privago-api" \
  -d "username=DEINE_EMAIL" \
  -d "password=DEIN_PASSWORT" \
  | jq -r '.access_token')

echo $TOKEN

Den Token bei jedem Request als Authorization: Bearer $TOKEN Header mitsenden.

POST /api/v1/documents — Multipart-Form mit file Feld. Max. 100 MB. Unterstützte Formate: PDF, JPG, PNG, HEIC.

curl -s -X POST https://app.privago.de/api/v1/documents \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@vertrag.pdf" \
  | jq .

# Antwort:
# {
#   "data": {
#     "document_id": "550e8400-e29b-41d4-a716-446655440000",
#     "filename": "vertrag.pdf",
#     "status": "uploaded"
#   }
# }

DOC_ID="550e8400-e29b-41d4-a716-446655440000"

GET /api/v1/documents/{id} — Poll alle 2 Sekunden bis status == "ready_for_review".

# Einmalig prüfen
curl -s -H "Authorization: Bearer $TOKEN" \
  https://app.privago.de/api/v1/documents/$DOC_ID \
  | jq '.data.status'

# Poll-Loop (bash)
while true; do
  STATUS=$(curl -s -H "Authorization: Bearer $TOKEN" \
    https://app.privago.de/api/v1/documents/$DOC_ID | jq -r '.data.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "ready_for_review" ] && break
  [ "$STATUS" = "failed" ] && echo "Fehler!" && exit 1
  sleep 2
done

GET /api/v1/documents/{id}/entities — gibt alle erkannten PII-Entitäten zurück. Unterstützt Pagination (page, page_size) und Filter (category, min_confidence).

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://app.privago.de/api/v1/documents/$DOC_ID/entities?page_size=50" \
  | jq '.data[] | {id, category, text, confidence, status}'

# Nur Personennamen mit Konfidenz > 80%:
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://app.privago.de/api/v1/documents/$DOC_ID/entities?category=person_name&min_confidence=0.8" \
  | jq .

PATCH /api/v1/documents/{id}/entities/{entity_id} — Status setzen auf accepted oder rejected.

ENTITY_ID="abc123..."

# Entität akzeptieren (wird im Export geschwärzt)
curl -s -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "accepted"}' \
  https://app.privago.de/api/v1/documents/$DOC_ID/entities/$ENTITY_ID \
  | jq '.data.status'

# Alle Entitäten auf einmal akzeptieren (Loop)
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://app.privago.de/api/v1/documents/$DOC_ID/entities?page_size=200" \
  | jq -r '.data[].id' \
  | while read id; do
      curl -s -X PATCH \
        -H "Authorization: Bearer $TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"status": "accepted"}' \
        https://app.privago.de/api/v1/documents/$DOC_ID/entities/$id > /dev/null
    done

POST /api/v1/documents/{id}/export — Startet den asynchronen Export-Task. Danach poll auf GET /export/{export_id} bisstatus == "ready".

# Export starten
EXPORT_ID=$(curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  https://app.privago.de/api/v1/documents/$DOC_ID/export \
  | jq -r '.data.export_id')

# Status pollen
while true; do
  RESULT=$(curl -s -H "Authorization: Bearer $TOKEN" \
    https://app.privago.de/api/v1/documents/$DOC_ID/export/$EXPORT_ID)
  STATUS=$(echo $RESULT | jq -r '.data.status')
  echo "Export-Status: $STATUS"
  if [ "$STATUS" = "ready" ]; then
    DOWNLOAD_URL=$(echo $RESULT | jq -r '.data.download_url')
    break
  fi
  [ "$STATUS" = "failed" ] && echo "Export fehlgeschlagen!" && exit 1
  sleep 2
done

# Geschwärztes PDF herunterladen
curl -L -o geschwärzt.pdf "$DOWNLOAD_URL"
echo "✅ Gespeichert als geschwärzt.pdf"

Alles zusammen: Upload → warten → alle akzeptieren → exportieren → herunterladen.

#!/usr/bin/env bash
set -euo pipefail

API="https://app.privago.de/api/v1"
FILE="${1:-dokument.pdf}"

# 1. Token
TOKEN=$(curl -s -X POST \
  https://auth.privago.de/realms/privago/protocol/openid-connect/token \
  -d "grant_type=password&client_id=privago-api" \
  -d "username=$PRIVAGO_EMAIL&password=$PRIVAGO_PASSWORD" \
  | jq -r '.access_token')

# 2. Upload
DOC_ID=$(curl -s -X POST "$API/documents" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@$FILE" | jq -r '.data.document_id')
echo "Hochgeladen: $DOC_ID"

# 3. Warten bis ready
until [ "$(curl -s -H "Authorization: Bearer $TOKEN" \
  "$API/documents/$DOC_ID" | jq -r '.data.status')" = "ready_for_review" ]; do
  sleep 2
done
echo "Analyse abgeschlossen"

# 4. Alle Entitäten akzeptieren
curl -s -H "Authorization: Bearer $TOKEN" \
  "$API/documents/$DOC_ID/entities?page_size=200" \
  | jq -r '.data[].id' \
  | xargs -I{} curl -s -X PATCH -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" -d '{"status":"accepted"}' \
    "$API/documents/$DOC_ID/entities/{}" > /dev/null
echo "Entitäten akzeptiert"

# 5. Export
EID=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  "$API/documents/$DOC_ID/export" | jq -r '.data.export_id')

until [ "$(curl -s -H "Authorization: Bearer $TOKEN" \
  "$API/documents/$DOC_ID/export/$EID" | jq -r '.data.status')" = "ready" ]; do
  sleep 2
done

URL=$(curl -s -H "Authorization: Bearer $TOKEN" \
  "$API/documents/$DOC_ID/export/$EID" | jq -r '.data.download_url')

curl -L -o "geschwärzt_$(basename $FILE)" "$URL"
echo "✅ Export fertig: geschwärzt_$(basename $FILE)"

• • 100 Requests/Minute pro authentifiziertem Nutzer
• • 5 gleichzeitige Uploads pro Account
• • Bei Überschreitung: HTTP 429 mit Retry-After Header