Document Intelligence API

Schnellstart — erste Antwort in 5 Minuten

curl -H "Authorization: Bearer $KEY" https://di.api.1885.cloud/health

curl -X POST https://di.api.1885.cloud/v1/classify \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"tender_ref": "DTAD:24545281"}'

Was kann die API schon? — der Story-Katalog

Jede Fähigkeit der Engine ist als User Story beschrieben: WAS für WEN aus Dokumenten gelesen wird, mit Akzeptanzkriterien und ehrlichem Status (produktiv/teilweise/geplant). Bevor ihr integriert: di.1885.cloud/stories durchsuchen (Themenblöcke: Ausschreibung, Prüfprotokolle, CAD-Zeichnungen, ISO 50001, Lieferscheine, Bescheinigungen) und prüfen, ob euer Bedarf schon bestellt ist. Fehlt eure Story? Direkt auf der Seite als Wunsch einreichen — jeder Wunsch wird vom Product Owner beantwortet, freigegebene Stories erscheinen im Katalog. Maschinenlesbar (ohne Key):

curl "https://di.api.1885.cloud/v1/stories?q=Pr%C3%BCftermin"

Antwort (echt, gekürzt): {"stories_gesamt":1,"themen":[{"titel":"Prüfprotokolle & Arbeitssicherheit","stories":[{"id":"PRF-1","persona":"Geräteverantwortliche:r","status":"geplant","natur":1,…}]}]} · Filter: ?thema=, ?status=produktiv, ?natur=2 · Wunsch: POST /v1/stories/wunsch

Sofort loslegen — mit euren eigenen Dokumenten

Der schnellste erste Erfolg: nehmt irgendein eigenes PDF — ein Prüfprotokoll, eine Rechnung, einen Lieferschein, ein Zeugnis — und reicht es bei POST /v1/dokumente ein (Rezept 1). Die API sagt euch, was sie erkannt hat und was sie damit kann; Unbekanntes beantwortet sie ehrlich statt mit einem Fehler. Für Beispiele ohne eigene Daten gibt es zusätzlich den gehosteten Beispiel-Datensatz DTAD:24545281 (Bau-Paket) — jeder gültige Key darf ihn abrufen, die Extraktions-Beispiele dieser Seite laufen damit unverändert per Copy & Paste. Kein Termin, keine Freigabe nötig.

Rezepte — komplette Wege, Schritt für Schritt

Referenz sagt was geht, Rezepte zeigen wie du ans Ziel kommst. Alle Antworten unten sind echt (gekürzt).

Rezept 1: Eigene Dokumente einreichen und verstehen (der Normalfall)

Für alle, die Prüfprotokolle, Rechnungen, Lieferscheine, Bescheinigungen oder Zeugnisse verarbeiten wollen.

curl -X POST https://di.api.1885.cloud/v1/dokumente -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"dokumente": [{"filename": "pruefprotokoll.pdf", "content_base64": "'$(base64 -w0 pruefprotokoll.pdf)'"}]}'

{"dokumenttyp": "geraetepruefprotokoll", "triage": "AUTO",
 "evidenz": "Prüf- und Messprotokoll Wiederholungsprüfung …",
 "weiterverarbeitung": {"status": "geplant", "hinweis": "DGUV-V3-/VDE-0701-0702-Prüfprotokolle: Gerätedaten, Sicht-/Mess-/Funktionsprüfung, Grenzwerte, nächster Prüftermin …"}}

Rezept 1b: Extraktion mit Fundstelle + Prüfquellen (am gehosteten Beispiel)

curl -X POST https://di.api.1885.cloud/v1/extract -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"tender_ref": "DTAD:24545281", "fields": ["procurement_number", "binding_deadline"]}'

Rezept 1c: Rechnung prüfen — PDF, XRechnung/ZUGFeRD oder Scan

Ein Endpoint für alle drei Fälle; die Antwort sagt in lesequelle ehrlich, welcher Weg gelesen hat (text_schicht / xrechnung_ubl|cii / zugferd_* / ocr_mistral).

