Every response follows the same few rules, and every error carries a stable code you can branch on.
Successful responses
Section titled “Successful responses”Every JSON response puts its result in data. Lists of things add a meta
object with paging or chunk details.
{ "data": { "kind": "show", "id": 1399, "title": "Game of Thrones" }, "meta": {}}- Field names are
camelCase, and so are enum values such asmovieSet. - Instants end in
Atand are ISO 8601 UTC with milliseconds, such as2026-11-14T15:03:02.000Z. Dates without a time, such asreleaseDate, areYYYY-MM-DD. - A reference to another resource is
{ "kind": "...", "id": ... }, plus a few display fields. - Images are
{ "id": "...", "extension": "png" }; see Build image URLs. - YAML routes return text as
application/yaml; charset=utf-8. - Text from TMDB and IGDB, such as titles, overviews, taglines and names, is in English only. There’s no language parameter.
Each endpoint page lists every field of its response.
Titles, People, Networks, Companies, Categories, Sets, Boxsets and Loadouts have
numeric Mediux IDs, such as 1399; a title’s IMDb, TVDB and other IDs are in its
externalIds. Lists and Assets use lowercase UUIDs. User paths take the username
in lower case (/users/koltom; a UUID there is 400 route.invalid), and a user’s
UUID id appears only in response bodies. A malformed ID returns 400; an ID that
doesn’t exist returns 404, or 410 if it was removed.
Browsers
Section titled “Browsers”Any website can call the Public API. Cross-origin GET and HEAD requests work
without credentials, preflight OPTIONS is answered for you, and your code can
read the ETag and Retry-After headers. The Protected API is for servers and
native apps: keep its tokens out of web pages.
Errors
Section titled “Errors”Check the HTTP status first: rate limits and outages from the network edge can
return a body in another format. Then branch on error.code, never on the
message, which can change.
Every error, Public or Protected, has data: null, the code, a short message and
a link to the code’s entry below. Some add details (limits such as maxItems)
and issues (each failing field, with its path):
{ "data": null, "error": { "code": "request.invalid", "message": "The request is invalid", "requestId": "8f0c2a1b3d4e5f60", "docs": "https://docs.mediux.io/api/errors#request-invalid", "issues": [{ "code": "request.tooBig", "path": ["titles"] }] }}Protected errors always carry requestId. Public errors are often served from the
edge cache to many callers, so they leave it out.
Quote requestId, or the cf-ray response header when it’s absent, if you ask
for help. Don’t pass tokens or request headers on in your own app’s errors.
Error codes
Section titled “Error codes”| Code | Status | Meaning |
|---|---|---|
request.invalid | 400 | The request body or a parameter isn't valid; see issues. |
route.invalid | 400 | The path, or an ID in it, isn't valid. |
route.queryNotSupported | 400 | Public paths take no query string. |
auth.required | 401 | No access token was sent. |
auth.invalidToken | 401 | The token is malformed, expired or revoked. Refresh it or connect again. |
auth.insufficientScope | 403 | The user didn't grant the App Permission this route needs. |
auth.forbidden | 403 | The app or the user can't do this, for example on someone else's resource. |
resource.notFound | 404 | Nothing exists at this path. |
request.methodNotAllowed | 405 | The route doesn't accept this method. Public routes take GET and HEAD. |
resource.conflict | 409 | The change conflicts with the resource's current state or a limit; see details. |
resource.gone | 410 | The resource existed but was removed. |
request.lengthRequired | 411 | A request body needs a Content-Length header. |
upload.tooLarge | 413 | The request body is larger than the route accepts. |
upload.unsupportedType | 415 | The request body's media type isn't accepted. |
entity.notInMediux | 422 | The title isn't on Mediux yet. Add it on mediux.io first. |
request.rateLimited | 429 | Too many requests. Wait for Retry-After, or 10 minutes when it's absent. |
service.unavailable | 503 | Mediux is briefly unavailable. Wait for Retry-After. |
OAuth endpoints use the standard OAuth error field instead; see
Authentication.
Business-rule codes
Section titled “Business-rule codes”Protected routes add their own codes, named area.reason:
| Code | Status | Meaning |
|---|---|---|
list.invalidInput | 400 | A List field isn't valid; see issues. |
list.notFound | 404 | No such List for this user: one they don't own, or, to subscribe, one that isn't Public. |
list.itemUnavailable | 404 | A title isn't on Mediux, or an Asset no longer exists. Nothing was added. |
list.itemIneligible | 409 | That item can't go on a List, such as a Boxset or Loadout poster. |
list.kindMismatch | 409 | Wrong route for this kind of List: titles on an Asset List, or Assets on a Media or Game List. |
list.subscriptionInvalid | 409 | Users can't subscribe to their own List. |
list.limit.lists | 409 | The user already owns 100 Lists. |
list.limit.subscriptions | 409 | The user already subscribes to 500 Lists. |
list.limit.images | 409 | The Asset List is full (about 1,000 images). |
list.limit.entities | 409 | The Media or Game List is full (500 titles). |
relationship.self | 422 | Users can't follow or hide themselves. |
Retries
Section titled “Retries”429: wait forRetry-After. A429without it comes from the network edge: back off for at least 10 minutes.503: wait forRetry-After, then try again.- A write whose response was lost: it may or may not have happened. Read the resource and compare before you write again.