REST-API

WORLDGATE
Ordnung!

REST-API

Alles, was die Oberfläche kann, geht auch per REST-API: für Skripte, iOS-Kurzbefehle, Home Assistant oder den Scanner, der direkt in den Posteingang liefern soll. Anfragen und Antworten sind JSON. Die Beispiele unten sind echte Antworten einer Demo-Installation mit der erfundenen Familie Muster.

Inhalt
  1. Erste Schritte
  2. Endpunkte
  3. Liste und Suche
  4. Beispiele
  5. Aus einem Skript
  6. Fehler

Erste Schritte

  1. In Ordnung! als Administrator anmelden, Einstellungen → API öffnen und Neu erzeugen klicken. Kopieren legt den Schlüssel in die Zwischenablage.
  2. Jede Anfrage schickt ihn als Kopfzeile mit: Authorization: Bearer <Schlüssel>.
  3. Erster Versuch im Terminal:
curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/documents?q=versicherung&limit=5"

Der Schlüssel handelt wie ein Administrator und sieht alle Bereiche, er gehört also nur in vertrauenswürdige Skripte. Neu erzeugen macht den alten sofort ungültig, Löschen schaltet den Zugang per Schlüssel ab. Ohne Schlüssel lässt sich die API nur mit einer Anmeldung im Browser nutzen.

Alle Endpunkte zum Ausprobieren: Ordnung! beschreibt seine API selbst unter /api/docs (maschinenlesbar unter /api/openapi.json). Wer im Browser angemeldet ist, kann dort jeden Aufruf mit Try it out direkt abschicken. Der Link steht auch unter Einstellungen → API.

Dokumente haben eine id, die sechs Zeichen am Ende des Dateinamens. Bereiche heißen wie ihre Ordner (familie, erika …), Ordner sind Pfade darunter (Versicherungen/Nordlicht/Hausrat).

↑ nach oben

Endpunkte

MethodePfadWofür
System
GET/api/versionVersion, ohne Anmeldung
GET/api/statusAnzahl Dokumente, Stand der Texterkennung, letztes Einlesen
POST/api/rescanOrdner jetzt neu einlesen
Archiv
GET/api/areasBereiche mit Anzeigenamen
GET/api/tree?areas=…Ordnerbaum mit Anzahl
GET/api/documentsListe und Suche, Parameter siehe unten
GET/api/documents/{id}ein Dokument mit Titel, Datum, Ordner, Tags
GET/api/documents/{id}/filedie Datei selbst (PDF)
GET/api/documents/{id}/texterkannter Text
PATCH/api/documents/{id}Titel und Datum ändern, benennt die Datei um
POST/api/documents/{id}/movein einen anderen Ordner oder Bereich
POST/api/documents/{id}/trashin den Papierkorb
Tags und Mappen
GET/api/tagsalle Tags mit Anzahl
PUT/api/documents/{id}/tagsTags eines Dokuments setzen
POST/api/tags/changeTags für viele Dokumente hinzufügen oder entfernen
GET/api/mappenMappen
GET/api/mappen/download?name=…&format=pdfeine Mappe als eine PDF (oder zip)
Posteingang
GET/api/inboxneue Dokumente mit Vorschlägen
POST/api/inbox/uploadDateien hochladen (Base64), Fotos werden PDFs
POST/api/inbox/{key}/fileablegen: Bereich, Ordner, Titel, Datum, Tags
POST/api/inbox/{key}/dismissverwerfen
Altablage
POST/api/altablageDokumente, Ordner oder alles älter als X Jahre hinein oder zurück; dry_run zählt nur

↑ nach oben

Liste und Suche

ParameterBedeutung
qSuchwörter, alle müssen vorkommen; #tag filtert nach Tag. Ohne folder geht die Suche über das ganze Archiv.
folder, recursiveOrdner und ob Unterordner dazugehören
areasBereiche, mit Komma getrennt; ohne: alle erlaubten
tagsTags, mit Komma getrennt, alle müssen passen
alttrue sucht auch in der Altablage
sort, descdate (Standard, neueste zuerst), title, area oder relevance (beste Treffer zuerst, nur bei einer Suche); desc=false dreht die Richtung
limit, offsetseitenweise holen, Standard 500

