---
name: mediux
description: Build apps and scripts on the Mediux API (community artwork for shows, movies, collections and games). Use when writing code that calls api.mediux.io or img.mediux.io, connects Mediux users with OAuth, reads Lists, or applies Mediux Sets with Kometa.
---

# Building on Mediux

Mediux is a community library of artwork for shows, movies, collections and
games. Follow these rules for any code that talks to Mediux. When a rule and
your own habits disagree, the rule wins.

## Read before you write code

- Docs index: [llms.txt](https://docs-preview.mediux.io/llms.txt). All guides in one file: [llms-full.txt](https://docs-preview.mediux.io/llms-full.txt).
- OpenAPI 3.1 document: [openapi.json](https://docs-preview.mediux.io/openapi.json). Generate types or a client from
  it rather than writing response shapes by hand.
- Every docs page has a Markdown copy: add `.md` to its path, such as
  [/api/errors.md](https://docs-preview.mediux.io/api/errors.md).

Check field names and paths against the OpenAPI document. Don't guess them.

## Requests

- Public API: `https://api.mediux.io`, `GET` or `HEAD` only, no account, key or token.
  Paths have no version prefix, trailing slash or query string. From a browser, send
  requests without credentials.
- Protected API (`/account`, `/notifications`, `/relationships`): an OAuth access
  token the user approved, sent as `Authorization: Bearer …`, from a server or native
  app only. See [Authentication](https://docs-preview.mediux.io/api/authentication.md).
- Every JSON response has `data`; lists of things add `meta`. See
  [Responses and errors](https://docs-preview.mediux.io/api/errors.md).
- Profile paths use the username in lower case (`/users/koltom`). Lists and Assets
  use lowercase UUIDs, as do User and Notification `id`s in bodies; titles, Sets,
  Boxsets and Loadouts have numeric Mediux IDs.

## Be light on the API

- Keep each response's `ETag` and send it back as `If-None-Match`. A `304` means
  reuse your copy. See [Caching](https://docs-preview.mediux.io/api/caching.md).
- Never poll titles or Sets for changes. Use the daily
  [activity feeds](https://docs-preview.mediux.io/api/pagination.md#activity-feeds) for what changed, and the
  [indexes](https://docs-preview.mediux.io/api/pagination.md#indexes) (refreshed hourly) to sync a full library.
  Don't probe IDs one by one.
- Keep concurrency low, and run large syncs as background jobs, not on page load.
- On `429`, wait for `Retry-After`; when it's absent, back off for at least
  10 minutes. On `503`, wait for `Retry-After`, then try again.

## Errors

- Check the HTTP status first, then branch on `error.code`, never on the message.
  Codes are listed in the [error catalogue](https://docs-preview.mediux.io/api/errors.md#error-codes).
- Show people a short, plain message. Log `error.requestId` when present, or the
  `cf-ray` header. Never log tokens or request headers.
- If a write's response is lost, read the resource and compare before writing
  again. Never blindly replay a write.

## Images

- Responses give images as `{ id, extension }`, never as URLs. Build URLs as shown in
  [Build image URLs](https://docs-preview.mediux.io/api/guides/image-urls.md): the original at
  `https://img.mediux.io/{area}/original/{id}.{extension}`, or a resized AVIF at
  `https://img.mediux.io/{area}/{size}/{id}.avif`.
- Use the smallest listed size that fits the space (`w300` for grids). Download
  the original only when the user wants the file itself.
- If a size returns `404`, fall back to the next smaller size, then the original.
- Image URLs never change, so cache images for a long time. Store image IDs, not
  URLs, and refresh them from the API: replaced artwork gets a new ID.
- Use `/assets/jpg/` copies only when `images.areas.assets.jpg` in `GET /config` is
  `true`.

## OAuth and users

- Register one app in Account → Apps on mediux.io. Every user connects their own
  account to it; don't register an app per install or deployment.
- Ask only for the permissions you use (`lists:read`, `lists:write`,
  `relationships:read`, `relationships:manage`, `notifications:read`), plus
  `offline_access` if you need a refresh token.
- Use authorization code with S256 PKCE for web and desktop apps, and the device flow
  for CLIs, servers, Docker and TVs. Public clients never ship a client secret.
- Refresh tokens rotate: save the new one before you use it.
- A `401` ends the connection: offer to connect again. A `403`
  `auth.insufficientScope` means the user didn't grant that permission: connect
  again asking for it, or do without.
- Store a user's `id`, not their username. Usernames can change, and a freed name
  can pass to someone else: re-read the current `username` (from the profile or
  `GET /relationships`) before you use it in a path such as `/users/{username}`
  or `/relationships/{username}`.
- Never ask for a Mediux password, and never send Mediux cookies.
- Apps can't publish or change artwork, Sets, Boxsets or Loadouts, delete, clone or
  reorder Lists, choose a List title's images, Like anything or manage accounts. Send users to mediux.io for those, and don't build
  workarounds.

## Show artwork well

- Artwork belongs to its creator. Show `creator.username` wherever you show a
  creator's artwork.
- Keep the artwork's aspect ratio (posters 2:3, backdrops 16:9). Don't stretch or
  crop it to fit.
- Show the `placeholder` size while an image loads, then swap in the real size.
- Respect the artwork's `language` and the user's language choices when picking
  between Sets.
- Write the name as "Mediux".

## Before you ship

- [ ] Types come from the OpenAPI document, not hand-written shapes.
- [ ] Every request reuses `ETag`s, and nothing polls on a timer.
- [ ] `429` and `503` back off as described above.
- [ ] Image URLs use the smallest size that fits, with a fallback.
- [ ] Tokens stay on the server or in the OS keychain, never in web pages or logs.
- [ ] Errors branch on `error.code`.
