---
icon: house
title: Fuxam API v4
sidebar:
  label: Einführung
  order: 0
description: Branchenübliche REST-API zur Integration mit der Fuxam-Plattform — Authentifizierung, Paginierung, Fehler und Endpunktreferenz.
---

Die **Fuxam API v4** ist eine versionierte REST-API, mit der Ihre Institution Studierendeninformationssysteme, Identity Provider, Reporting-Tools und eigene Middleware mit denselben Daten verbinden kann, die Ihre Mitarbeitenden in Fuxam Web verwalten. Jeder Endpunkt teilt einen Satz Konventionen für Authentifizierung, Antwortform, Paginierung, Fehler und Concurrency — sobald Sie die Muster auf dieser Seite kennen, können Sie sie auf Nutzer, Kurse, Curricula und den Rest des Ressourcenkatalogs anwenden.

**Base URL:** `https://fuxam.app/api/v4`

## Warum Institutionen integrieren

Universitäten laufen selten auf einem einzigen System. Zulassung kann in einem Produkt liegen, HR in einem anderen und die Lernplattform in einem dritten. Die Fuxam API existiert, damit diese Systeme autoritative Daten austauschen können, ohne doppelte Dateneingabe:

- **Identitäten bereitstellen und synchronisieren** mit denselben Nutzern, die Ihre Administratoren in der [Nutzerverwaltung](/docs/de/fuxam-web/base/user-management) verwalten.
- **Akademische Struktur lesen und aktualisieren** — Kurse, Module, Curricula, Studiengänge und Semester — im Einklang mit [FuxamCMS](/docs/de/fuxam-web/cms) und [FuxamLMS](/docs/de/fuxam-web/lms).
- **Operative Workflows automatisieren** wie Raum-Lookups, Termindaten und Fortschrittsreads, die sonst manuelle Exporte erfordern würden.

Die Integration ist institutionsbezogen: Zugangsdaten, die Sie unter **Organisation → API-Integrationen** erstellen, authentifizieren sich als Integration dieser Institution, nicht als einzelner Mitarbeiter.

## Wie das in Fuxam passt

Die API ist die programmatische Oberfläche von Konzepten, die Sie bereits aus dem Web-Handbuch kennen. Ein Nutzer in der API ist dieselbe Identität wie in der Nutzerverwaltung; eine Kurs-ID adressiert denselben Kurs, den Mitarbeitende in der Kursverwaltung oder im LMS öffnen.

```mermaid
flowchart LR
  External[Externe Systeme] --> API[Fuxam API v4]
  API --> Data[Nutzer Kurse Akademisches Einrichtungen]
  Data --> Web[Fuxam Web]
```

| API-Ressourcenbereich | Verwandte Themen im Web-Handbuch |
|---|---|
| Nutzer, Rollen, Nutzergruppen | [Nutzerverwaltung](/docs/de/fuxam-web/base/user-management), [Rollen und Berechtigungen](/docs/de/fuxam-web/base/user-management/roles-and-permissions), [Nutzergruppen](/docs/de/fuxam-web/base/user-management/user-groups) |
| Kurse, Inhaltsblöcke, Fortschritt | [Kursverwaltung](/docs/de/fuxam-web/cms/courses-management), [LMS-Kurse](/docs/de/fuxam-web/lms/courses), [Inhalt](/docs/de/fuxam-web/lms/content) |
| Module, Curricula, Studiengänge, Semester | [Akademische Struktur](/docs/de/fuxam-web/cms/academic-structure), [Studiengänge und Kohorten](/docs/de/fuxam-web/cms/programs-and-planning/study-programs-cohorts) |
| Räume, Termine | [Räume](/docs/de/fuxam-web/cms/academic-structure/rooms), [Kalender](/docs/de/fuxam-web/base/calendar) |

## Schlüsselkonzepte