↑ nach oben

Beispiele

System

Version

GET /api/version

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/version"

Antwort · 200

{
  "name": "Ordnung!",
  "version": "2026.11.70"
}

Zustand

GET /api/status

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/status"

Antwort · 200

{
  "total": 17,
  "last_scan": "2026-11-09T09:34:10",
  "last_scan_seconds": 0.0,
  "scanning": false,
  "texts": {
    "total": 17,
    "done": 17,
    "ocr_pages": 0,
    "errors": 0,
    "empty": 0,
    "running": false
  },
  "readonly": false,
  "version": "2026.11.70",
  "ocr": false,
  "inbox": {
    "new": 3,
    "filed": 0,
    "dismissed": 0,
    "reading": 0
  },
  "reference": null
}

Archiv

Bereiche

GET /api/areas

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/areas"

Antwort · 200

[
  {
    "name": "erika",
    "count": 4,
    "label": "Erika"
  },
  {
    "name": "familie",
    "count": 5,
    "label": "Familie"
  },
  "…"
]

Ordnerbaum

GET /api/tree?areas=erika

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/tree?areas=erika"

Antwort · 200

{
  "name": "",
  "path": "",
  "count": 4,
  "own": 0,
  "areas": [
    "erika"
  ],
  "children": [
    {
      "name": "Arbeit",
      "path": "Arbeit",
      "count": 1,
      "own": 0,
      "areas": [
        "erika"
      ],
      "children": [
        {
          "name": "Gehalt",
          "path": "Arbeit/Gehalt",
          "count": 1,
          "own": 1,
          "areas": [
            "erika"
          ],
          "children": []
        }
      ]
    },
    {
      "name": "Ausweise",
      "path": "Ausweise",
      "count": 1,
      "own": 1,
      "areas": [
        "erika"
      ],
      "children": []
    },
    "…"
  ],
  "alt": {
    "name": "Altablage",
    "path": "Altablage",
    "count": 0,
    "own": 0,
    "areas": [],
    "children": []
  }
}

Suchen

GET /api/documents?q=versicherung&limit=2

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/documents?q=versicherung&limit=2"

Antwort · 200

{
  "total": 5,
  "items": [
    {
      "id": "f6a89a",
      "sha256": "f6a89ace4feb…",
      "path": "familie/Versicherungen/Nordlicht/Hausrat/2026-01-12_Versicherungsschein Hausrat_f6a89a.pdf",
      "area": "familie",
      "folder": "Versicherungen/Nordlicht/Hausrat",
      "name": "2026-01-12_Versicherungsschein Hausrat_f6a89a.pdf",
      "ext": "pdf",
      "title": "Versicherungsschein Hausrat",
      "date": "2026-01-12",
      "size": 1891,
      "snippet": "Nordlicht \u0002Versiche\u0003…",
      "tags": []
    },
    {
      "id": "90c76a",
      "sha256": "90c76aba6003…",
      "path": "haus/Versicherungen/Nordlicht/Wohngebäude/2026-01-12_Versicherungsschein Wohngebäude_90c76a.pdf",
      "area": "haus",
      "folder": "Versicherungen/Nordlicht/Wohngebäude",
      "name": "2026-01-12_Versicherungsschein Wohngebäude_90c76a.pdf",
      "ext": "pdf",
      "title": "Versicherungsschein Wohngebäude",
      "date": "2026-01-12",
      "size": 2021,
      "snippet": "Nordlicht \u0002Versiche\u0003…",
      "tags": [
        "Steuererklärung 2026"
      ]
    }
  ]
}

Beste Treffer zuerst

GET /api/documents?q=versicherung&sort=relevance&limit=2

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/documents?q=versicherung&sort=relevance&limit=2"

Antwort · 200