curl -X POST https://di.api.1885.cloud/v1/pruefung -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "rechnung.xml", "content_base64": "'$(base64 -w0 rechnung.xml)'"}'

import base64, requests
r = requests.post("https://di.api.1885.cloud/v1/pruefung",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"filename": "rechnung.pdf",
          "content_base64": base64.b64encode(open("rechnung.pdf","rb").read()).decode()})
for p in r.json()["punkte"]:
    print(p["ampel"], p["feld"], "—", p.get("rechtsgrundlage",""))

POST /v1/pruefung  {"filename": ..., "content_base64": ..., "modus": "async"}
→ 202 {"job_id": "<uuid>", "polling_url": "/v1/jobs/<uuid>"}
GET /v1/jobs/<uuid>  → {"status": "fertig", "ergebnis": { ... komplette Antwort ... }}

Rezept 2: Zweifelsfälle abarbeiten (Prüfer-Workflow)

curl -H "Authorization: Bearer $KEY" "https://di.api.1885.cloud/v1/review?status=offen&limit=10"

curl -X POST https://di.api.1885.cloud/v1/review/claim -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"id": "<uuid>", "bearbeiter": "anna.p"}'
curl -X POST https://di.api.1885.cloud/v1/review/entscheid -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "<uuid>", "bearbeiter": "anna.p", "entscheidung": "bestaetigt"}'

POST <eure URL>  ·  Header: X-1885-Signature: sha256=<hmac>
{"ereignis": "neue_eintraege", "tender_ref": "DTAD:24545281", "anzahl": 2,
 "eintraege": [{"id": "<uuid>", "field_key": "contract_penalty", "grund": "Lesungen divergieren: …"}]}

Rezept 3: Eine Scan-Seite bauen (Upload beliebiger Unterlagen)

curl -X POST https://di.api.1885.cloud/v1/dokumente -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"dokumente": [{"filename": "gutachten.pdf", "content_base64": "<base64>"}]}'

Antwort-Prinzipien (gelten überall)

• Fundstelle je Wert: Datei, Seite, wörtliches Zitat — zum Nachklicken.
• Kein Ratewert: was die Unterlagen nicht hergeben, kommt als not_checkable/NOT_FOUND zurück.
• Konsens & Triage: mehrere unabhängige Lesungen; Dissens wird ausgewiesen statt übertüncht.
• Prüfquellen je Feld: validation_sources dokumentiert, welche Instanz den Wert bestätigt oder verletzt hat — Konsens, Format-Regel (mit Norm-Zitat, z. B. ISO 7064) oder Plausibilität. AUTO gibt es nur mit mindestens einer bestätigenden Quelle; eine verletzte harte Regel schickt das Feld zu REVIEW.
• Gemessene Qualität: der Mess-Stand je Pack ist öffentlich abrufbar unter /v1/tuev (JSON, ohne Key) — Methodik in llms-full.txt.
• Dauer: Lese-Endpoints antworten in Sekunden; /v1/extract ohne fields und Flächenläufe brauchen Minuten — Client-Timeout entsprechend setzen (≥ 300 s) — oder /v1/pruefung asynchron aufrufen (modus: async): 202 mit job_id + polling_url (GET /v1/jobs/<id>), optional signierter Webhook.

Fehler — Ursache und Lösung

Gateway-Fehler sind application/problem+json mit maschinenlesbarem code — verzweigt im Client auf code, nie auf den Text.

Für Agenten — finden, verstehen, integrieren ohne Menschen

