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

Diese Seite beschreibt die Web-API (Cloud). Für die lokale Desktop-API (127.0.0.1, Hotfolder, GPO) siehe Automatisierung & Integration.

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 or team role insufficient
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)

Parameters

Name Type Required Description
file file (multipart/form-data) Yes 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)

Parameters

Name Type Required Description
page integer No Page number (default: 1)
limit integer No 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)

Parameters

Name Type Required Description
id string Yes 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)

Parameters

Name Type Required Description
id string Yes Document ID (path)
status string No Filter by status: suggested, accepted, rejected
page integer No Page number (default: 1)
limit integer No 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)

Parameters

Name Type Required Description
id string Yes Document ID
suggestionId string Yes 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)

Parameters

Name Type Required Description
id string Yes 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)

Parameters

Name Type Required Description
id string Yes Document ID

Response

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

Accept or reject multiple redaction suggestions at once.

Auth: API Key (Bearer Token)

Parameters

Name Type Required Description
id string Yes 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)

Parameters

Name Type Required Description
id string Yes 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)

Parameters

Name Type Required Description
limit integer No Number of entries (default: 20, max: 100)
documentId string No 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.