{
  "total": 5,
  "items": [
    {
      "id": "f6a89a",
      "sha256": "f6a89ace4feb…",
      "path": "familie/Versicherungen/Nordlicht/Hausrat/2026-01-12_Versicherungsschein Hausrat_f6a89a.pdf",
      "area": "familie",
      "folder": "Versicherungen/Nordlicht/Hausrat",
      "name": "2026-01-12_Versicherungsschein Hausrat_f6a89a.pdf",
      "ext": "pdf",
      "title": "Versicherungsschein Hausrat",
      "date": "2026-01-12",
      "size": 1891,
      "snippet": "Nordlicht \u0002Versiche\u0003…",
      "tags": []
    },
    {
      "id": "90c76a",
      "sha256": "90c76aba6003…",
      "path": "haus/Versicherungen/Nordlicht/Wohngebäude/2026-01-12_Versicherungsschein Wohngebäude_90c76a.pdf",
      "area": "haus",
      "folder": "Versicherungen/Nordlicht/Wohngebäude",
      "name": "2026-01-12_Versicherungsschein Wohngebäude_90c76a.pdf",
      "ext": "pdf",
      "title": "Versicherungsschein Wohngebäude",
      "date": "2026-01-12",
      "size": 2021,
      "snippet": "Nordlicht \u0002Versiche\u0003…",
      "tags": [
        "Steuererklärung 2026"
      ]
    }
  ]
}

Ein Ordner, alphabetisch

GET /api/documents?folder=Versicherungen/Nordlicht/Hausrat&areas=familie&sort=title&desc=false

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/documents?folder=Versicherungen/Nordlicht/Hausrat&areas=familie&sort=title&desc=false"

Antwort · 200

{
  "total": 1,
  "items": [
    {
      "id": "f6a89a",
      "sha256": "f6a89ace4feb…",
      "path": "familie/Versicherungen/Nordlicht/Hausrat/2026-01-12_Versicherungsschein Hausrat_f6a89a.pdf",
      "area": "familie",
      "folder": "Versicherungen/Nordlicht/Hausrat",
      "name": "2026-01-12_Versicherungsschein Hausrat_f6a89a.pdf",
      "ext": "pdf",
      "title": "Versicherungsschein Hausrat",
      "date": "2026-01-12",
      "size": 1891,
      "snippet": null,
      "tags": []
    }
  ]
}

Ein Dokument

GET /api/documents/f6a89a

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/documents/f6a89a"

Antwort · 200

{
  "id": "f6a89a",
  "sha256": "f6a89ace4feb…",
  "path": "familie/Versicherungen/Nordlicht/Hausrat/2026-01-12_Versicherungsschein Hausrat_f6a89a.pdf",
  "area": "familie",
  "folder": "Versicherungen/Nordlicht/Hausrat",
  "name": "2026-01-12_Versicherungsschein Hausrat_f6a89a.pdf",
  "ext": "pdf",
  "title": "Versicherungsschein Hausrat",
  "date": "2026-01-12",
  "size": 1891,
  "snippet": null,
  "copies": [
    "familie/Versicherungen/Nordlicht/Hausrat/2026-01-12_Versicherungsschein Hausrat_f6a89a.pdf"
  ],
  "text": {
    "pages": 1,
    "ocr_pages": 0,
    "method": "text",
    "error": "",
    "chars": 497
  },
  "tags": []
}

Erkannter Text

GET /api/documents/f6a89a/text

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/documents/f6a89a/text"

Antwort · 200

Nordlicht Versicherung 
Nordlicht Versicherung · www.nordlicht-versicherung.test · info@nordlicht-versicherung.test 
Familie Muster 
Lindenweg 5 
12345 Musterstadt 
Musterstadt, 12.01.2026 
Versicherungsschein Hausrat 
Sehr geehrte Damen un…

Titel und Datum ändern

PATCH /api/documents/f6a89a

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     -X PATCH \
     -H "Content-Type: application/json" \
     -d '{"title": "Versicherungsschein Hausrat (Kopie fürs Finanzamt)", "date": "2026-01-12"}' \
     "https://ordnung.example.org/api/documents/f6a89a"