| Konzept | Bedeutung |
|---|---|
| **Integration** | Ein unter **Organisation → API-Integrationen** registrierter API-Client mit `clientId` und `clientSecret`. |
| **Response envelope** | Erfolgreiche Antworten wrappen den Payload in `{ data, meta }` (Einzelressource) oder `{ data, pagination, meta }` (Listen). |
| **Cursor pagination** | Keyset-Paging mit `?limit=` und `?cursor=` — niemals Offset/`page`-basiert. |
| **Sparse fieldsets** | Optionales `?fields=`, um nur die benötigten Eigenschaften anzufordern. |
| **Problem details** | Fehler nutzen RFC 7807 `application/problem+json` mit einem stabilen maschinenlesbaren `code`. |
| **Idempotency** | Create-(`POST`)-Anfragen können `Idempotency-Key` senden, um doppelte Ressourcen bei Retry zu vermeiden. |
| **Optimistic concurrency** | Schreibvorgänge auf Einzelressourcen nutzen `ETag` / `If-Match`, damit gleichzeitige Updates sich nicht still überschreiben. |

## Konventionen auf einen Blick

- **Ein Response-Envelope** überall: `{ data, meta }` für eine Einzelressource, `{ data, pagination, meta }` für Listen.
- **Cursor-Paginierung**: `?limit=&cursor=`; Antworten tragen `pagination.next_cursor`, `pagination.has_more` und `pagination.limit`. Keine Offsets.
- **RFC-7807-Fehler** (`application/problem+json`) mit stabilem, maschinenlesbarem Top-Level-`code`.
- **Idempotente Creates** über den Header `Idempotency-Key`.
- **Sparse Fieldsets** über `?fields=id,email,…`.
- **Optimistic Concurrency** bei Schreibvorgängen auf Einzelressourcen: `GET`-Antworten enthalten ein starkes `ETag`; senden Sie es als `If-Match` bei `PATCH`, `PUT` oder `DELETE` zurück.

Jede Antwort enthält ein `meta`-Objekt mit `requestId`, `timestamp` und `version` (`"v4"`).

## Typischer Anfragefluss

```mermaid
sequenceDiagram
  participant Client
  participant API as Fuxam API v4
  Client->>API: GET with Basic Auth
  API-->>Client: 200 data meta and ETag
  Client->>API: PATCH with If-Match and body
  alt ETag matches
    API-->>Client: 200 updated resource
  else ETag stale
    API-->>Client: 412 precondition failed
  end
```

## Authentifizierung

Alle Anfragen nutzen **HTTP Basic Auth** mit Ihren Integrations-Zugangsdaten (`clientId:clientSecret`, Base64-kodiert):

```http
Authorization: Basic <base64(clientId:clientSecret)>
```

Erstellen Sie eine Integration unter **Organisation → API-Integrationen**, um `clientId` und `clientSecret` zu erhalten. API-Key-Berechtigungs-Scopes sind in v4 nicht implementiert — Basic Auth ist für die Integration Alles-oder-nichts.

Für eine vollständige Walkthrough zu Zugangsdaten und Sicherheitspraxis siehe [Authentifizierung](/docs/de/api/authentication).

## Response-Envelope

Einzelressource:

```json
{
  "data": { "id": "usr_123", "email": "user@example.com" },
  "meta": {
    "requestId": "req_1700000000000_abc123",
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v4"
  }
}
```

Liste (mit Cursor-Paginierung):

```json
{
  "data": [{ "id": "usr_123" }, { "id": "usr_456" }],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIzfQ==",
    "has_more": true,
    "limit": 25
  },
  "meta": {
    "requestId": "req_1700000000000_abc123",
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v4"
  }
}
```

Nutzen Sie `?fields=`, um auf unterstützten Endpunkten ein Sparse Fieldset anzufordern. Details und Schleifenbeispiele finden Sie unter [Paginierung und Filterung](/docs/de/api/pagination-and-filtering).

## Cursor-Paginierung

