API reference

Authored by Claude · Last updated October 8, 2026AI generated documentation written by reading the source code

self-hosted

---

The Media Server's API is described by an OpenAPI specification, generated from the server's source code. There are two copies of it.

Copy	Where	Describes
Published	https://help.cardinalapps.io/openapi/media-server.json	The latest Media Server code, updated with each release of this site
On each server	/api/docs (interactive) and /api/docs-json (raw)	The version that server runs

Use the published copy to plan an app or generate a client. Use a server's own copy to check what that server supports: a server on an older version may not have every endpoint in the published copy.

curl -o media-server.json https://help.cardinalapps.io/openapi/media-server.json

The interactive reference at http://<server>/api/docs can send requests. Authorize it with a personal access token to try endpoints against your own server.

Conventions

• Base path. Every endpoint is under /api/v1.
• IDs. Items are identified by string IDs named after their type, such as musicTrackId and photoId.
• Lists. Paginated list endpoints take take, skip, order, and orderBy, and respond with [items, total]. See Browsing.
• Permissions. Each endpoint's description lists the capabilities it requires. A request from a user without them is refused with 403. See Role-Based Access Control.
• Errors. Refusals have a JSON body with a message, and some carry a machine-readable code. See Authentication for the authentication codes.
• Deleting. No endpoint deletes your media files. Deletes only remove entries from the server's database and files from its own cache.
• Dev endpoints. Endpoints under /api/v1/dev exist for Cardinal's automated tests and respond 404 on a normal server.

Useful starting points

Endpoint	Auth	Purpose
GET /api/v1/instance	None	The server's instance ID and name
GET /api/v1/health	None	Whether the server is up
GET /api/v1/users/current	Required	The user the credential belongs to
GET /api/v1/versions	Required	The server's version

Was this article helpful?