Antwort · 200

{
  "path": "familie/Versicherungen/Nordlicht/Hausrat/2026-01-12_Versicherungsschein Hausrat (Kopie fürs Finanzamt)_f6a89a.pdf",
  "id": "f6a89a"
}

Verschieben

POST /api/documents/f6a89a/move

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{"folder": "Steuern/2025"}' \
     "https://ordnung.example.org/api/documents/f6a89a/move"

Antwort · 200

{
  "path": "familie/Steuern/2025/2026-01-12_Versicherungsschein Hausrat_f6a89a.pdf",
  "id": "f6a89a"
}

Tags und Mappen

Tags für viele Dokumente

POST /api/tags/change

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{"ids": ["f6a89a"], "add": ["Steuer 2026"]}' \
     "https://ordnung.example.org/api/tags/change"

Antwort · 200

{
  "changed": 1
}

Alle Tags

GET /api/tags

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/tags"

Antwort · 200

[
  {
    "name": "Bad",
    "count": 1
  },
  {
    "name": "Steuer 2026",
    "count": 1
  },
  "…"
]

Nach Tag filtern

GET /api/documents?tags=Steuer%202026

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/documents?tags=Steuer%202026"

Antwort · 200

{
  "total": 1,
  "items": [
    {
      "id": "f6a89a",
      "sha256": "f6a89ace4feb…",
      "path": "familie/Versicherungen/Nordlicht/Hausrat/2026-01-12_Versicherungsschein Hausrat_f6a89a.pdf",
      "area": "familie",
      "folder": "Versicherungen/Nordlicht/Hausrat",
      "name": "2026-01-12_Versicherungsschein Hausrat_f6a89a.pdf",
      "ext": "pdf",
      "title": "Versicherungsschein Hausrat",
      "date": "2026-01-12",
      "size": 1891,
      "snippet": null,
      "tags": [
        "Steuer 2026"
      ]
    }
  ]
}

Mappen

GET /api/mappen

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/mappen"

Antwort · 200

[
  {
    "name": "Steuererklärung 2026",
    "area": "familie",
    "count": 6,
    "writable": true
  }
]

Posteingang

Datei in den Posteingang

POST /api/inbox/upload

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{"files": [{"name": "rechnung-heizung.pdf", "data": "JVBERi0xLjQK…"}], "combine": false}' \
     "https://ordnung.example.org/api/inbox/upload"

Antwort · 201

{
  "names": [
    "rechnung-heizung.pdf"
  ]
}

Posteingang mit Vorschlägen

GET /api/inbox

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/inbox"

Antwort · 200

{
  "items": [
    {
      "key": "c420aef54a5f",
      "inbox": "8d4ad354",
      "inbox_name": "Scanner",
      "rel": "scan_20261103_001.pdf",
      "name": "scan_20261103_001.pdf",
      "ext": "pdf",
      "size": 1846,
      "status": "new",
      "added": "2026-11-09T09:34:10",
      "filed_path": "",
      "text": {
        "chars": 491,
        "pages": 1,
        "ocr_pages": 0,
        "method": "text",
        "error": ""
      },
      "ai": null,
      "suggestion": {
        "area": "",
        "folder": "Versicherungen/Nordlicht/Wohngebäude",
        "source": "rule",
        "title": "",
        "title_fallback": "Wohngebäude",
        "date": "2026-11-03",
        "date_fallback": "2026-11-09",
        "candidates": [
          {
            "folder": "Versicherungen/Nordlicht/Wohngebäude",
            "source": "rule",
            "rules": [
              {
                "rule": "584ff08f",
                "folder": "Versicherungen/Nordlicht/Wohngebäude",
                "source": "auto",
                "conditions": [
                  {
                    "type": "id",
                    "value": "WG-4471-2026"
                  }
                ]
              }
            ]
          }
        ],
        "conflict": false,
        "duplicate": null
      }
    },
    {
      "key": "448edcc4e8d7",
      "inbox": "8d4ad354",
      "inbox_name": "Scanner",
      "rel": "scan_20261105_002.pdf",
      "name": "scan_20261105_002.pdf",
      "ext": "pdf",
      "size": 1757,
      "status": "new",
      "added": "2026-11-09T09:34:10",
      "filed_path": "",
      "text": {
        "chars": 402,
        "pages": 1,
        "ocr_pages": 0,
        "method": "text",
        "error": ""
      },
      "ai": null,
      "suggestion": {
        "area": "",
        "folder": "",
        "source": "",
        "title": "",
        "title_fallback": "scan_20261105_002",
        "date": "2026-11-05",
        "date_fallback": "2026-11-09",
        "candidates": [],
        "conflict": false,
        "duplicate": null
      }
    },
    "…"
  ],
  "counts": {
    "new": 4,
    "filed": 0,
    "dismissed": 0,
    "reading": 1
  },
  "archive_writable": true,
  "inboxes": [
    {
      "id": "8d4ad354",
      "name": "Scanner",
      "area": "",
      "enabled": true,
      "after_import": "move",
      "delete_days": 0,
      "status": {
        "exists": true,
        "readable": true,
        "writable": true
      }
    }
  ],
  "folders": [
    "Arbeit",
    "Arbeit/Gehalt",
    "…"
  ],
  "areas": [
    "erika",
    "familie",
    "…"
  ]
}

