Datenmaske
API DOCUMENTATION

Datenmaske REST API

Programmatic access to PDF redaction. Upload documents, detect PII, apply redactions, and export — all via a REST API.

Base URL: https://datenmaske.de/api/v1

Machine-readable specification (OpenAPI 3.0.3): openapi.json

Authentication

All API requests require an API key via the Authorization header: 

Authorization: Bearer dm_live_ihr_api_schluessel_hier

API keys can be created in Settings. Max. 5 active keys per account. Available from the Solo plan (€29/month).

Rate Limiting

Plan Requests/Min Documents/Month Max. Pages
Starter No API access — —
Solo 15 150 Unlimited
Professional 30 150 Unlimited
Business 120 Unlimited Unlimited

On exceedance: HTTP 429 with the Retry-After header. All responses include X-RateLimit-* headers.

Error responses

Status Meaning
400 Validation error — invalid input
401 Unauthorized — API key missing or invalid
403 Forbidden — plan does not support this feature
404 Resource not found
429 Rate limit exceeded or monthly quota exhausted
500 Server error 
{
  "error": "Description of the error",
  "details": ["Field error 1", "Field error 2"]  // optional on 400
}

Endpoints

POST /api/v1/documents

Upload and process a PDF. The document is analyzed, PII is detected, and redaction suggestions are generated.

Auth: API Key (Bearer Token)

Parameter

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

Response 

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

Counts against the monthly document quota. Processing time: ~2-10 seconds depending on document size.

GET /api/v1/documents

List all of the user's documents.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
page integer Nein Page number (default: 1)
limit integer Nein Results per page (default: 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}

Retrieve the status and summary of a document, including the number of redaction suggestions.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
id string Ja Document 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

Retrieve all detected PII suggestions for a document.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
id string Ja Document ID (path)
status string Nein Filter by status: suggested, accepted, rejected
page integer Nein Page number (default: 1)
limit integer Nein Results per page (default: 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 values: name, address, phone, email, birth_date, iban, customer_number, insurance_number, ssn, credit_card, other. Source: "regex", "ner", or "custom".

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

Accept or reject a redaction suggestion.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
id string Ja Document ID
suggestionId string Ja Suggestion ID

Request Body 

{
  "status": "accepted"
}

Response 

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

Status: "accepted" or "rejected". Only suggestions with status "suggested" can be changed.

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

Apply redaction and export the redacted PDF. Only accepted suggestions are redacted.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
id string Ja Document ID

Request Body 

{
  "autoAcceptAll": false
}

If autoAcceptAll: true, all open suggestions are automatically accepted before redaction. The response is a PDF file (binary), not JSON.

Success response: Content-Type: application/pdf with headers X-Redaction-Count, X-Verification-Passed

DELETE /api/v1/documents/{id}

Delete a document and all associated data.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
id string Ja Document ID

Response 

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

Accept or reject multiple redaction suggestions at once.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
id string Ja Document ID

Request Body 

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

Response 

{
  "updated": 2
}

Send a JSON array with suggestion ID and desired status.

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

Retrieve a JSON redaction report for a document with summary and type breakdown.

Auth: API Key (Bearer Token)

Parameter

Name Typ Pflicht Beschreibung
id string Ja Document 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
}

Includes the SHA-256 checksum of the original document and the verification status.

GET /api/v1/account

Retrieve account information, current plan, and monthly usage.

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 of -1 means unlimited (Business plan).

GET /api/v1/audit

Retrieve audit logs for all API actions. Only available on the Business plan.

Auth: API Key (Bearer Token — Business plan required)

Parameter

Name Typ Pflicht Beschreibung
limit integer Nein Number of entries (default: 20, max: 100)
documentId string Nein Filter by document 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"
    }
  ]
}

Returns 403 for Professional and Starter plans.

GET /api/v1

Retrieve API status and available endpoints.

Auth: API Key (Bearer Token)

Response 

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

Example workflow

# 1. Upload PDF
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. Show detected PII
curl https://datenmaske.de/api/v1/documents/doc_abc123/suggestions \
  -H "Authorization: Bearer dm_live_ihr_schluessel"

# 3. Accept/reject suggestions
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. Apply redaction and export PDF
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. Delete document
curl -X DELETE https://datenmaske.de/api/v1/documents/doc_abc123 \
  -H "Authorization: Bearer dm_live_ihr_schluessel"

Start using the API

Create an API key in Settings and start with programmatic PDF redaction. From €29/month.

Create API key Compare plans