---
title: "REST-API"
description: "REST-API des Servers von LumiScan Annotation Web: Anmeldung, Projekte, Bilder, Annotationen, Sperren, Verlauf, Hinweise, Prüfung und Vorschläge."
product: "LumiScan Annotation Web"
component: "lumiscan-annotation-web-de"
version: "2.3.0"
display_version: "2.3.0.0"
latest_version: false
language: "de"
url: "https://docs.hdvisionsystems.com/de/lumiscan-annotation-web-de/2.3.0/rest-api.html"
---

# REST-API – LumiScan Annotation Web

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).

```bash
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, angenommene Bildformate und die Grenze für hochgeladene Dateien (ö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, offenen Hinweisen, Rahmenanzahl und Labels der Referenzannotation, nach der Bewertung die Unsicherheit des Netzes, die Exportmenge (`set`), die Fertig-Markierung (`done`, `doneBy`, `doneAt`), bei TIFF-Seiten `file` und `page`; bei mehreren Annotatoren auch Anzahlen und Prüfstand |
| `GET /image?folder=&name=` | Das Bild: PNG, JPEG und BMP wie gespeichert, TIFF-Seiten als PNG (eine Seite heißt `scan.tif#2`, URL-kodiert `scan.tif%232`) |
| `PUT /image/done?folder=&name=` | `{"done": true}` oder `false`: Bild als fertig markieren oder die Markierung entfernen (Annotator, Reviewer) |
| `PUT /images/upload?folder=&name=` | Eine Bilddatei hinzufügen, gesendet als Inhalt (`application/octet-stream`); `newFolder=1` legt den Ordner an; größere Dateien in Stücken mit `offset` (bisherige Bytes) und `total` (Dateigröße). 409 `exists`, wenn der Name oder seine Annotationsdatei vergeben ist (Project admin) |
| `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 |
| `POST /uncertainty/scan` | `{folder, includeAnnotated?, rescore?}`: Das Netz bewertet die Bilder des Ordners im Hintergrund (Annotator) |
| `GET /uncertainty/status`, `POST /uncertainty/cancel` | Fortschritt der Bewertung; abbrechen |
| `GET /training-export/preview` | Was ein Export für LumiScan Training enthielte; Parameter `name`, `network`, `validation`, `test`, `together=1`, `folder` (wiederholbar), `nonRotable` (wiederholbar) (Reviewer) |
| `GET /training-export` | Der Export als ZIP-Datei, gleiche Parameter (Reviewer) |
| `GET /coco-export` | Der COCO-Export, gleiche Parameter und dazu `format=zip` (Bilder und Annotationen) oder `format=json` mit `set=all`, `train`, `val` oder `test` (Reviewer) |