API-Referenz

API- Dokumentation

Alle Endpoints mit Parametern, Beispiel-Responses und kopierbaren curl-Befehlen. Für Einsteiger und Profis.

8 Endpoints

Bearer-Auth

JSON Responses

Erste Schritte

Authentifizierung

Die API nutzt Bearer-Token-Authentifizierung. Du brauchst einen API-Schlüssel, den du in den Einstellungen deines Accounts erstellen kannst.

So funktioniert es

1Erstelle einen API-Schlüssel in den Einstellungen deines Documentr-Accounts. Der Schlüssel beginnt mit dk_ und wird nur einmal angezeigt — kopiere ihn sofort.

2Sende den Schlüssel bei jedem API-Request im Authorization-Header mit:

Beispiel-Request

curl -H "Authorization: Bearer dk_dein_schlüssel" \
     https://documentr.app/api/v1/stats

Dein API-Schlüssel wird serverseitig mit SHA-256 gehasht gespeichert. Er ist an deinen Account gebunden — du siehst nur deine eigenen Dokumente. Maximal 5 Schlüssel pro Account.

Dokumente

Dokumente-Endpoints

Dokumente auflisten, einzelne Dokumente abrufen und PDF-Dateien herunterladen.

GET/api/v1/documents

Gibt eine paginierte Liste deiner Dokumente zurück. Du kannst nach Tags, Ordnern, Absender, Favoriten, Archiv-Status und Datum filtern. Alle Filter sind optional und kombinierbar.

Parameter

Name	Typ	Pflicht	Beschreibung
`limit`	integer	Nein	Anzahl Ergebnisse pro Seite (Standard: 50 (max. 100))
`offset`	integer	Nein	Überspringt die ersten N Ergebnisse (für Pagination) (Standard: 0)
`tag`	string	Nein	Filtert nach Dokumenten mit diesem Tag (Teilsuche, Groß-/Kleinschreibung egal)
`folder`	string	Nein	Filtert nach Dokumenten in diesem Ordner (Teilsuche)
`sender`	string	Nein	Filtert nach Absender (Teilsuche)
`favorite`	boolean	Nein	Wenn true, nur favorisierte Dokumente
`archived`	boolean	Nein	Wenn true, nur archivierte Dokumente (Standard: false)
`fromDate`	string (date)	Nein	Nur Dokumente ab diesem Datum (ISO 8601, z.B. 2025-01-01)
`toDate`	string (date)	Nein	Nur Dokumente bis zu diesem Datum

Response

{
  "data": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Nebenkostenabrechnung 2024",
      "summary": "Jährliche Nebenkostenabrechnung für die Wohnung in der Bergstraße 12.",
      "sender": "Hausverwaltung Müller GmbH",
      "documentDate": "2025-03-15T00:00:00.000Z",
      "isFavorite": false,
      "createdAt": "2025-03-20T14:30:00.000Z",
      "folder": "Wohnung",
      "tags": ["Nebenkosten", "2024", "Wohnung"]
    }
  ],
  "meta": {
    "total": 142,
    "limit": 50,
    "offset": 0
  }
}

curl

curl -H "Authorization: Bearer dk_dein_schlüssel" \
     "https://documentr.app/api/v1/documents?tag=Rechnung&limit=10"

GET/api/v1/documents/:uuid

Gibt alle Details eines einzelnen Dokuments zurück, identifiziert per UUID. Enthält Titel, Zusammenfassung, Absender, Datum, Tags, Ordner und mehr.

Parameter

Name	Typ	Pflicht	Beschreibung
`uuid`	string	Ja	Die UUID des Dokuments (findest du z.B. in der Dokumentliste)

Response