Listenendpunkte akzeptieren die Query-Parameter `?limit=` (1–100) und `?cursor=`:

| Parameter | Beschreibung |
|-----------|-------------|
| `limit` | Seitengröße (1–100; Server-Default gilt, wenn weggelassen) |
| `cursor` | Undurchsichtiger Cursor aus `pagination.next_cursor` der vorherigen Seite |

Cursor sind HMAC-signiert und an Ihre Institution und Integration gebunden. Manipulierte oder fremde Cursor liefern `400` mit dem Code `invalid_cursor`. Die Paginierung nutzt Keyset-Cursor über `(sortField, id)` — niemals Offset-basiertes Paging.

Wenn `pagination.has_more` `false` ist, haben Sie die letzte Seite erreicht.

## Fehlermodell (RFC 7807)

Alle Fehler verwenden `application/problem+json` mit `type` als URI `https://fuxam.app/errors/{code}`.

Es gibt **zwei getrennte `code`-Namespaces**:

- Der Top-Level-`code` ist die geschlossene `ApiErrorCode`-Union — maschinenlesbar und stabil.
- Jeder Eintrag in `errors[].code` ist ein **Zod-Issue-Code** (z. B. `invalid_string`) mit einem RFC-6901-`pointer` (z. B. `/email`).

```json
{
  "type": "https://fuxam.app/errors/resource_not_found",
  "title": "Not Found",
  "status": 404,
  "code": "resource_not_found"
}
```

**v4 sendet kein `403`.** Cross-Tenant-Zugriff liefert dasselbe `404 resource_not_found` wie eine wirklich fehlende Ressource — Existenz wird nie preisgegeben. Validierungsfehler liefern HTTP `422`.

Häufige Statuscodes: `200` Lesen/Aktualisieren, `201` erstellt, `204` gelöscht, `409` Konflikt oder laufender Idempotenz-Lock, `412` ETag-Mismatch, `428` fehlendes erforderliches `If-Match`, `429` Rate Limit (`Retry-After` beachten).

Vertiefte Abdeckung von Fehlerbehandlung, Idempotenz, Concurrency und Rate Limits finden Sie unter [Fehler und Idempotenz](/docs/de/api/errors-and-idempotency).

## Idempotenz

POST-Anfragen, die Ressourcen erstellen, akzeptieren einen `Idempotency-Key`-Header. Das erneute Senden desselben Schlüssels innerhalb des Idempotenzfensters liefert die zwischengespeicherte Antwort (einschließlich des ursprünglichen `201`) zurück, ohne ein Duplikat zu erzeugen. Konfliktierende laufende Schlüssel können `409` zurückgeben.

