# Paperless-ngx API Dokumentation (Context7)

**Quelle:** Context7 MCP Server  
**Abrufdatum:** 2026-04-20  
**Library ID:** `/paperless-ngx/paperless-ngx`

---

## 🆓 Neue Features & Endpunkte

### 1. Workflows API (NEU!)
Automatisierte Workflows mit Triggern und Actions:

```bash
# Workflows auflisten
GET /api/workflows/

# Workflow erstellen
POST /api/workflows/
Content-Type: application/json

{
  "name": "Auto-tag Invoices",
  "enabled": true,
  "triggers": [{
    "type": 2,
    "filter_filename": "*.pdf",
    "matching_algorithm": 3,
    "match": "invoice"
  }],
  "actions": [{
    "type": 1,
    "assign_tags": [5],
    "assign_document_type": 2
  }]
}
```

**Trigger-Typen:**
- Dokument-Upload
- Filename-Matching
- Content-Matching

**Action-Typen:**
- Tags zuweisen
- Dokumententyp zuweisen
- Korrespondent zuweisen
- Benachrichtigungen senden

---

### 2. Tasks API (NEU!)
Verfolgung von asynchronen Aufgaben:

```bash
# Task-Status prüfen
GET /api/tasks/?task_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Response:
{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "SUCCESS",  // PENDING, SUCCESS, FAILED
  "related_document": 456
}
```

---

### 3. Dokument-Upload mit Metadaten

```bash
# Basis-Upload
POST /api/documents/post_document/
-F "document=@/path/to/invoice.pdf"

# Upload mit vollständigen Metadaten
POST /api/documents/post_document/
-F "document=@/path/to/invoice.pdf"
-F "title=Company Invoice Q4 2024"
-F "correspondent=5"
-F "document_type=3"
-F "tags=1"
-F "tags=7"
-F "created=2024-10-15"
-F "archive_serial_number=00142"
-F "custom_fields=[{\"field\": 1, \"value\": \"Custom Value\"}]"

# Response: Task UUID
"550e8400-e29b-41d4-a716-446655440000"
```

---

### 4. Dokument-Verwaltung

```bash
# Dokument abrufen
GET /api/documents/{id}/

# Metadaten aktualisieren (PATCH!)
PATCH /api/documents/{id}/
Content-Type: application/json

{
  "title": "Updated Invoice Title",
  "correspondent": 5,
  "document_type": 2,
  "tags": [1, 3, 7],
  "archive_serial_number": 142,
  "custom_fields": [{"field": 1, "value": "Updated Value"}]
}

# Original herunterladen
GET /api/documents/{id}/download/

# Archiv-Version (PDF/A) herunterladen
GET /api/documents/{id}/download/?original=false
```

---

### 5. Custom Fields API

```bash
# Custom Fields auflisten
GET /api/custom_fields/

# Custom Field erstellen
POST /api/custom_fields/
{
  "name": "Rechnungsnummer",
  "data_type": "string",
  "extra_data": {"select_options": []}
}
```

---

## 🔧 Integration Patterns

### Scanner-to-Folder-to-Paperless
1. Scanner speichert in Netzwerk-Ordner
2. Paperless-ngx Consumer überwacht Ordner
3. OCR und Indexierung automatisch
4. Workflow-Regeln wenden Tags/Korrespondenten an

### Email-basierte Ingestion
1. Email-Account überwachen
2. Anhänge automatisch extrahieren
3. In Paperless-ngx importieren
4. Absender als Korrespondent speichern

### ERP-System Integration
```bash
# Rechnung aus ERP hochladen
# → Paperless-ngx verarbeitet OCR
# → API gibt Dokument-ID zurück
# → ERP speichert Dokument-ID für Verknüpfung
```

---

## 📊 Best Practices

1. **Asynchrone Verarbeitung:** Uploads return Task UUID → Status prüfen
2. **Workflows nutzen:** Automatische Kategorisierung statt manuelles Tagging
3. **Custom Fields:** Für projektspezifische Metadaten
4. **Archive Serial Number:** Für physische Ablage-Verknüpfung
5. **PATCH statt PUT:** Für partielle Updates

---

## 🔗 Weitere Ressourcen

- **Paperless-AI:** `/clusterzx/paperless-ai` - AI-powered Klassifizierung
- **Paperless-GPT:** `/icereed/paperless-gpt` - LLM-enhanced OCR
- **Paperless-Stack:** `/timothystewart6/paperless-stack` - Docker Compose Setup

---

*Diese Dokumentation wurde über Context7 MCP generiert und sollte regelmäßig aktualisiert werden.*