{
  "data": {
    "info": "Dokument gefunden.",
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Mietvertrag Bergstraße 12",
    "summary": "Mietvertrag zwischen Max Mustermann und Hausverwaltung Müller GmbH für die 3-Zimmer-Wohnung in der Bergstraße 12, 10115 Berlin.",
    "sender": "Hausverwaltung Müller GmbH",
    "documentDate": "2023-07-01T00:00:00.000Z",
    "createdAt": "2023-07-05T10:15:00.000Z",
    "folder": "Wohnung",
    "tags": ["Mietvertrag", "Wohnung", "2023"],
    "isFavorite": true,
    "isArchived": false,
    "pageCount": 8,
    "hasVectorData": true
  }
}

curl

curl -H "Authorization: Bearer dk_dein_schlüssel" \
     "https://documentr.app/api/v1/documents/a1b2c3d4-e5f6-7890-abcd-ef1234567890"

GET/api/v1/documents/:uuid/download

Gibt die originale PDF-Datei eines Dokuments als Download zurück. Der Response hat den Content-Type application/pdf.

Parameter

Name	Typ	Pflicht	Beschreibung
`uuid`	string	Ja	Die UUID des Dokuments

Response

(Binäre PDF-Datei — Content-Type: application/pdf)

curl

curl -H "Authorization: Bearer dk_dein_schlüssel" \
     -o dokument.pdf \
     "https://documentr.app/api/v1/documents/a1b2c3d4-.../download"

Suche

Suche-Endpoints

Zwei Suchvarianten: Textsuche über Metadaten und semantische Suche im Dokumentinhalt.

POST/api/v1/documents/search

Durchsucht Titel, Zusammenfassung und Absender aller Dokumente per Trigram-Matching. Findet auch unscharfe Treffer — z.B. "Stromrechung" findet "Stromrechnung". Ideal wenn du nach einem bestimmten Dokumentnamen oder Absender suchst.

Request Body

{
  "query": "Stromrechnung Stadtwerke"
}

Response

{
  "data": {
    "info": "3 Treffer für \"Stromrechnung Stadtwerke\".",
    "results": [
      {
        "uuid": "...",
        "title": "Stromrechnung Q4 2024",
        "summary": "Quartalsabrechnung der Stadtwerke München...",
        "sender": "Stadtwerke München",
        "similarity": 0.85,
        "documentDate": "2025-01-15T00:00:00.000Z",
        "tags": ["Rechnung", "Strom", "2024"]
      }
    ]
  }
}

curl

curl -X POST \
     -H "Authorization: Bearer dk_dein_schlüssel" \
     -H "Content-Type: application/json" \
     -d '{"query": "Stromrechnung Stadtwerke"}' \
     "https://documentr.app/api/v1/documents/search"

POST/api/v1/documents/search-content

Durchsucht den gesamten Inhalt deiner Dokumente per Vektorähnlichkeit. Versteht die Bedeutung deiner Anfrage — nicht nur Schlüsselwörter. Perfekt wenn du eine spezifische Information suchst, die irgendwo im Text steht.

Request Body

{
  "query": "Wie hoch ist die Kündigungsfrist meines Mietvertrags?",
  "limit": 5
}

Response

{
  "data": {
    "info": "5 semantische Treffer.",
    "results": [
      {
        "uuid": "...",
        "title": "Mietvertrag Bergstraße 12",
        "content": "...Die Kündigungsfrist beträgt drei Monate zum Monatsende gemäß § 573c BGB...",
        "similarity": 0.92,
        "pageNumber": 4,
        "documentDate": "2023-07-01T00:00:00.000Z"
      }
    ]
  }
}

curl

curl -X POST \
     -H "Authorization: Bearer dk_dein_schlüssel" \
     -H "Content-Type: application/json" \
     -d '{"query": "Kündigungsfrist Mietvertrag", "limit": 5}' \
     "https://documentr.app/api/v1/documents/search-content"

Organisation

Organisation-Endpoints

Tags und Ordner deiner Bibliothek abfragen — inklusive der Anzahl enthaltener Dokumente.

GET/api/v1/tags

