Fuxam API v4

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.
• Read and update academic structure — courses, modules, curricula, study programs, and terms — in line with FuxamCMS and FuxamLMS.
• 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.

Key concepts

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

Authentication

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

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.

Response envelope

Single resource:

{
  "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):

{
  "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.

Cursor pagination

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

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

{
  "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.

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.

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

Optimistic concurrency

Single-resource GETs 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.

In this section

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

Where to start

1. Follow Getting started to create credentials and call GET /users.
2. Read Authentication before storing secrets in production.
3. Use Pagination and filtering when you need to walk large collections.
4. Apply Errors and idempotency before any create or update automation.
5. Copy a pattern from 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

Courses

Academics

Facilities

Directory