# REST-API (Projekte, Testfälle, Sequenzen, Ergebnisse)

## Was ist das?

Die REST-API ist der programmatische **Lesezugang** zu Ihren Daten:
Fremdsysteme (PLM, Jira, eigene Skripte, Dashboards) können Projekte,
Testfälle, Sequenzen und Testergebnisse auslesen — ohne Browser-Anmeldung.
Ihre Daten bleiben damit Ihre Daten: alles, was in TestLabIQ steht, ist
maschinell abrufbar (zusätzlich zum CSV-Export in der Oberfläche) — kein
Lock-in.

Die API ist bewusst **nur lesend**. Anlegen und Ändern läuft über die
Oberfläche; die einzigen Ausnahmen laufen nicht über das Organisations-Token,
sondern über den **Prüfstand-eigenen** API-Key: die Messdaten-Anlieferung über
die [Ingestion-API](https://www.testlabiq.com/hilfe/messdaten) bzw. [MQTT](https://www.testlabiq.com/hilfe/mqtt-anbindung),
sowie das Setzen des eigenen Prüfstandsstatus (`PATCH /api/v1/stations/me/status`,
siehe [Messdaten](https://www.testlabiq.com/hilfe/messdaten)). Weitere Schreibzugriffe
über das Organisations-Token sind vorgesehen und folgen zusammen mit der
Aktionsklassen-Steuerung (Freigabe je Aktionstyp).

## So benutzt man es

1. **Zugang einrichten lassen:** Es gibt aktuell keine Selbstbedienung dafür
   (siehe [Agent-Zugang](https://www.testlabiq.com/hilfe/agent-tokens)) — wenden Sie sich für eine
   Anbindung an unser Team.
2. **Aufrufen:** Token im Header `Authorization: Bearer <token>` mitsenden.

### Endpunkte (alle lesend)

| Pfad | Zweck | Recht |
|---|---|---|
| `GET /api/v1/projects` | Projekte auflisten (`?archived=`, Pagination) | projects:read |
| `GET /api/v1/projects/{id}` | Projekt mit Meilensteinen | projects:read |
| `GET /api/v1/test-cases` | Testfälle auflisten (`?group=`, `?search=`) | test-cases:read |
| `GET /api/v1/test-cases/{id}` | Testfall inkl. erwarteter Messgrößen | test-cases:read |
| `GET /api/v1/sequences` | Sequenzen auflisten (`?projectId=`) | test-runs:read |
| `GET /api/v1/sequences/{id}` | Sequenz mit Testfall-Items und Status | test-runs:read |
| `GET /api/v1/sequences/{id}/results` | Ergebnisse je Item und Messkanal | test-runs:read |
| `GET /api/v1/ingestion/deliveries` | Messdaten-Zustell-Log (REST, MQTT & CSV) | stations:read |

Messdaten anliefern (`POST /api/v1/measurements`) läuft über den
**Prüfstand-API-Key**, nicht über das Organisations-Token — siehe
[Messdaten](https://www.testlabiq.com/hilfe/messdaten).

### Beispiel: Ergebnisse einer Sequenz abrufen

```bash
curl https://<ihre-instanz>/api/v1/sequences/<id>/results \
  -H "Authorization: Bearer <token>"
```

Antwort: je Testfall-Item der Status und je Messkanal bestanden/nicht
bestanden mit gemessenem Min/Avg/Max gegen die Grenzwerte — maschinell
weiterverarbeitbar, ohne den PDF-Bericht zu parsen.

### Pagination

Listen liefern `{ "data": [...], "nextCursor": "<id>" }`. Solange `nextCursor`
nicht `null` ist, die nächste Seite mit `?cursor=<nextCursor>` holen.
`?limit=` steuert die Seitengröße (1–200, Standard 50).

### Fehler

Fehler kommen immer als `{ "error": { "code": "...", "message": "..." } }` mit
stabilem Code: `VALIDATION` (400), `PERMISSION_DENIED` (401/403), `NOT_FOUND`
(404), `CONFLICT`/`PRECONDITION` (409), `LIMIT_EXCEEDED` (429).

## Typische Probleme

- **`401` — Token fehlt/ungültig.** Header prüfen (`Authorization: Bearer …`).
  Ein gesperrtes Token bleibt auch dann ungültig, wenn es sonst korrekt
  aussieht.
- **`403 PERMISSION_DENIED`.** Die Rolle des Tokens hat das nötige Leserecht
  nicht.
- **`404 NOT_FOUND` bei existierender ID.** Die ID gehört zu einer anderen
  Organisation oder der Datensatz ist gelöscht. Tokens sehen ausschliesslich
  die eigene Organisation.
- **`405 Method Not Allowed` bei POST/PUT/PATCH.** Die API ist nur lesend —
  Anlegen und Ändern läuft über die Oberfläche (siehe oben).

---

Quelle: https://www.testlabiq.com/hilfe/rest-api