REST-API

Alles, was der Browser tut, läuft über die REST-API des Servers; andere Programme können sie ebenso nutzen, etwa um Annotationen zu importieren oder die Statistik zu lesen.

Grundlagen

  • Alle Routen liegen unter /api; Anfragen und Antworten sind JSON. folder und name sind Query-Parameter.

  • Alles außer GET /api/status und den Anmelderouten braucht eine Sitzung: Melden Sie sich mit POST /api/auth/login an und senden Sie das Sitzungs-Cookie mit jeder Anfrage.

  • Ändernde Anfragen (POST, PUT, DELETE) brauchen den Header X-Requested-With: lsa.

  • Der Benutzer ist immer der angemeldete. Routen zu Bildern, Einstellungen, Verlauf und Hinweisen nehmen project=<ID> (Standard: das einzige Projekt des Benutzers, sonst default).

  • Fehler: {"error": "<Code>", "message": "<Text>"} mit dem HTTP-Status (400 fehlerhafte Anfrage, 401 nicht angemeldet, 403 Rolle fehlt, 404 nicht gefunden, 409 Konflikt, 423 gesperrt).

curl -c cookies.txt -H "X-Requested-With: lsa" -H "Content-Type: application/json" \
     -d '{"username":"anna","password":"..."}' https://annotation.example.com/api/auth/login
curl -b cookies.txt "https://annotation.example.com/api/images?project=line-5&folder=2026-10-28"

Routen

Rolle in Klammern: Admin ist der Server-Admin; die anderen Rollen sind die Rollen des Benutzers im Projekt.

Anmeldung und Benutzer

Methode und Pfad Zweck

GET /status

Version, Lizenzstatus (öffentlich)

GET /auth/providers

Angebotene Anmeldeverfahren (öffentlich)

POST /auth/login

{username, password}: lokales Konto, dann Verzeichnis → Sitzungs-Cookie

GET /auth/oidc/start, /auth/oidc/callback

Single Sign-on (Browser-Weiterleitungen)

POST /auth/logout

Sitzung beenden; liefert bei Single-Sign-on-Sitzungen die Abmeldeadresse des Anbieters

GET /auth/me

Der angemeldete Benutzer und seine Rollen

POST /auth/password

{current, password}: eigenes Passwort ändern (lokale Konten)

GET/POST /admin/users, PUT/DELETE /admin/users/<Name>, POST /admin/users/<Name>/password

Benutzerverwaltung (Admin)

GET/PUT /admin/mappings

Zuordnungen Gruppe → Rolle (Admin)

GET /admin/auth, POST /admin/auth/test-ldap

Konfigurierte Anmeldeverfahren, Verzeichnisanmeldung testen (Admin)

GET/POST /admin/backups, GET /admin/backups/<Datei>

Sicherungen auflisten, erstellen und herunterladen (Admin)

Projekte

Methode und Pfad Zweck

GET /projects

Projekte des Benutzers mit seinen Rollen; für Admins auch die S3-Ziele

POST /projects

{name, description, folder?, storage?, prefix?, openToAll}: neues Projekt (Admin)

GET/PUT /projects/<ID>

Details; Name, Beschreibung, offen für alle, Mitglieder (Project admin)

DELETE /projects/<ID>

{deleteFiles}: Projekt entfernen (Admin)

GET /projects/<ID>/export[?history=0]

Die Projektdatei (tar) (Admin)

POST /projects/import, PUT /projects/import/<Upload>?offset=, POST /projects/import/<Upload>/finish

Projektdatei in Stücken hochladen und als neues Projekt entpacken (Admin)

GET /people

Personen mit einer Rolle im Projekt (als Empfänger für Hinweise)

Bilder und Annotationen

Methode und Pfad Zweck

GET /folders

Unterordner des Projekts

GET /images?folder=

Bilder mit Annotations- und Sperrstatus und offenen Hinweisen; bei mehreren Annotatoren auch Anzahlen und Prüfstand

GET /image?folder=&name=

Das Bild (PNG)

GET /annotations?folder=&name=[&layer=annotator]

Rahmen, Bildgröße, Revision, Sperre. layer=annotator: Ihre eigene Version

PUT /annotations?folder=&name=[&layer=annotator]

Speichern {session, baseRevision, boxes, force?} → 409 bei Konflikt, 423 bei Sperre

POST/DELETE /lock?folder=&name=[&layer=annotator]

Bearbeitungssperre nehmen, erneuern oder freigeben ({session})

DELETE /image?folder=&name=

Ein Bild mit Dateien, Versionen, Verlauf und Hinweisen löschen (Project admin)

POST /geometry/fit-box

Kleinster gedrehter Rahmen um {points: [[x, y], …]}

Ein Rahmen ist {"cx": 412.3, "cy": 267.8, "width": 188.0, "height": 71.4, "angle": -0.385, "label": "bracket", "metadata": null} (Winkel in Radiant).

Verlauf, Hinweise, Einstellungen

Methode und Pfad Zweck

GET /history?folder=&name=[&layer=annotator&owner=], GET /history/version?id=

Gespeicherte Versionen einer Annotation; eine Version mit ihren Rahmen

GET /notes?folder=&name=, GET /notes/open[?mine=1]

Überarbeitungshinweise eines Bildes; offene Hinweise des Projekts

POST /notes, PUT/DELETE /notes/<ID>

{folder, name, text, assignee, x?, y?}; {status, reply, text}; löschen (Verfasser oder Project admin)

GET /settings, PUT /settings

Projekteinstellungen (ändern: Project admin)

POST /labels

Ein Label zur gemeinsamen Liste hinzufügen (Annotator, Reviewer)

Prüfung und Vorschläge

Methode und Pfad Zweck

GET /compare?folder=&name=

Die Rahmen aller Annotatoren, zugeordnete Objekte und Abweichungen (Reviewer)

GET /statistics[?folder=]

Übereinstimmungsstatistik für einen Ordner oder das Projekt (Reviewer)

POST /preannotate?folder=&name=

Rahmenvorschläge; Body {boxes?, labels?}; 501 ohne Dienst, 502, wenn keiner antwortet

GET /preannotate/services

Die Dienste für Rahmenvorschläge, ihre Backends und Netze