Backend REST API

The Modula backend exposes its capabilities as a REST API. It is a Hono application mounted under /api, organized into independent route packages — one per category — so each group of endpoints can be enabled and configured per deployment.

This section documents the API surface category by category. If you are self-hosting, start with System requirements.

Base URL

Every endpoint lives under the /api base path:

https://your-host.example/api/<category>/...

Authentication

Most endpoints are authenticated through the current session (cookie-based). A request without a valid session receives 401 Unauthorized with a JSON body of the shape { "message": "Unauthorized" }.

• Fine-grained authorization (who can read or edit a given resource) is delegated to the backend’s repository layer, not enforced in the route itself.
• Content endpoints additionally accept an LTI platform context (lti_platform_id, id_token) so modules can be listed on behalf of an LTI platform.
• The AI chat endpoint can optionally run in an anonymous “playground” mode when the deployment enables it.

Conventions

• Format — requests and responses are JSON unless noted (uploads are binary; downloads are application/zip).
• Errors — failures return an appropriate HTTP status with a { "message": string } body.
• Pagination — list endpoints accept from (offset) and size (page length, capped per endpoint) query parameters.
• Filtering — filter parameters use bracket syntax, e.g. filter[published]=true, filter[accept]=image/*.

Categories

Health check

A minimal, always-mounted liveness endpoint is available for load balancers and uptime probes:

• GET /api/health — returns 200 OK when the server is up.