---
icon: house
title: Fuxam API v4
sidebar:
  label: Introduction
  order: 0
description: Industry-standard REST API for integrating with the Fuxam platform — authentication, pagination, errors, and endpoint reference.
---

The **Fuxam API v4** is a versioned REST API that lets your institution connect student information systems, identity providers, reporting tools, and custom middleware to the same data your staff manage in Fuxam Web. Every endpoint shares one set of conventions for authentication, response shape, pagination, errors, and concurrency — so once you learn the patterns on this page, you can apply them across users, courses, curricula, and the rest of the resource catalog.

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

## Why institutions integrate

Universities rarely run on a single system. Admissions may live in one product, HR in another, and the learning platform in a third. The Fuxam API exists so those systems can exchange authoritative data without duplicate data entry:

- **Provision and sync identities** with the same users your administrators manage in [User Management](/docs/fuxam-web/base/user-management).
- **Read and update academic structure** — courses, modules, curricula, study programs, and terms — in line with [FuxamCMS](/docs/fuxam-web/cms) and [FuxamLMS](/docs/fuxam-web/lms).
- **Automate operational workflows** such as room lookups, appointment data, and progress reads that would otherwise require manual export.

Integration is institution-scoped: credentials you create under **Organization → API integrations** authenticate as that institution's integration, not as an individual staff user.

## How this fits into Fuxam

The API is the programmatic surface of concepts you already know from Handbook Web. A user in the API is the same identity as in User Management; a course id addresses the same course staff open in Courses Management or the LMS.

```mermaid
flowchart LR
  External[External systems] --> API[Fuxam API v4]
  API --> Data[Users courses academics facilities]
  Data --> Web[Fuxam Web]
```

| API resource area | Related Handbook Web topics |
|---|---|
| Users, roles, user groups | [User Management](/docs/fuxam-web/base/user-management), [Roles and permissions](/docs/fuxam-web/base/user-management/roles-and-permissions), [User groups](/docs/fuxam-web/base/user-management/user-groups) |
| Courses, content blocks, progress | [Courses Management](/docs/fuxam-web/cms/courses-management), [LMS courses](/docs/fuxam-web/lms/courses), [Content](/docs/fuxam-web/lms/content) |
| Modules, curricula, study programs, terms | [Academic structure](/docs/fuxam-web/cms/academic-structure), [Study programs and cohorts](/docs/fuxam-web/cms/programs-and-planning/study-programs-cohorts) |
| Rooms, appointments | [Rooms](/docs/fuxam-web/cms/academic-structure/rooms), [Calendar](/docs/fuxam-web/base/calendar) |

## Key concepts

| Concept | Meaning |
|---|---|
| **Integration** | An API client registered under **Organization → API integrations**, with a `clientId` and `clientSecret`. |
| **Response envelope** | Successful responses wrap the payload in `{ data, meta }` (single resource) or `{ data, pagination, meta }` (lists). |
| **Cursor pagination** | Keyset paging with `?limit=` and `?cursor=` — never offset/`page` based. |
| **Sparse fieldsets** | Optional `?fields=` to request only the properties you need. |
| **Problem details** | Errors use RFC 7807 `application/problem+json` with a stable machine-readable `code`. |
| **Idempotency** | Create (`POST`) requests can send `Idempotency-Key` to avoid duplicate resources on retry. |
| **Optimistic concurrency** | Single-resource writes use `ETag` / `If-Match` so concurrent updates do not silently overwrite each other. |

## Conventions at a glance

- **One response envelope** everywhere: `{ data, meta }` for a single resource, `{ data, pagination, meta }` for lists.
- **Cursor pagination**: `?limit=&cursor=`; responses carry `pagination.next_cursor`, `pagination.has_more`, and `pagination.limit`. No offsets.
- **RFC 7807 errors** (`application/problem+json`) with a stable, machine-readable top-level `code`.
- **Idempotent creates** via the `Idempotency-Key` header.
- **Sparse fieldsets** via `?fields=id,email,…`.
- **Optimistic concurrency** on single-resource writes: `GET` responses include a strong `ETag`; send it back as `If-Match` on `PATCH`, `PUT`, or `DELETE`.

Every response includes a `meta` object with `requestId`, `timestamp`, and `version` (`"v4"`).

## Typical request flow

```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
```

## Authentication

All requests use **HTTP Basic Auth** with your integration credentials (`clientId:clientSecret`, base64-encoded):

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

Create an integration under **Organization → API integrations** to obtain your `clientId` and `clientSecret`. API-key permission scopes are not implemented in v4 — Basic Auth is all-or-nothing for the integration.

For a full walkthrough of credential handling and security practice, see [Authentication](/docs/api/authentication).

## Response envelope

Single resource:

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

List (with cursor pagination):

```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"
  }
}
```

Use `?fields=` to request a sparse fieldset on supported endpoints. Details and loop examples are in [Pagination and filtering](/docs/api/pagination-and-filtering).

## Cursor pagination

List endpoints accept `?limit=` (1–100) and `?cursor=` query parameters:

| Parameter | Description |
|-----------|-------------|
| `limit` | Page size (1–100; server default applies if omitted) |
| `cursor` | Opaque cursor from the previous page's `pagination.next_cursor` |

Cursors are HMAC-signed and bound to your institution and integration. Tampered or foreign cursors return `400` with code `invalid_cursor`. Pagination uses keyset cursors over `(sortField, id)` — never offset-based paging.

When `pagination.has_more` is `false`, you have reached the last page.

## Error model (RFC 7807)

All errors use `application/problem+json` with `type` as the URI `https://fuxam.app/errors/{code}`.

There are **two distinct `code` namespaces**:

- The top-level `code` is the closed `ApiErrorCode` union — machine-readable and stable.
- Each entry in `errors[].code` is a **Zod issue code** (e.g. `invalid_string`) with an RFC-6901 `pointer` (e.g. `/email`).

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

**v4 emits no `403`.** Cross-tenant access returns the same `404 resource_not_found` as a truly missing resource — existence is never leaked. Validation failures return HTTP `422`.

Common status codes: `200` read/update, `201` created, `204` deleted, `409` conflict or in-flight idempotency lock, `412` ETag mismatch, `428` missing required `If-Match`, `429` rate limit (honor `Retry-After`).

Deep coverage of error handling, idempotency, concurrency, and rate limits is in [Errors and idempotency](/docs/api/errors-and-idempotency).

## Idempotency

POST requests that create resources accept an `Idempotency-Key` header. Submitting the same key twice within the idempotency window returns the cached response (including the original `201`) without creating a duplicate. Conflicting in-flight keys may return `409`.

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

## Optimistic concurrency

Single-resource `GET`s emit a strong `ETag`. Send it back as `If-Match` on `PATCH`, `PUT`, or `DELETE`:

- **412** `precondition_failed` — the resource changed since you read it.
- **428** `precondition_required` — `If-Match` was required but absent.

## Rate limits

Each integration shares a **1000 requests/min** budget (sliding window, keyed by integration + institution). Responses include `RateLimit-*` headers; `429` responses include `Retry-After`.

:::info
**Migrating from v3:** Base path `/api/v3` → `/api/v4`. Courses are addressed by **id** (look up by code with `GET /courses?code=…`). Lists use `cursor`/`limit` instead of `page`/`pageSize`. List bodies are always `{ data: [...] }`. Errors include a stable `code`; validation failures are `422`.
:::

## In this section

Start with the guides below, then use the resource cards for endpoint reference.

**[Getting started](/docs/api/getting-started)**

Create an integration, authenticate, and make your first list request.

**[Authentication](/docs/api/authentication)**

Basic Auth, credentials, rotation, and security practice.

**[Pagination and filtering](/docs/api/pagination-and-filtering)**

Cursors, sparse fieldsets, and filter patterns.

**[Errors and idempotency](/docs/api/errors-and-idempotency)**

Problem details, retries, ETags, and rate limits.

**[Recipes](/docs/api/recipes)**

End-to-end patterns for sync, lookup, and safe writes.

## Where to start

1. Follow [Getting started](/docs/api/getting-started) to create credentials and call `GET /users`.
2. Read [Authentication](/docs/api/authentication) before storing secrets in production.
3. Use [Pagination and filtering](/docs/api/pagination-and-filtering) when you need to walk large collections.
4. Apply [Errors and idempotency](/docs/api/errors-and-idempotency) before any create or update automation.
5. Copy a pattern from [Recipes](/docs/api/recipes), then open the matching endpoint reference below.

## Browse by resource

Endpoint reference pages are grouped by resource tag, organized into the sections below. These routes are generated from the OpenAPI specification.

### Users

**[Users](/docs/api/users/users/list-users)**

User profiles, membership, lifecycle, contact details

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

Institution roles and user role grants

### Courses

**[Courses](/docs/api/courses/courses/list-courses)**

Courses (addressed by id; filter by code)

**[Content Blocks](/docs/api/courses/courses-content-blocks/list-content-blocks)**

Course content blocks

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

Course workbenches

**[User Progress](/docs/api/courses/courses-user-progress/get-user-progress)**

User progress across content blocks

**[Appointments](/docs/api/appointments/appointments/list-appointments)**

Appointments and room bookings

### Academics

**[Course Modules](/docs/api/campus-management/campus-management-modules/list-modules)**

Course modules, versions, and groups

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

Curricula, versions, and nested structure

**[Study Programs](/docs/api/campus-management/campus-management-study-programs/list-study-programs)**

Study programs, versions, cohorts

**[Organization Terms](/docs/api/campus-management/campus-management-organization-terms/list-organization-terms)**

Academic term chronology

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

Cohorts within study programs

### Facilities

**[Rooms](/docs/api/room-management/room-management/list-rooms)**

Rooms, setups, locations, amenities

### Time tracking

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

Sessions, logs, and timestamp templates

### Directory

**[User Groups](/docs/api/users/users-user-groups/list-user-groups)**

Directory user groups and memberships
