Auslieferungs-Feed abrufen

GET

/v1/scans

const url = 'https://api.legentio.com/v1/scans?since=2026-01-01T00%3A00%3A00Z&status=completed%2Cfailed&environment=prod&limit=50';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.legentio.com/v1/scans?since=2026-01-01T00%3A00%3A00Z&status=completed%2Cfailed&environment=prod&limit=50' \
  --header 'Authorization: Bearer <token>'

Der Feed ist der Auslieferungsmechanismus (Ersatz für Webhooks). Er ist eine geordnete Sicht auf abgeschlossene Produktionsläufe, sortiert nach Auslieferungszeitpunkt. Der Server merkt sich nichts als „konsumiert“; der Client speichert den zurückgegebenen nextCursor und schickt ihn beim nächsten Poll wieder mit.

Wichtige Eigenschaften:

Auslieferung ist at-least-once: Nach einem Absturz kann derselbe Lauf (scanId, revision) erneut erscheinen – die Verarbeitung muss idempotent sein (Upsert nach scanId, höchste revision gewinnt).
Ein Retry oder eine Korrektur erhöht revision und lässt den Lauf erneut im Feed auftauchen, vor jedem gespeicherten Cursor.
status, environment und documentType sind Lesezeit-Filter über eine einzige Sequenz – der Cursor läuft auch über übersprungene Läufe hinweg weiter, Filter dürfen zwischen zwei Polls gewechselt werden.

Authorizations

orgApiKey

Parameters

Query Parameters

cursor

string

Opake Position aus dem nextCursor der vorherigen Antwort. Schließt since aus.

since

string

Startet den Feed an einem vergangenen Zeitpunkt (Backfill/Recovery): ISO-8601-Zeitstempel oder Millisekunden seit 1970. Schließt cursor aus. Ohne cursor und ohne since beginnt der Feed am Anfang der Historie.

Example

2026-01-01T00:00:00Z

status

string

default: completed

Komma-getrennte Teilmenge aus completed,failed. Standard: nur completed.

Example

completed,failed

environment

string

default: prod

Allowed values: prod test all

prod (Standard, nur Produktionsläufe), test (nur Testläufe) oder all (beide). Jeder Eintrag trägt zusätzlich sein eigenes environment-Feld.

documentType

string

Auf einen Dokumenttyp-Slug einschränken.

limit

integer

default: 50 >= 1 <= 200

Seitengröße, 1–200.

markdown

string

true/1/yes hängt das erkannte markdown an jeden Eintrag an (aus der Inline-Kopie auf dem Lauf).

Responses

200

Eine Seite des Feeds.

application/json

object

items

required

Array

object

scanId

required

string

revision

required

Revision des Laufs. Steigt bei Retry/Korrektur und liefert den Lauf erneut im Feed aus. Clients behalten die höchste Revision je scanId.

integer

status

required

Im Feed nur completed/failed. In der Einzelabfrage kann zusätzlich processing (aus uploaded/processing) auftreten.

string

Allowed values: processing completed failed

environment

required

string

Allowed values: prod test

documentType

required

object

slug

Slug des Dokumenttyps zum Zeitpunkt des Laufs.

string | null

name

Anzeigename des Dokumenttyps zum Zeitpunkt des Laufs.

string | null

fileName

required

Ursprünglicher Dateiname des eingereichten PDFs.

string

partnerName

Der klassifizierte Partner (Sender) des Dokuments, falls erkannt.

string | null

partnerTestMode

true, wenn der klassifizierte Partner für diesen Dokumenttyp im Testmodus steht. Der Lauf wird normal verarbeitet und im Feed ausgeliefert, sollte aber vom Client als Testlauf behandelt und nicht produktiv weiterverarbeitet werden. false, wenn kein Partner erkannt wurde oder der Partner produktiv ist.

boolean

ocrConfidence

Gesamtkonfidenz der Erkennung, falls vorhanden.

number | null

data

Strukturiertes Erkennungsergebnis (nur bei status = completed vorhanden). Die Felder entsprechen dem Schema des Dokumenttyps.

object | null

failureReason

Maschinenlesbarer Fehlergrund (nur bei status = failed).

string | null

error

Menschenlesbare Fehlermeldung (nur bei status = failed).

string | null

submittedAt

Zeitpunkt der Einreichung (ISO 8601).

string | null format: date-time

completedAt

Zeitpunkt des Abschlusses (ISO 8601).

string | null format: date-time

deliveredAt

Auslieferungszeitpunkt im Feed (ISO 8601).

string | null format: date-time

resultTruncated

true, wenn data (oder markdown) zu groß war, um inline im Feed mitgeliefert zu werden. Dann den vollständigen Wert über GET /v1/scans/{scanId} nachladen.

boolean

markdown

Erkanntes Markdown – nur enthalten, wenn ?markdown=true gesetzt wurde.

string | null

nextCursor

required

Opake Position für den nächsten Poll. Persistiere sie und sende sie als cursor beim nächsten Abruf.

string

Example

{
  "items": [
    {
      "status": "processing",
      "environment": "prod"
    }
  ]
}

400

Ungültige Parameter – z. B. cursor und since gleichzeitig, ungültiger Cursor, ungültiger status/environment-Wert oder limit außerhalb 1–200.

application/json

object

error

required

Menschenlesbare Fehlermeldung (deutsch).

string

Example

{
  "error": "Dokumenttyp nicht gefunden."
}

401

API-Schlüssel fehlt oder ist ungültig.

application/json

object

error

required

Menschenlesbare Fehlermeldung (deutsch).

string

Example

{
  "error": "Dokumenttyp nicht gefunden."
}

403

Der API-Schlüssel gehört zu keiner Organisation.

application/json

object

error

required

Menschenlesbare Fehlermeldung (deutsch).

string

Example

{
  "error": "Dokumenttyp nicht gefunden."
}

404

Der über documentType angegebene Dokumenttyp wurde nicht gefunden.

application/json

object

error

required

Menschenlesbare Fehlermeldung (deutsch).

string

Example

{
  "error": "Dokumenttyp nicht gefunden."
}