```http
Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

## Optimistic Concurrency

`GET`s auf Einzelressourcen senden ein starkes `ETag`. Senden Sie es als `If-Match` bei `PATCH`, `PUT` oder `DELETE` zurück:

- **412** `precondition_failed` — die Ressource hat sich seit dem Lesen geändert.
- **428** `precondition_required` — `If-Match` war erforderlich, fehlte aber.

## Rate Limits

Jede Integration teilt sich ein Budget von **1000 Anfragen/min** (gleitendes Fenster, Schlüssel aus Integration + Institution). Antworten enthalten `RateLimit-*`-Header; `429`-Antworten enthalten `Retry-After`.

:::info
**Migration von v3:** Base-Pfad `/api/v3` → `/api/v4`. Kurse werden über **id** adressiert (Lookup nach Code mit `GET /courses?code=…`). Listen nutzen `cursor`/`limit` statt `page`/`pageSize`. Listen-Bodies sind immer `{ data: [...] }`. Fehler enthalten einen stabilen `code`; Validierungsfehler sind `422`.
:::

## In diesem Abschnitt

Beginnen Sie mit den Leitfäden unten und nutzen Sie dann die Ressourcen-Karten für die Endpunktreferenz.

**[Erste Schritte](/docs/de/api/getting-started)**

Integration erstellen, authentifizieren und erste Listenanfrage stellen.

**[Authentifizierung](/docs/de/api/authentication)**

Basic Auth, Zugangsdaten, Rotation und Sicherheitspraxis.

**[Paginierung und Filterung](/docs/de/api/pagination-and-filtering)**

Cursor, Sparse Fieldsets und Filtermuster.

**[Fehler und Idempotenz](/docs/de/api/errors-and-idempotency)**

Problem Details, Retries, ETags und Rate Limits.

**[Rezepte](/docs/de/api/recipes)**

End-to-End-Muster für Sync, Lookup und sichere Writes.

## Wo Sie starten

1. Folgen Sie [Erste Schritte](/docs/de/api/getting-started), um Zugangsdaten zu erstellen und `GET /users` aufzurufen.
2. Lesen Sie [Authentifizierung](/docs/de/api/authentication), bevor Sie Secrets in der Produktion speichern.
3. Nutzen Sie [Paginierung und Filterung](/docs/de/api/pagination-and-filtering), wenn Sie große Sammlungen durchlaufen müssen.
4. Wenden Sie [Fehler und Idempotenz](/docs/de/api/errors-and-idempotency) an, bevor Sie Create- oder Update-Automatisierung starten.
5. Kopieren Sie ein Muster aus [Rezepte](/docs/de/api/recipes) und öffnen Sie dann die passende Endpunktreferenz unten.

## Nach Ressource durchsuchen

Endpunktreferenzseiten sind nach Ressourcen-Tag gruppiert und in die Abschnitte unten organisiert. Diese Routen werden aus der OpenAPI-Spezifikation generiert.

### Nutzer

**[Nutzer](/docs/de/api/users/users/list-users)**

Nutzerprofile, Mitgliedschaft, Lebenszyklus, Kontaktdaten

**[Rollen](/docs/de/api/users/users-roles-access/list-roles)**

Institutionsrollen und Nutzer-Rollenzuweisungen

### Kurse

**[Kurse](/docs/de/api/courses/courses/list-courses)**

Kurse (adressiert über id; Filter nach Code)

**[Inhaltsblöcke](/docs/de/api/courses/courses-content-blocks/list-content-blocks)**

Kurs-Inhaltsblöcke

**[Workbenches](/docs/de/api/courses/courses-workbenches/list-workbenches)**

Kurs-Workbenches

**[Nutzerfortschritt](/docs/de/api/courses/courses-user-progress/get-user-progress)**

Nutzerfortschritt über Inhaltsblöcke

**[Termine](/docs/de/api/appointments/appointments/list-appointments)**

Termine und Raumbuchungen

### Akademisches

**[Kursmodule](/docs/de/api/campus-management/campus-management-modules/list-modules)**

Kursmodule, Versionen und Gruppen

**[Curricula](/docs/de/api/campus-management/campus-management-curricula/list-curricula)**

Curricula, Versionen und verschachtelte Struktur

**[Studiengänge](/docs/de/api/campus-management/campus-management-study-programs/list-study-programs)**

Studiengänge, Versionen, Kohorten

**[Organisationssemester](/docs/de/api/campus-management/campus-management-organization-terms/list-organization-terms)**

Chronologie akademischer Semester

**[Kohorten](/docs/de/api/campus-management/campus-management-cohorts/list-cohorts)**

Kohorten innerhalb von Studiengängen

### Einrichtungen

**[Räume](/docs/de/api/room-management/room-management/list-rooms)**

Räume, Setups, Standorte, Ausstattung

### Zeiterfassung

**[Zeiterfassung](/docs/de/api/time-tracking/time-tracking/list-time-tracking-logs)**

Sitzungen, Protokolle und Zeitstempelvorlagen

### Verzeichnis

**[Nutzergruppen](/docs/de/api/users/users-user-groups/list-user-groups)**

Verzeichnis-Nutzergruppen und Mitgliedschaften
