Datenmaske
API DOKUMENTATION

Datenmaske REST API

Programmatischer Zugriff auf die PDF-Schwärzung. Dokumente hochladen, PII erkennen, Schwärzung anwenden und exportieren — alles über eine REST API.

Basis-URL: https://datenmaske.de/api/v1

Maschinenlesbare Spezifikation (OpenAPI 3.0.3): openapi.json

Authentifizierung

Alle API-Anfragen erfordern einen API-Schlüssel über den Authorization Header: 

Authorization: Bearer dm_live_ihr_api_schluessel_hier

API-Schlüssel können in den Einstellungen erstellt werden. Max. 5 aktive Schlüssel pro Konto. Verfügbare ab dem Solo-Tarif (29€/Monat).

Rate Limiting

Tarif Anfragen/Min Dokumente/Monat Max. Seiten
Starter Kein API-Zugang — —
Solo 15 150 Unbegrenzt
Professional 30 150 Unbegrenzt
Business 120 Unbegrenzt Unbegrenzt

Bei Überschreitung: HTTP 429 mit Retry-After Header. Alle Antworten enthalten X-RateLimit-* Header.

Fehlerantworten

Status Bedeutung
400 Validierungsfehler — ungültige Eingabe
401 Nicht autorisiert — API-Schlüssel fehlt oder ungültig
403 Verboten — Tarif unterstützt diese Funktion nicht
404 Ressource nicht gefunden
429 Rate-Limit überschritten oder Monatskontingent erschöpft
500 Serverfehler 
{
  "error": "Beschreibung des Fehlers",
  "details": ["Feldfehler 1", "Feldfehler 2"]  // optional bei 400
}

Endpunkte

POST /api/v1/documents

PDF hochladen und verarbeiten. Das Dokument wird analysiert, PII erkannt und Schwärzungsvorschläge erstellt.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
file file (multipart/form-data) Ja PDF-Datei (max. 50 MB)

Response 

{
  "id": "doc_abc123",
  "filename": "vertrag.pdf",
  "pageCount": 5,
  "suggestionsCount": 12,
  "status": "review"
}

Zählt gegen das monatliche Dokumentkontingent. Verarbeitungszeit: ~2-10 Sekunden je nach Dokumentgröße.

GET /api/v1/documents

Alle Dokumente des Benutzers auflisten.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
page integer Nein Seitennummer (Standard: 1)
limit integer Nein Ergebnisse pro Seite (Standard: 20, max: 100)

Response 

