API-Einstieg

Notory bringt eine vollständige REST-API mit. Die stabile Oberfläche liegt unter /api/v1 und ist versioniert: eine Breaking Change würde als neuer Versionspfad ausgeliefert, sodass Integrationen gegen /api/v1 weiterlaufen.

Die vollständige, durchsuchbare Referenz aller Endpunkte findest du unter API-Referenz.

Basis-URL

https://<deine-instanz>/api/v1

Auf der Live-Demo also https://demo.notory.io/api/v1. Die maschinenlesbare OpenAPI-Spec wird unter /api/openapi.json ausgeliefert. Daraus lässt sich mit einem OpenAPI-Generator ein typisierter Client in jeder Sprache erzeugen (es wird kein separates SDK benötigt).

Authentifizierung

Es gibt zwei Wege:

Browser-Sessions nutzen HttpOnly-Cookies plus einen CSRF-Token (X-CSRF-Token). Das ist der Weg der Weboberfläche.
Programmatische Clients senden einen API-Token als Bearer-Header:

curl -H "Authorization: Bearer inv_dein_token" \
  https://demo.notory.io/api/v1/assets

API-Tokens beginnen mit dem Präfix inv_. Du erstellst und verwaltest sie in der Weboberfläche unter Einstellungen → API-Tokens (siehe API-Tokens). Der Token wird nur einmal bei der Erstellung im Klartext angezeigt. Danach wird nur noch sein Hash gespeichert.

Token-Scopes

Ein Token kann Scopes tragen:

Scope	Wirkung
`read`	Nur lesende Zugriffe (`GET`, `HEAD`, `OPTIONS`).
`write`	Schreibende Zugriffe (`POST`, `PUT`, `DELETE`); schließt Lesen ein.
(leer)	Voller Zugriff im Rahmen der Rolle des Token-Besitzers (Abwärtskompatibilität).

Der Token erbt immer die Rolle und den Mandanten seines Besitzers. Ein Token kann also nie mehr, als der Benutzer selbst darf (RBAC + Mandanten-Isolation gelten weiter).

SSO / SCIM

Identity-Provider können Benutzer per SCIM 2.0 unter /scim/v2 bereitstellen. SSO/OIDC wird pro Mandant konfiguriert (siehe SSO / OIDC).

Rate-Limits

Sensible Endpunkte (v. a. Login/Auth) sind pro Client-IP rate-limited (Standard: 60 Anfragen/Minute). Wird das Limit überschritten, antwortet die API mit HTTP 429 (Too Many Requests); der Retry-After-Header nennt die Wartezeit. Baue in Integrationen ein Backoff ein.

Fehlercodes

Status	Bedeutung
`200` / `201`	Erfolg (`201` bei Neuanlage).
`400`	Ungültige Anfrage (z. B. fehlender Mandant im Token).
`401`	Nicht authentifiziert: Token fehlt, ist ungültig oder abgelaufen.
`403`	Authentifiziert, aber keine Berechtigung (Rolle/Scope/Feature-Gating).
`404`	Ressource nicht gefunden (oder außerhalb des eigenen Mandanten).
`422`	Validierungsfehler: die Antwort nennt Feld und Grund.
`429`	Rate-Limit erreicht (siehe oben).

Fehlerantworten folgen dem FastAPI-Schema { "detail": "..." } bzw. bei Validierungsfehlern einer strukturierten Liste unter detail.

Paginierung

Listen-Endpunkte paginieren über die Query-Parameter page (ab 1) und page_size (1 bis 100, Standard 25) und liefern ein Objekt mit items, total, page, page_size und total_pages.

Nächste Schritte

API-Referenz (Scalar): alle Endpunkte zum Ausprobieren.
Wie lege ich ein Asset an?: GUI- und API-Weg im Vergleich.
API-Tokens verwalten: Token erstellen und widerrufen.