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

Datenschutz & Cookies

Mit deiner Einwilligung messen wir pseudonym die Reichweite dieser Seite (Google Analytics) und den Erfolg unserer Anzeigen. In der App tracken wir nicht. Du kannst frei entscheiden und deine Wahl jederzeit über „Cookie-Einstellungen" im Footer ändern.

Mehr in der Datenschutzerklärung