{
  "documents": [
    {
      "id": "doc_abc123",
      "originalName": "vertrag.pdf",
      "pageCount": 5,
      "status": "review",
      "createdAt": "2026-05-13T18:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}
GET /api/v1/documents/{id}

Status und Zusammenfassung eines Dokuments abrufen, inklusive Anzahl der Schwärzungsvorschläge.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
id string Ja Dokument-ID

Response 

{
  "id": "doc_abc123",
  "originalName": "vertrag.pdf",
  "pageCount": 5,
  "status": "review",
  "createdAt": "2026-05-13T18:30:00Z",
  "suggestions": {
    "total": 12,
    "accepted": 8,
    "rejected": 2,
    "pending": 2
  }
}
GET /api/v1/documents/{id}/suggestions

Alle erkannten PII-Vorschläge eines Dokuments abrufen.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
id string Ja Dokument-ID (Pfad)
status string Nein Filter nach Status: suggested, accepted, rejected
page integer Nein Seitennummer (Standard: 1)
limit integer Nein Ergebnisse pro Seite (Standard: 50, max: 200)

Response 

{
  "suggestions": [
    {
      "id": "sug_xyz789",
      "documentId": "doc_abc123",
      "sensitivityType": "name",
      "detectedText": "Max Mustermann",
      "confidence": 95,
      "pageNumber": 1,
      "bboxX": 72,
      "bboxY": 120,
      "bboxWidth": 98,
      "bboxHeight": 12,
      "status": "suggested",
      "source": "regex"
    }
  ],
  "total": 12,
  "page": 1,
  "limit": 50
}

sensitivityType-Werte: name, address, phone, email, birth_date, iban, customer_number, insurance_number, ssn, credit_card, other. Quelle: "regex", "ner" oder "custom".

PATCH /api/v1/documents/{id}/suggestions/{suggestionId}

Einen Schwärzungsvorschlag akzeptieren oder ablehnen.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
id string Ja Dokument-ID
suggestionId string Ja Vorschlags-ID

Request Body 

{
  "status": "accepted"
}

Response 

{
  "id": "sug_xyz789",
  "status": "accepted"
}

Status: "accepted" oder "rejected". Nur Vorschläge mit Status "suggested" können geändert werden.

POST /api/v1/documents/{id}/redact

Schwärzung anwenden und das redaktierte PDF exportieren. Nur akzeptierte Vorschläge werden geschwärzt.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
id string Ja Dokument-ID

Request Body 

{
  "autoAcceptAll": false
}

Wenn autoAcceptAll: true, werden alle offenen Vorschläge automatisch akzeptiert bevor geschwärzt wird. Antwort ist eine PDF-Datei (binary), nicht JSON.

Erfolgs-Response: Content-Type: application/pdf mit Headern X-Redaction-Count, X-Verification-Passed

DELETE /api/v1/documents/{id}

Dokument und alle zugehörigen Daten löschen.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
id string Ja Dokument-ID

Response 

{
  "success": true
}
PATCH /api/v1/documents/{id}/suggestions

Mehrere Schwärzungsvorschläge gleichzeitig akzeptieren oder ablehnen.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
id string Ja Dokument-ID

Request Body 

[
  { "id": "sug_xyz789", "status": "accepted" },
  { "id": "sug_abc456", "status": "rejected" }
]

Response 

{
  "updated": 2
}

Senden Sie ein JSON-Array mit Vorschlags-ID und gewünschtem Status.

POST /api/v1/documents/{id}/report

JSON-Schwärzungsbericht eines Dokuments abrufen mit Zusammenfassung und Typ-Aufschlüsselung.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
id string Ja Dokument-ID

Response 

{
  "document": {
    "id": "doc_abc123",
    "originalName": "vertrag.pdf",
    "pageCount": 5,
    "status": "review",
    "fileSize": 245000,
    "checksumSha256": "abc123...",
    "createdAt": "2026-05-13T18:30:00Z"
  },
  "redactionSummary": {
    "total": 12,
    "accepted": 8,
    "rejected": 2,
    "pending": 2,
    "manual": 0
  },
  "typeBreakdown": {
    "name": 4,
    "email": 3,
    "iban": 2,
    "address": 3
  },
  "verificationPassed": true
}

Enthält SHA-256 Prüfsumme des Originaldokuments und Verifizierungsstatus.

GET /api/v1/account

Kontoinformationen, aktuellen Tarif und monatliche Nutzung abrufen.

Auth: API Key (Bearer Token)

Response 

{
  "plan": {
    "name": "Professional",
    "key": "professional",
    "features": {
      "enableOcr": true,
      "enableCustomPatterns": true,
      "maxPages": "unlimited",
      "docsPerMonth": 150,
      "enableApiAccess": true,
      "apiRateLimit": 30
    }
  },
  "usage": {
    "monthlyUsed": 23,
    "monthlyLimit": 150,
    "periodStart": "2026-05-01T00:00:00Z",
    "periodEnd": "2026-06-01T00:00:00Z"
  }
}

monthlyLimit von -1 bedeutet unbegrenzt (Business-Tarif).

GET /api/v1/audit

Audit-Protokolle für alle API-Aktionen abrufen. Nur im Business-Tarif verfügbar.

Auth: API Key (Bearer Token — Business-Tarif erforderlich)

Parameter

Name Typ Pflicht Beschreibung
limit integer Nein Anzahl der Einträge (Standard: 20, max: 100)
documentId string Nein Filter nach Dokument-ID

Response 

{
  "logs": [
    {
      "id": "log_abc123",
      "documentId": "doc_xyz",
      "action": "api.document.upload",
      "details": { "filename": "vertrag.pdf", "pageCount": 5 },
      "ipAddress": "192.168.1.1",
      "createdAt": "2026-05-13T18:30:00Z"
    }
  ]
}

Gibt 403 zurück für Professional- und Starter-Tarife.

GET /api/v1

API-Status und verfügbare Endpunkte abrufen.

Auth: API Key (Bearer Token)

Response 

{
  "status": "ok",
  "service": "datenmaske-api",
  "version": "v1",
  "endpoints": { ... }
}

Beispiel-Workflow

# 1. PDF hochladen
curl -X POST https://datenmaske.de/api/v1/documents \
  -H "Authorization: Bearer dm_live_ihr_schluessel" \
  -F "file=@vertrag.pdf"

# Response: { "id": "doc_abc123", "pageCount": 5, "suggestionsCount": 12, "status": "review" }

# 2. Erkannte PII anzeigen
curl https://datenmaske.de/api/v1/documents/doc_abc123/suggestions \
  -H "Authorization: Bearer dm_live_ihr_schluessel"

# 3. Vorschläge akzeptieren/ablehnen
curl -X PATCH https://datenmaske.de/api/v1/documents/doc_abc123/suggestions/sug_xyz \
  -H "Authorization: Bearer dm_live_ihr_schluessel" \
  -H "Content-Type: application/json" \
  -d '{"status": "accepted"}'

# 4. Schwärzung anwenden und PDF exportieren
curl -X POST https://datenmaske.de/api/v1/documents/doc_abc123/redact \
  -H "Authorization: Bearer dm_live_ihr_schluessel" \
  -H "Content-Type: application/json" \
  -d '{"autoAcceptAll": true}' \
  -o redacted_vertrag.pdf

# 5. Dokument löschen
curl -X DELETE https://datenmaske.de/api/v1/documents/doc_abc123 \
  -H "Authorization: Bearer dm_live_ihr_schluessel"

API-Zugang starten

Erstelle einen API-Schlüssel in den Einstellungen und starte mit der programmatischen PDF-Schwärzung. Ab 29€/Monat.

API-Schlüssel erstellen Tarife vergleichen