• Fähigkeiten prüfen (zuerst!): GET /v1/stories (ohne Key) — der Story-Katalog sagt, WAS für WEN die API liest und ob es produktiv ist. Nie eine Fähigkeit versprechen, die dort nicht produktiv gelistet ist; Fehlendes per POST /v1/stories/wunsch bestellen.
• Entdecken: di.1885.cloud/llms.txt — kompakte, maschinenlesbare Selbstbeschreibung (Fähigkeiten, Auth, Beispiele). Kataloge aller 1885-APIs: developer.1885.cloud/llms.txt.
• Verstehen: /openapi.json (Routen) + diese Seite (strukturierte Abschnitte, stabile Anker).
• Integrieren (empfohlen): MCP. Streamable-HTTP-Server unter POST /mcp — die Tools spiegeln die Routen inkl. Beschreibungen. Konfiguration:

  { "mcpServers": { "1885-di": {
      "type": "http",
      "url": "https://di.api.1885.cloud/mcp?apiKey=<KEY>" } } }

• Schlüssel: Bearer-Keys, je Produkt gescopet, einzeln sperrbar (Unkey). Die Ausgabe läuft bewusst über einen menschlichen Owner — Agenten nennen ihrem Betreiber Zweck + gewünschte Produkte, der Owner beantragt bei Auriga.
• Vertragsregeln für Agenten: Werte nur mit Fundstelle weiterverwenden; not_checkable respektieren (nicht auffüllen); lange Läufe (/v1/extract) asynchron einplanen.

Betrieb & Verlässlichkeit

• Status & Änderungen: Statusseite und Changelog (beide auch als JSON mit ?format=json).
• Limits (ehrlich): 15 MB je Dokument, 10 Dokumente je /v1/dokumente-Aufruf. Ratelimit-Vertrag: Sandbox-Keys 60 Anfragen/Minute — darüber 429 mit Retry-After-Header (code rate_limit): so lange warten, dann wiederholen. Produktiv-Keys ohne hartes Limit (fair use); derselbe 429-Vertrag gilt, sobald ein Limit konfiguriert wird. Bei 5xx: Backoff 30–60 s.
• Idempotenz: POST /v1/pruefung nimmt einen Idempotency-Key-Header an: gleicher Key + gleicher Body → gespeicherte Antwort erneut (Header Idempotency-Replayed: true, im Async-Fall dieselbe job_id); gleicher Key + anderer Body → 422. Fenster 48 h. Empfohlen für jeden Retry — kein Dokument wird doppelt geprüft.
• Versionierung: additive Änderungen (neue Felder, neue Prüfpunkte) jederzeit — Clients müssen unbekannte Felder ignorieren. Breaking Changes nur als neue Version (/v2/...): Ankündigung im Changelog, ab dann Deprecation- und Sunset-Header auf den Alt-Routen, mindestens 6 Monate Parallelbetrieb; /v1 bleibt dabei bedienbar.
• Datenhaltung: synchron geprüfte Dokumente werden verarbeitet, nicht gespeichert. Async-Jobs speichern das Prüfergebnis (nicht das Dokument) in der Job-Tabelle (EU-Datenbank), abrufbar über die job_id. Verbindliche Aufbewahrungs-/GoBD-Zusagen: über Auriga anfragen.
• Offboarding: Key-Widerruf jederzeit (formlos an Auriga oder via developer.1885.cloud; Sandbox-Keys verfallen nach 14 Tagen von selbst). Gespeicherte Job-Ergebnisse vor dem Ausstieg per GET /v1/jobs/<id> exportieren; Löschung aller Job-Ergebnisse auf Zuruf. Es gibt keinen Lock-in: alle Daten, die ihr uns gabt, habt ihr selbst — wir halten nur Prüfergebnisse.

Schlüssel & Verwaltung

Zentrale Verwaltung über Unkey (Workspace „Auriga Strategy“): pro Nutzer/Partner/Agent ein eigener Schlüssel mit Produkt-Scope, einzeln sperrbar. Antrag: Formular auf developer.1885.cloud — Genehmigung und Erzeugung laufen zentral im Admin-Bereich. Verwendung immer als Authorization: Bearer <KEY>, Ablage als Umgebungsvariable/Secret.

Auriga Strategy · developer.1885.cloud · Base-URL https://di.api.1885.cloud — die bisherige Adresse di.1885.cloud bleibt dauerhaft gültig (Übergangs-Alias: api.1885.cloud) · Status · Changelog · Stand 15.07.2026