Altablage

Probelauf: was älter als ein Jahr ist

POST /api/altablage

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{"older_than_years": 1, "dry_run": true}' \
     "https://ordnung.example.org/api/altablage"

Antwort · 200

{
  "count": 1,
  "folders": [
    {
      "folder": "Ausweise",
      "count": 1
    }
  ]
}

Fehler

Unbekanntes Dokument

GET /api/documents/000000

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/documents/000000"

Antwort · 404

{
  "detail": "document not found"
}

Ungültiger Parameter

GET /api/documents?sort=zufall

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/documents?sort=zufall"

Antwort · 422

{
  "detail": [
    {
      "type": "string_pattern_mismatch",
      "loc": [
        "query",
        "sort"
      ],
      "msg": "String should match pattern '^(|date|title|area|relevance)$'",
      "input": "zufall",
      "ctx": {
        "pattern": "^(|date|title|area|relevance)$"
      }
    }
  ]
}

Falscher Schlüssel

GET /api/me

Anfrage

curl -H "Authorization: Bearer $ORDNUNG_KEY" \
     "https://ordnung.example.org/api/me"

Antwort · 401

{
  "detail": "not authenticated"
}

↑ nach oben

Aus einem Skript

Dasselbe in Python, ohne Zusatzpakete: die fünf neuesten Treffer zu „Versicherung“ ausgeben und eine PDF in den Posteingang legen.

import base64, json, urllib.request

HOST = "https://ordnung.example.org"
KEY = "dein-schluessel"            # Einstellungen → API

def api(path, body=None):
    req = urllib.request.Request(HOST + path, method="POST" if body else "GET",
                                 data=json.dumps(body).encode() if body else None,
                                 headers={"Authorization": "Bearer " + KEY,
                                          "Content-Type": "application/json"})
    with urllib.request.urlopen(req) as r:
        return json.load(r)

for d in api("/api/documents?q=versicherung&limit=5")["items"]:
    print(d["date"], d["title"], "→", d["area"] + "/" + d["folder"])

pdf = base64.b64encode(open("rechnung.pdf", "rb").read()).decode()
print(api("/api/inbox/upload", {"files": [{"name": "rechnung.pdf", "data": pdf}]}))

↑ nach oben

Fehler

Fehler kommen als HTTP-Status mit einer Begründung in detail.

StatusBedeutung
400unzulässige Änderung, z. B. Ordner schon der gleiche
401nicht angemeldet oder falscher Schlüssel
403keine Rechte im Bereich
404nicht gefunden
409Konflikt, z. B. gibt es die Datei am Ziel schon
422ungültige Parameter

↑ nach oben

← Zum Handbuch