Gibt alle Tags zurück, die du in deiner Bibliothek verwendest — sortiert nach Dokumentanzahl (häufigste zuerst). Unterstützt Pagination.

Parameter

Name	Typ	Pflicht	Beschreibung
`limit`	integer	Nein	Anzahl Ergebnisse (Standard: 50 (max. 100))
`offset`	integer	Nein	Offset für Pagination (Standard: 0)

Response

{
  "data": [
    { "name": "Rechnung", "documentCount": 47 },
    { "name": "Vertrag", "documentCount": 23 },
    { "name": "Versicherung", "documentCount": 18 },
    { "name": "Steuer", "documentCount": 12 }
  ],
  "meta": { "total": 35, "limit": 50, "offset": 0 }
}

curl

curl -H "Authorization: Bearer dk_dein_schlüssel" \
     "https://documentr.app/api/v1/tags"

GET/api/v1/folders

Gibt alle Ordner zurück — sortiert nach Dokumentanzahl. Jeder Ordner hat einen Namen, ein optionales Icon und die Anzahl enthaltener Dokumente.

Parameter

Name	Typ	Pflicht	Beschreibung
`limit`	integer	Nein	Anzahl Ergebnisse (Standard: 50 (max. 100))
`offset`	integer	Nein	Offset für Pagination (Standard: 0)

Response

{
  "data": [
    { "name": "Versicherungen", "icon": "🛡️", "documentCount": 28 },
    { "name": "Wohnung", "icon": "🏠", "documentCount": 19 },
    { "name": "Arbeit", "icon": "💼", "documentCount": 15 },
    { "name": "Steuer", "icon": "📊", "documentCount": 12 }
  ],
  "meta": { "total": 8, "limit": 50, "offset": 0 }
}

curl

curl -H "Authorization: Bearer dk_dein_schlüssel" \
     "https://documentr.app/api/v1/folders"

Statistik

Statistik-Endpoints

Kennzahlen deiner Dokumentenbibliothek auf einen Blick.

GET/api/v1/stats

Gibt einen Überblick über deine gesamte Bibliothek: wie viele Dokumente du hast, wie viele davon analysiert, archiviert oder favorisiert sind, plus Anzahl deiner Tags und Ordner.

Response

{
  "data": {
    "totalDocuments": 142,
    "analyzedDocuments": 138,
    "archivedDocuments": 12,
    "favoriteDocuments": 23,
    "totalTags": 35,
    "totalFolders": 8
  }
}

curl

curl -H "Authorization: Bearer dk_dein_schlüssel" \
     "https://documentr.app/api/v1/stats"

Technische Details

Pagination & Rate-Limiting

Pagination

Listen-Endpoints unterstützen limit und offset Parameter.

Standard: 50 Ergebnisse pro Seite, maximal 100.

Jede Antwort enthält ein meta-Objekt mit total, limit und offset.

Rate-Limiting

Die Limits hängen von deinem Plan ab:

Free20 Requests / Minute

Plus100 Requests / Minute

Unlimited300 Requests / Minute

Response-Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Fehlerbehandlung

HTTP Status-Codes

Bei Fehlern gibt die API einen passenden HTTP-Statuscode mit einer Fehlernachricht zurück.

400

Bad Request

Die Anfrage ist fehlerhaft — z.B. fehlt ein Pflicht-Parameter oder das JSON-Format ist ungültig.

401

Unauthorized

Kein API-Schlüssel mitgesendet oder der Schlüssel ist ungültig. Prüfe den Authorization-Header.

404

Not Found

Das angeforderte Dokument wurde nicht gefunden — entweder existiert die UUID nicht oder es gehört einem anderen Account.

429

Too Many Requests

Rate-Limit überschritten. Warte die im Retry-After Header angegebene Zeit ab, bevor du es erneut versuchst.

Bereit, die API zu nutzen?

Erstelle einen API-Schlüssel und schicke deinen ersten Request in unter einer Minute.

Kostenlos starten Zurück zur Übersicht