# Mediux API > Read Mediux artwork with no sign-up, or act for a user with OAuth. Community artwork for shows, movies, collections and games, as JSON. The Mediux API gives your app the artwork, Sets, creators and Lists in the Mediux library. Reading public artwork needs no account, key or token: send a `GET` and you're done. To act for a user, such as editing their Lists, use OAuth. - [Get started](https://docs-preview.mediux.io/api/quickstart.md) - [Browse endpoints](https://docs-preview.mediux.io/api/reference.md) ## Two APIs, one host Everything lives at `https://api.mediux.io`. | | Public API | Protected API | | -------------- | --------------------------------------------- | ------------------------------------------------ | | Use it to | Read titles, Sets, creators, Lists and feeds | Read and edit one user's Lists, follows and more | | Authentication | None | OAuth access token the user approved | | Methods | `GET` and `HEAD` | `GET`, `POST`, `PATCH`, `PUT` and `DELETE` | | Paths | `/shows/1399`, `/movie-set/{id}`, … | `/account`, `/notifications`, `/relationships` | | Runs from | Anywhere, including browsers | Your server or a native app | Artwork itself comes from `https://img.mediux.io`; responses give you image IDs and you [build the URLs](https://docs-preview.mediux.io/api/guides/image-urls.md). ## Start here - [Get started](https://docs-preview.mediux.io/api/quickstart.md): Make your first request in a minute. - [Authentication](https://docs-preview.mediux.io/api/authentication.md): Register an app and connect a user with OAuth. - [Responses and errors](https://docs-preview.mediux.io/api/errors.md): The response envelope, IDs and every error code. - [Indexes, feeds and pages](https://docs-preview.mediux.io/api/pagination.md): List everything of one type and follow new artwork. ## Guides - [Build image URLs](https://docs-preview.mediux.io/api/guides/image-urls.md): Turn an image ID into a full-size or resized URL. - [Use Set YAML with Kometa](https://docs-preview.mediux.io/api/guides/kometa.md): Apply a whole Set to your Plex library. - [Read and edit Lists](https://docs-preview.mediux.io/api/guides/lists.md): Read a user's Lists, and create and fill them. - [Draw the Ambient Mesh](https://docs-preview.mediux.io/api/guides/ambient-mesh.md): Paint a title's colour wash in plain CSS. --- # Get started > Make your first request in a minute, with no account or key. Reading public artwork needs no account, key or token. ## Fetch a Show ```sh curl https://api.mediux.io/shows/1399 ``` The Show is under `data`. The [Show reference](https://docs-preview.mediux.io/api/reference/shows/retrieve.md) has a full example response. ## From JavaScript ```js const response = await fetch("https://api.mediux.io/shows/1399", { credentials: "omit", }); if (!response.ok) { const { error } = await response.json().catch(() => ({})); throw new Error(error?.code ?? `HTTP ${response.status}`); } const { data } = await response.json(); console.log(data.title); ``` This works in a browser too. Use `GET` or `HEAD`, leave credentials out, and don't add query parameters: public paths take none. ## Show its poster Images come back as an ID and an extension. Add them to the image host: ```js const { id, extension } = data.metadataImages.poster; const poster = `https://img.mediux.io/metadata/original/${id}.${extension}`; ``` [Build image URLs](https://docs-preview.mediux.io/api/guides/image-urls.md) covers resized versions and community artwork. ## Next steps - Browse the [public endpoints](https://docs-preview.mediux.io/api/reference.md) for titles, Sets, creators, Lists, feeds and YAML exports. - Learn the [response format and error codes](https://docs-preview.mediux.io/api/errors.md). - To act for a user, [connect your app with OAuth](https://docs-preview.mediux.io/api/authentication.md). --- # Authentication > Register your app once, then connect users with browser sign-in or the device flow. Public reads need no authentication. The Protected API (`/account`, `/notifications` and `/relationships`) acts for one Mediux user and needs an access token that user approved. Mediux uses standard OAuth, so any OAuth library works. ## The short version 1. [Register your app](#register-your-app) once and copy its client ID. 2. Pick the recipe that fits where your app runs: | Your app | Recipe | | ----------------------------------------------------------------- | --------------------------------------------------- | | A website or service you host | [Browser sign-in](#browser-sign-in) | | A CLI or desktop tool on the same computer as the browser | [Browser sign-in](#browser-sign-in), on `localhost` | | A tool on a server, in Docker, on a TV, or a self-hosted web page | [Device flow](#device-flow) | | Your own script | [Device flow](#device-flow) | 3. Send the access token as `Authorization: Bearer ACCESS_TOKEN`. Run the flow and your API calls from your server or app, not from a web page's JavaScript. Keep tokens out of source control and logs. ## Register your app Register at [Account → Apps](https://mediux.io/account/apps/) with a verified email. You do this once: everyone who uses your app connects their own account to it. - **Name, description and homepage** are shown to people when they connect. - **Callback URLs** are for browser sign-in. Use an HTTPS URL for a website, or a `localhost` / `127.0.0.1` URL (or a reverse-domain app URL such as `com.example.app:/callback`) for a tool on the user's own computer. Register the exact URL, including the port. - **Enable device flow** for tools that can't receive a callback. An app can use both. Mediux gives you a **client ID**, which isn't secret: you can ship it in your code, including open source. If every callback URL is an HTTPS website and device flow is off, you also get a **client secret** to keep on your server; you can regenerate it at any time without disconnecting anyone. Forks and redistributions of an open-source tool must register their own app. The issuer is `https://mediux.io/api/auth`; its [metadata document](https://mediux.io/api/auth/.well-known/oauth-authorization-server) lists every endpoint. ## Browser sign-in Send the user's browser to Mediux, then exchange the code it brings back. 1. Create a random `state` and a PKCE verifier, and keep both for the callback. 2. Redirect the browser to the authorization endpoint: ```text https://mediux.io/api/auth/oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fapp.example%2Fcallback&resource=https%3A%2F%2Fapi.mediux.io&scope=lists%3Aread%20offline_access&code_challenge=BASE64URL_SHA256_OF_VERIFIER&code_challenge_method=S256&state=STATE ``` 3. The user signs in and approves. At your callback, check `state` matches and there is no `error`, then exchange the code: ```sh curl --request POST \ https://api.mediux.io/api/auth/oauth2/token \ --user "$CLIENT_ID:$CLIENT_SECRET" \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode "client_id=$CLIENT_ID" \ --data-urlencode "code=$CODE" \ --data-urlencode "redirect_uri=$REDIRECT_URI" \ --data-urlencode "code_verifier=$CODE_VERIFIER" \ --data-urlencode 'resource=https://api.mediux.io' ``` Apps without a secret leave out the `--user` line. **A local CLI or desktop tool** does the same with a `localhost` callback: start a small listener on the registered port, open the authorization URL in the user's browser, and read the code when the browser comes back. The user just approves; there's nothing to type. ## Device flow For tools whose browser is somewhere else: a server, Docker, a TV, or a self-hosted web page at an address like `http://192.168.1.20:8080`. 1. Ask for a code: ```sh curl --request POST \ https://api.mediux.io/api/auth/device/code \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode "client_id=$CLIENT_ID" \ --data-urlencode 'scope=lists:read offline_access' \ --data-urlencode 'resource=https://api.mediux.io' ``` 2. Show the user where to go. The response has `verification_uri` (`https://mediux.io/link`), `user_code` (such as `BCDFGHJK`; show it as `BCDF-GHJK`), and `verification_uri_complete`, which carries the code: - On a screen or in a log, show _Go to mediux.io/link and enter BCDF-GHJK_, plus `verification_uri_complete` as a link or QR code. - In a self-hosted web page, open `verification_uri_complete` in a new tab for them, so they don't type anything. Codes last ten minutes and work once. 3. While the user approves, poll from your server every `interval` seconds: ```sh curl --request POST \ https://api.mediux.io/api/auth/oauth2/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \ --data-urlencode "client_id=$CLIENT_ID" \ --data-urlencode "device_code=$DEVICE_CODE" ``` Keep polling on `authorization_pending`, wait longer on `slow_down`, and stop on `access_denied` or `expired_token`. Success returns your tokens. ### Example: your own script Register an app with device flow on, then: ```js const API = "https://api.mediux.io"; const CLIENT_ID = "YOUR_CLIENT_ID"; const form = (body) => ({ method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams(body), }); const code = await ( await fetch( `${API}/api/auth/device/code`, form({ client_id: CLIENT_ID, scope: "lists:read offline_access", resource: `${API}`, }), ) ).json(); console.log(`Open ${code.verification_uri_complete}`); let tokens; while (!tokens) { await new Promise((done) => setTimeout(done, code.interval * 1000)); const result = await ( await fetch( `${API}/api/auth/oauth2/token`, form({ grant_type: "urn:ietf:params:oauth:grant-type:device_code", client_id: CLIENT_ID, device_code: code.device_code, }), ) ).json(); if (result.access_token) tokens = result; else if (result.error !== "authorization_pending") throw new Error(result.error); } const me = await fetch(`${API}/account`, { headers: { Authorization: `Bearer ${tokens.access_token}` }, }); console.log(await me.json()); ``` ## Permissions Ask only for what your app needs. Each scope is independent: | Scope | Access | | ---------------------- | --------------------------------------------------------------------------- | | `relationships:read` | Read follows and hides. | | `relationships:manage` | Read and manage follows and hides (includes read). | | `lists:read` | Read the user's Lists, including private and subscribed Lists. | | `lists:write` | Create and edit Lists, add and remove items, and subscribe (includes read). | | `notifications:read` | Read the user's notifications and mark them read. | Add `offline_access` to get a refresh token. Apps can't upload or change artwork, Sets, Boxsets or Loadouts, delete Lists, change Likes or manage the account: owners do those on mediux.io. Apps can unfollow and unhide. Any token can call [`GET /account`](https://docs-preview.mediux.io/api/reference/account-identity/get.md) for the user's ID and username. The user sees your app's name, developer and permissions, a note that Mediux hasn't reviewed the app, and a warning on permissions with lasting effects. Check the `scope` in the token response: it lists what the user approved. To ask for more later, connect again. ## Tokens - Access tokens last one hour. - Refresh tokens rotate: each refresh returns a new one, which you save before using. A connection lasts until the user disconnects it, or until it goes 90 days without a refresh. - Two refreshes a few seconds apart get the same result. Reusing an old refresh token later revokes the connection. ```sh curl --request POST \ https://api.mediux.io/api/auth/oauth2/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode "client_id=$CLIENT_ID" \ --data-urlencode "refresh_token=$REFRESH_TOKEN" ``` To disconnect from your side, revoke the refresh token at `/api/auth/oauth2/revoke` with `token` and `token_type_hint=refresh_token`. Apps with a secret add `--user "$CLIENT_ID:$CLIENT_SECRET"` to token and revoke calls. ## When a connection ends People can disconnect your app in Account → Apps, and Mediux can disable an app that misuses the API. Either way, refreshes and writes stop straight away and reads stop within 60 seconds. Treat a `401` or `403` as the end of the connection and offer to connect again. ## Endpoints | Purpose | URL | | --------------------------------------- | ------------------------------------------------------------------- | | Metadata | `https://mediux.io/api/auth/.well-known/oauth-authorization-server` | | Browser sign-in | `https://mediux.io/api/auth/oauth2/authorize` | | Device code | `https://api.mediux.io/api/auth/device/code` | | Code entry for people | `https://mediux.io/link` | | Tokens (exchange, refresh, device poll) | `https://api.mediux.io/api/auth/oauth2/token` | | Revoke | `https://api.mediux.io/api/auth/oauth2/revoke` | --- # Build with AI > Give your AI coding agent the Mediux docs and integration rules, so what it builds follows them. AI coding agents build better integrations when they read the right docs first. Mediux publishes everything an agent needs as plain text, free to fetch: | File | What it is | | ------------------------------------- | ------------------------------------------------------------------------ | | [`SKILL.md`](https://docs-preview.mediux.io/skills/mediux/SKILL.md) | The Mediux Agent Skill: the rules every integration follows | | [`llms.txt`](https://docs-preview.mediux.io/llms.txt) | An index of every docs page, linked as Markdown | | [`llms-full.txt`](https://docs-preview.mediux.io/llms-full.txt) | Every guide and concept page in one file | | [`openapi.json`](https://docs-preview.mediux.io/openapi.json) | The OpenAPI 3.1 document, for types and generated clients | | `.md` | Any docs page as Markdown: add `.md` to its path, as in `/api/errors.md` | Each page also has **Copy as Markdown** and **View as Markdown** under its title. ## Add the skill The skill tells your agent how to call the API, cache responses, build image URLs, handle errors and connect users, and what apps can't do. In Claude Code, save it as a project skill: ```sh mkdir -p .claude/skills/mediux curl -o .claude/skills/mediux/SKILL.md https://docs.mediux.io/skills/mediux/SKILL.md ``` Other agents that support Agent Skills take the same file in their skills folder. Download it again now and then to pick up changes. ## Or add it to AGENTS.md For any agent that reads an `AGENTS.md` (or a similar rules file), paste this in: ```md ## Mediux This project uses the Mediux API. Before writing Mediux code, read https://docs.mediux.io/skills/mediux/SKILL.md and follow its rules. Look up endpoints in https://docs.mediux.io/llms.txt and https://docs.mediux.io/openapi.json; don't guess paths or field names. ``` ## Starter prompt ```text Build using the Mediux API. First read https://docs.mediux.io/skills/mediux/SKILL.md and https://docs.mediux.io/llms.txt, then the pages you need. Generate types from https://docs.mediux.io/openapi.json. Follow the skill's rules on caching, image URLs, errors and OAuth, and finish with its "Before you ship" checklist. ``` --- # Responses and errors > The response envelope, IDs, browser access and every error code. Every response follows the same few rules, and every error carries a stable code you can branch on. ## Successful responses Every JSON response puts its result in `data`. Lists of things add a `meta` object with paging or chunk details. ```json { "data": { "kind": "show", "id": 1399, "title": "Game of Thrones" }, "meta": {} } ``` - Field names are `camelCase`, and so are enum values such as `movieSet`. - Instants end in `At` and are ISO 8601 UTC with milliseconds, such as `2026-11-14T15:03:02.000Z`. Dates without a time, such as `releaseDate`, are `YYYY-MM-DD`. - A reference to another resource is `{ "kind": "...", "id": ... }`, plus a few display fields. - Images are `{ "id": "...", "extension": "png" }`; see [Build image URLs](https://docs-preview.mediux.io/api/guides/image-urls.md). - 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. ## IDs 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 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 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`): ```json { "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 | 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](https://docs-preview.mediux.io/api/authentication.md). ### 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 - **`429`:** wait for `Retry-After`. A `429` without it comes from the network edge: back off for at least 10 minutes. - **`503`:** wait for `Retry-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. --- # Indexes, feeds and pages > List everything of one type with indexes, follow new artwork with feeds, and page through a creator's work. Public routes don't take query strings, so there are three fixed ways through a lot of results: | You want | Use | | --------------------------------- | --------------------------------- | | Everything of one type | [Indexes](#indexes) | | What's new or changed | [Activity feeds](#activity-feeds) | | One creator's Sets, Assets, Lists | [Creator pages](#creator-pages) | ## Indexes Each title type has an index (`/shows`, `/movies`, …), as do creators (`/users`) and Public Lists (`/lists`). An index is a manifest of chunks, each with its `path`, `itemCount` and when it last changed: ```json { "data": [ { "chunk": 0, "path": "/shows/chunks/0", "itemCount": 1111, "updatedAt": "2026-11-15T07:55:55.544Z" } ], "meta": { "scheme": "idRange", "chunkSize": 10000, "chunkCount": 33, "totalItems": 7437 } } ``` Fetch the manifest, then the chunks you need. - **`idRange`** (titles and other numeric IDs): chunk `n` holds IDs from `n × chunkSize` up to the next boundary, in ascending order. `chunkSize` differs by type. - **`uuidPrefix`** (creators and Public Lists): a chunk holds the IDs that start with the same two hexadecimal digits. A chunk with no entries returns `404`. Indexes refresh hourly; send each chunk's `ETag` back as `If-None-Match` and an unchanged chunk answers `304`. ## Activity feeds Feeds list the Sets changed on one UTC day, newest first: `/feeds/media-sets` and `/feeds/game-sets` for today, or add a date (`/feeds/media-sets/2026-11-14`) for an earlier day. Follow `meta.previous` and `meta.next` to move between days. Today and the 13 days before it are kept; any other day is `404`. A deleted or hidden Set simply drops out, so reconcile a full library through the indexes. Each feed also has an Atom version (`/feeds/media-sets.atom`) for feed readers. ## Creator pages A creator's profile, `/users/{username}` (the username in lower case; a spelling with capitals redirects there), counts their items of each kind in `content`. Read the items from `/users/{username}/{kind}/pages/{page}`, where `kind` is `sets`, `boxsets`, `loadouts`, `assets` or `lists` (`sets` holds show, movie, collection and game Sets): - pages hold up to 50 items, most recently updated first; - `meta` gives `page`, `pageSize`, `totalItems`, `totalPages`, and the `next` and `previous` paths (or `null`); - page 1 of an empty kind is an empty list, and a page past the end is `404`. ## Protected lists Protected routes that list things, such as `/account/lists` and `/notifications`, page with a cursor instead: pass `meta.nextCursor` back as `?after=` until it's `null`. `?limit=` sets the page size. --- # Caching > Reuse responses with ETags, and know how fresh each kind of response is. Public responses are cached at the edge, so most requests are fast. You can cache them too. ## Revalidate with ETags Keep each response's `ETag` and send it back as `If-None-Match`, exactly as you received it (it may be weak, `W/"…"`). An unchanged response answers `304 Not Modified` with no body: reuse your copy. | Response | Browser `Cache-Control` | | ----------------------------------------------------- | ------------------------------------- | | Titles, Sets, Boxsets, Loadouts, Assets, YAML | `public, no-cache` | | Creator profiles and pages, Lists, `/config` | `public, no-cache` | | Index manifests and chunks, activity feeds | `public, no-cache` | | Images on `img.mediux.io` | `public, max-age=31536000, immutable` | | Errors and `308` redirects | `no-store` | | Protected API | `private, no-store` | `public, no-cache` means you may keep the response but must revalidate it before reuse. No response is served stale while revalidating. ## How fresh things are - **Changes to titles, Sets, Assets, Lists and profiles** show up within seconds. - **Indexes** and **List subscriber counts** refresh hourly. - **Activity feeds** can be up to an hour behind. - **Privacy changes**, such as a List made private or an account deleted, take effect straight away. - **Images never change** at a given URL: replaced artwork gets a new ID. That's why images can be cached for a year. Don't cache Protected API responses in a shared cache: they belong to one user. --- # Build image URLs > Turn an image ID from any response into a full-size, resized or JPG image URL. Responses never contain image URLs. Each image is an ID and the original's file extension, and you build the URL you need on `https://img.mediux.io`: ```json "poster": { "id": "6d5b60e2-ad28-4e03-8dcf-dddbcbdec4fc", "extension": "png" } ``` ## Pick the area The first part of the path says where the image comes from: | Area | Holds | Found in | | ---------- | --------------------------------------------------- | ----------------------------------------- | | `assets` | Community artwork | Sets, Assets, Lists and creator pages | | `metadata` | Provider images (TMDB, IGDB) that identify a title | `metadataImages` on titles and People | | `users` | Creator avatars and profile backdrops | Creator profiles | ## Build the URL | You want | URL | | --------------------------- | ------------------------------------------------------ | | The original file | `https://img.mediux.io/{area}/original/{id}.{extension}` | | A resized AVIF | `https://img.mediux.io/{area}/{size}/{id}.avif` | | A JPG copy (community art) | `https://img.mediux.io/assets/jpg/{id}.jpg` | | An ICO (Game Icons) | `https://img.mediux.io/assets/ico/{id}.ico` | ```js const host = "https://img.mediux.io"; const original = (area, { id, extension }) => `${host}/${area}/original/${id}.${extension}`; const resized = (area, { id }, size) => `${host}/${area}/${size}/${id}.avif`; // A Set's poster as a grid thumbnail, and its full-size file. const thumb = resized("assets", set.movie.poster, "w300"); const full = original("assets", set.movie.poster); ``` `placeholder` is a tiny blurred AVIF to show while the real image loads. ## File types Resized images are always AVIF, JPG copies are JPEG and Game Icons also come as ICO. An original keeps its own type, given by `extension`: | `extension` | Media type | | ------------- | -------------------------- | | `avif` | `image/avif` | | `jpg`, `jpeg` | `image/jpeg` | | `png` | `image/png` | | `webp` | `image/webp` | | `svg` | `image/svg+xml` | | `ico` | `image/vnd.microsoft.icon` | ## Sizes Each slot has its own sizes, listed below and in [`GET /config`](https://docs-preview.mediux.io/api/reference/reference/retrieve-config.md) at runtime. A raster image only has the sizes up to its own width: if a size returns `404`, use the next smaller one, then the original. An SVG has every size. ### Community artwork (`assets`) | Slot | Sizes | | ---- | ----- | | `poster` | `placeholder`, `w300` | | `backdrop` | `placeholder`, `w300`, `w1920` | | `logo` | `placeholder`, `w300` | | `squareArt` | `placeholder`, `w300` | | `titlecard` | `placeholder`, `w300` | | `thumb` | `placeholder`, `w300` | | `cover` | `placeholder`, `w300` | | `hero` | `placeholder`, `w300`, `w1920` | | `wideCover` | `placeholder`, `w300` | | `background` | `placeholder`, `w300`, `w1920` | | `squareCover` | `placeholder`, `w300` | | `icon` | `placeholder`, `w300`, `ico` | JPG copies suit tools that can't read AVIF, such as some media servers. Check `images.areas.assets.jpg` in `/config` before you use them: while it's `false`, use the original instead. Logos, Icons and SVG originals have no JPG copy. A JPG copy fits inside the box `images.areas.assets.jpgFits` gives for its slot, such as 1000 × 1500 for a poster, and is never enlarged. Where `crop` is `true` (Game launcher art), a file with another shape is centre-cropped to the box's shape. ### Provider images (`metadata`) | Slot | Sizes | | ---- | ----- | | `backdrop` | `placeholder`, `w300`, `w780`, `w1280`, `w1920`, `w3840` | | `logo` | `w300`, `w1280` | | `poster` | `placeholder`, `w300`, `w780` | | `profile` | `placeholder`, `w300`, `w780` | ### Creator images (`users`) | Slot | Sizes | | ---- | ----- | | `avatar` | `placeholder`, `w92`, `w300` | | `backdrop` | `placeholder`, `w300`, `w1920` | ## Keep URLs fresh An image URL always shows the same file, so browsers and your own cache can keep it for a year. When a creator replaces artwork, the new file gets a new ID and the old URL may stop working. Store IDs from the API rather than URLs you built long ago, and read them again when you refresh your data. --- # Use Set YAML with Kometa > Apply a show, movie or collection Set's artwork to your Plex library with Kometa. Every show, movie and collection Set has a YAML document that [Kometa](https://kometa.wiki/) reads to apply the Set's artwork. No account or key is needed. ## Get the URL On mediux.io, open the Set and find **YAML export**: **Open published YAML** gives its URL, and **Copy YAML** or **Download YAML** give a snapshot. The URL follows the Set's type and ID: | Set | YAML | Always the original files | | -------------- | --------------------------------------- | ------------------------------------------------ | | Show Set | `https://api.mediux.io/show-set/{id}.yaml` | `https://api.mediux.io/show-set/{id}.original.yaml` | | Movie Set | `https://api.mediux.io/movie-set/{id}.yaml` | `https://api.mediux.io/movie-set/{id}.original.yaml` | | Collection Set | `https://api.mediux.io/collection-set/{id}.yaml` | `https://api.mediux.io/collection-set/{id}.original.yaml` | The URL always reflects the Set's current artwork. A snapshot stays as you saved it, and links to the images rather than containing them. ## Add it to Kometa In your `config.yml`, add the URL under `metadata_files` for the matching library: ```yaml libraries: Movies: metadata_files: - url: https://api.mediux.io/movie-set/321.yaml ``` For a saved snapshot, point at the file instead: ```yaml - file: config/metadata/mediux-movie-set-321.yaml ``` Kometa's [file-block guide](https://kometa.wiki/en/latest/config/files/) covers both. ## How titles match - **Movies** match by TMDB ID. - **Shows** match by TVDB ID, falling back to IMDb. Seasons and episodes follow TMDB numbering, so pick the TMDB episode order in your library before applying titlecards. - **Collection Sets** go in a movie library. They apply artwork to the collection's movies, not to a collection itself. ## What's included Show and movie posters, backdrops, logos and square art; season posters and backdrops; and episode titlecards. Thumbs aren't included, and game Sets have no YAML. YAML only changes artwork, never other library metadata. The document is cached like other Set responses: revalidate it with its `ETag` (see [Caching](https://docs-preview.mediux.io/api/caching.md)). --- # Read and edit Lists > Read a user's Lists, check which hold a title, and create, edit and fill Lists for them. The List routes act on the connected user's Lists under `https://api.mediux.io/account/lists`. Reading needs the `lists:read` [permission](https://docs-preview.mediux.io/api/authentication.md#permissions); changing anything needs `lists:write`, which includes read. Every request sends `Authorization: Bearer ACCESS_TOKEN`. Apps never delete, clone or reorder a List, choose a title's images, add a whole Set or handle Set suggestions, and can't Like anything: the owner does those on mediux.io. Anyone's **Public** Lists are also readable without a token through the [public List endpoints](https://docs-preview.mediux.io/api/reference/lists.md). ## Kinds of List | `kind` | Holds | Limit | | ----------- | ---------------------------------------------------------------------- | ------------ | | `assetList` | Individual Assets (community images) | 1,000 images | | `mediaList` | Shows, Movies and Collections, each with one chosen image per position | 500 titles | | `gameList` | Games, each with one chosen image per position | 500 titles | A user can own 100 Lists and subscribe to 500. List IDs are UUIDs. A title is `{ "kind": "show" | "movie" | "collection" | "game", "id": 1399 }`, with its Mediux ID. ## Read | Route | Returns | | ------------------------------------------------ | ------------------------------------------------------------- | | `GET /account/lists` | The user's own Lists, then their subscriptions, cursor-paged | | `GET /account/lists/membership?entity=movie:603` | Which of their Media and Game Lists hold a title | | `GET /account/lists/{list}` | One List, private ones included, in the public List shape | | `GET /account/lists/{list}/titles/{family}/{id}` | One title in a List; `family` is `shows`, `movies`, `collections` or `games` | Page `GET /account/lists` with `?after=` and `?limit=`; see [protected lists](https://docs-preview.mediux.io/api/pagination.md#protected-lists). Other reads take no query string. Each route has a full page in the [Your Lists reference](https://docs-preview.mediux.io/api/reference/account-lists/list.md). ## Create and edit ```sh curl --request POST https://api.mediux.io/account/lists \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H 'Content-Type: application/json' \ --data '{"name": "Watching", "kind": "mediaList", "isPublic": false}' ``` | Route | Body | | --------------------------------------- | -------------------------------------------------------- | | `POST /account/lists` | `name` (up to 80 characters), `kind`, optional `description` (up to 500) and `isPublic` (default `false`) | | `PATCH /account/lists/{list}` | Any of `name`, `description` and `isPublic` | | `POST /account/lists/{list}/titles` | `{ "titles": [...] }`: add up to 500 titles (16 KiB body) to a Media or Game List | | `POST /account/lists/{list}/titles/remove` | `{ "titles": [...] }`: remove them | | `POST /account/lists/{list}/assets` | `{ "items": [{ "kind": "asset", "id": "..." }] }`: add up to 100 Assets to an Asset List | | `POST /account/lists/{list}/assets/remove` | The same shape: remove them | | `PUT /account/lists/{list}/subscription` | `{ "subscribed": true }` to follow someone else's Public List, `false` to leave it | A title added to a Media or Game List starts with no image chosen; the owner picks images on mediux.io. If any title in the request isn't on Mediux yet, the whole request is refused with `404` `list.itemUnavailable` and nothing is added. Add and remove requests answer only the change: `{ "added": 2, "existing": 1 }` or `{ "removed": 2 }`. A subscription answers `{ "subscribed", "changed", "subscriberCount" }`, and create and edit answer the List, whose `itemCount` and `subscriberCount` give the current totals. Making a List public or private takes effect straight away. Other changes to a Public List can take up to an hour to show on the public endpoints. ## Errors Errors use the [shared format](https://docs-preview.mediux.io/api/errors.md#errors). Besides the shared codes, List routes return: | Code | Status | Meaning | | -------------------------- | ------ | -------------------------------------------------- | | `list.invalidInput` | `400` | A field isn't valid; see `issues` | | `list.notFound` | `404` | No List with this ID that the user owns or follows | | `list.itemUnavailable` | `404` | The title or Asset no longer exists | | `list.itemIneligible` | `409` | That item can't go in this List | | `list.kindMismatch` | `409` | Wrong route for this kind of List | | `list.subscriptionInvalid` | `409` | You can't subscribe to your own List; a private one is `list.notFound` | | `list.limit.lists` | `409` | The user already has 100 Lists | | `list.limit.subscriptions` | `409` | The user already follows 500 Lists | | `list.limit.images` | `409` | The Asset List is full | | `list.limit.entities` | `409` | The Media or Game List is full | Every List response is `Cache-Control: private, no-store`. --- # Draw the Ambient Mesh > Paint a title's Ambient Mesh in CSS from the colours in its detail response. Show, Movie, Collection and Game details include an `ambientMesh`: a soft colour wash taken from the title's Backdrop. It sits inside that image, at `metadataImages.backdrop.ambientMesh` (`metadataImages.background.ambientMesh` for a Game), because it is derived from that image. The Mediux website paints it behind each title page. You can paint the same wash in your app with plain CSS: no image request, no canvas and no library. `ambientMesh` is `null` when the Backdrop has no mesh yet, and `backdrop` itself is `null` when the title has no hosted Backdrop, so use optional chaining and keep a plain background as the fallback. ## What the response holds ```json "backdrop": { "id": "…", "extension": "jpg", "ambientMesh": { "base": "#015f66", "grid": [ ["#2f4832", "#334c32", "#345135", "#32553b", "#31593d", "#325b3e", "#375c3b", "#3c5b38"], ["#30472f", "#354b30", "#365033", "#355439", "#33593d", "#315c40", "#325d41", "#325e40"], ["#31452d", "#34482d", "#374d30", "#375335", "#35573a", "#315c40", "#2d5e44", "#295f48"], ["#2c412a", "#2f4329", "#32472d", "#334d32", "#31553a", "#2d5b42", "#275e49", "#1f604f"], ["#253e29", "#283e28", "#2a412a", "#2b4830", "#2a5039", "#265a45", "#205e4e", "#196054"] ] }, "accent": { "color": "#68867b" } } ``` - `base` is the dominant colour. Paint it underneath everything. - `grid` is 5 rows of 8 colours, top row first and left to right in each row. Each colour is the wash at the centre of its cell, laid over the Backdrop's 16:9 frame. - `accent` sits beside `ambientMesh` and is a single colour picked from the same Backdrop, for buttons, links or highlights. ## How it is drawn Each grid row becomes one horizontal gradient with a colour stop at every column centre. The five rows are stacked, and each row below the first fades in from the previous row's centre to its own. That blends the colours smoothly in both directions, which is how the website renders it. | Column | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | | ------ | ----- | ------ | ------ | ------ | ------ | ------ | ------ | ------ | | Stop | 6.25% | 18.75% | 31.25% | 43.75% | 56.25% | 68.75% | 81.25% | 93.75% | | Row | 1 | 2 | 3 | 4 | 5 | | ------ | --- | --- | --- | --- | --- | | Centre | 10% | 30% | 50% | 70% | 90% | ## Draw it from a response Give the element five empty children, one per row: ```html
``` ```css .mesh { position: relative; overflow: hidden; aspect-ratio: 16 / 9; background-color: #111; /* fallback when ambientMesh is null */ } .mesh > * { position: absolute; inset: 0; } ``` Then set the colours from the response: ```js const centre = (index, count) => `${((index + 0.5) / count) * 100}%`; function drawAmbientMesh(element, mesh) { if (!mesh) return; element.style.backgroundColor = mesh.base; mesh.grid.forEach((row, r) => { const layer = element.children[r]; const stops = row.map((colour, c) => `${colour} ${centre(c, row.length)}`); layer.style.backgroundImage = `linear-gradient(90deg, ${stops.join(", ")})`; if (r > 0) { const from = centre(r - 1, mesh.grid.length); const to = centre(r, mesh.grid.length); layer.style.maskImage = `linear-gradient(transparent ${from}, #000 ${to})`; } }); } const show = await fetch("https://api.mediux.io/shows/1396").then((r) => r.json(), ); drawAmbientMesh( document.querySelector(".mesh"), show.metadataImages.backdrop?.ambientMesh, ); ``` ## The same mesh as static CSS For a fixed page, or to check your output against a known result, here is the response above (Breaking Bad) as plain CSS. It uses the HTML and the `.mesh` rules from the previous section. ```css .mesh { background-color: #015f66; } .mesh > :nth-child(1) { background-image: linear-gradient( 90deg, #2f4832 6.25%, #334c32 18.75%, #345135 31.25%, #32553b 43.75%, #31593d 56.25%, #325b3e 68.75%, #375c3b 81.25%, #3c5b38 93.75% ); } .mesh > :nth-child(2) { background-image: linear-gradient( 90deg, #30472f 6.25%, #354b30 18.75%, #365033 31.25%, #355439 43.75%, #33593d 56.25%, #315c40 68.75%, #325d41 81.25%, #325e40 93.75% ); mask-image: linear-gradient(transparent 10%, #000 30%); } .mesh > :nth-child(3) { background-image: linear-gradient( 90deg, #31452d 6.25%, #34482d 18.75%, #374d30 31.25%, #375335 43.75%, #35573a 56.25%, #315c40 68.75%, #2d5e44 81.25%, #295f48 93.75% ); mask-image: linear-gradient(transparent 30%, #000 50%); } .mesh > :nth-child(4) { background-image: linear-gradient( 90deg, #2c412a 6.25%, #2f4329 18.75%, #32472d 31.25%, #334d32 43.75%, #31553a 56.25%, #2d5b42 68.75%, #275e49 81.25%, #1f604f 93.75% ); mask-image: linear-gradient(transparent 50%, #000 70%); } .mesh > :nth-child(5) { background-image: linear-gradient( 90deg, #253e29 6.25%, #283e28 18.75%, #2a412a 31.25%, #2b4830 43.75%, #2a5039 56.25%, #265a45 68.75%, #205e4e 81.25%, #196054 93.75% ); mask-image: linear-gradient(transparent 70%, #000 90%); } ``` ## Fill a different shape The grid maps onto a 16:9 frame. To fill a wider or taller area without stretching the wash, size every row like `background-size: cover` and centre it. Set the same size on the mask: ```css .mesh { container-type: size; } .mesh > * { --frame-width: max(100cqw, calc(100cqh * 16 / 9)); --frame: var(--frame-width) calc(var(--frame-width) * 9 / 16); background-size: var(--frame); background-position: center; background-repeat: no-repeat; mask-size: var(--frame); mask-position: center; mask-repeat: no-repeat; } ``` Unprefixed `mask-image` works in current Chrome, Edge, Firefox and Safari. For Safari before 15.4, also set `-webkit-mask-image` to the same value. ## Caching The mesh and accent come with the title's detail response, so they follow that response's [caching](https://docs-preview.mediux.io/api/caching.md). When Mediux improves how meshes are made, every title's response is refreshed with the new colours, so read them from the API instead of storing them for good. --- # Public API > Anonymous read endpoints for titles, Sets, creators, Lists, feeds and YAML exports. Every Public API route is an anonymous `GET` or `HEAD` on `https://api.mediux.io`: no account, key or token. Paths have no version prefix, trailing slash or query string. - **Titles and more:** Shows, Movies, Collections, Games, People, Networks, Companies and Categories each have an index, a detail route and their Assets; Shows, Movies, Collections and Games also list their Sets. They appear once they have published artwork. Their text comes from TMDB or IGDB, in English only. - **Sets:** the Set's type is in the path, such as `/movie-set/{id}`; show, movie and collection Sets also have [YAML for Kometa](https://docs-preview.mediux.io/api/guides/kometa.md). Talent, Brand and Category Sets, and the Sets routes of People, Networks, Companies and Categories, are not in the initial release. - **Creators and Lists:** profiles with paged content, and Public Lists. - **Feeds:** the Sets changed each day, as JSON or Atom. See [Indexes, feeds and pages](https://docs-preview.mediux.io/api/pagination.md) to go through everything, [Build image URLs](https://docs-preview.mediux.io/api/guides/image-urls.md) for artwork, and [Responses and errors](https://docs-preview.mediux.io/api/errors.md) for the envelope and codes. ## All operations ### Reference - `GET /config`: [Retrieve the API configuration](https://docs-preview.mediux.io/api/reference/reference/retrieve-config.md) ### Shows - `GET /shows/{id}/assets`: [Retrieve a Show's Assets](https://docs-preview.mediux.io/api/reference/shows/retrieve-assets.md) - `GET /shows/{id}/sets`: [Retrieve a Show's Sets](https://docs-preview.mediux.io/api/reference/shows/retrieve-sets.md) - `GET /shows/{id}`: [Retrieve a Show](https://docs-preview.mediux.io/api/reference/shows/retrieve.md) - `GET /shows`: [Retrieve the Show index](https://docs-preview.mediux.io/api/reference/shows.md) - `GET /shows/chunks/{chunk}`: [Retrieve a Show index chunk](https://docs-preview.mediux.io/api/reference/shows/index-chunk.md) ### Seasons - `GET /seasons/{id}/assets`: [Retrieve a Season's Assets](https://docs-preview.mediux.io/api/reference/seasons/retrieve-assets.md) - `GET /seasons/{id}`: [Retrieve a Season](https://docs-preview.mediux.io/api/reference/seasons/retrieve.md) ### Episodes - `GET /episodes/{id}`: [Retrieve an Episode](https://docs-preview.mediux.io/api/reference/episodes/retrieve.md) ### Movies - `GET /movies/{id}/assets`: [Retrieve a Movie's Assets](https://docs-preview.mediux.io/api/reference/movies/retrieve-assets.md) - `GET /movies/{id}/sets`: [Retrieve a Movie's Sets](https://docs-preview.mediux.io/api/reference/movies/retrieve-sets.md) - `GET /movies/{id}`: [Retrieve a Movie](https://docs-preview.mediux.io/api/reference/movies/retrieve.md) - `GET /movies`: [Retrieve the Movie index](https://docs-preview.mediux.io/api/reference/movies.md) - `GET /movies/chunks/{chunk}`: [Retrieve a Movie index chunk](https://docs-preview.mediux.io/api/reference/movies/index-chunk.md) ### Collections - `GET /collections/{id}/assets`: [Retrieve a Collection's Assets](https://docs-preview.mediux.io/api/reference/collections/retrieve-assets.md) - `GET /collections/{id}/sets`: [Retrieve a Collection's Sets](https://docs-preview.mediux.io/api/reference/collections/retrieve-sets.md) - `GET /collections/{id}`: [Retrieve a Collection](https://docs-preview.mediux.io/api/reference/collections/retrieve.md) - `GET /collections`: [Retrieve the Collection index](https://docs-preview.mediux.io/api/reference/collections.md) - `GET /collections/chunks/{chunk}`: [Retrieve a Collection index chunk](https://docs-preview.mediux.io/api/reference/collections/index-chunk.md) ### People - `GET /people/{id}/assets`: [Retrieve a Person's Assets](https://docs-preview.mediux.io/api/reference/people/retrieve-assets.md) - `GET /people/{id}`: [Retrieve a Person](https://docs-preview.mediux.io/api/reference/people/retrieve.md) - `GET /people`: [Retrieve the Person index](https://docs-preview.mediux.io/api/reference/people.md) - `GET /people/chunks/{chunk}`: [Retrieve a Person index chunk](https://docs-preview.mediux.io/api/reference/people/index-chunk.md) ### Networks - `GET /networks/{id}/assets`: [Retrieve a Network's Assets](https://docs-preview.mediux.io/api/reference/networks/retrieve-assets.md) - `GET /networks/{id}`: [Retrieve a Network](https://docs-preview.mediux.io/api/reference/networks/retrieve.md) - `GET /networks`: [Retrieve the Network index](https://docs-preview.mediux.io/api/reference/networks.md) - `GET /networks/chunks/{chunk}`: [Retrieve a Network index chunk](https://docs-preview.mediux.io/api/reference/networks/index-chunk.md) ### Companies - `GET /companies/{id}/assets`: [Retrieve a Company's Assets](https://docs-preview.mediux.io/api/reference/companies/retrieve-assets.md) - `GET /companies/{id}`: [Retrieve a Company](https://docs-preview.mediux.io/api/reference/companies/retrieve.md) - `GET /companies`: [Retrieve the Company index](https://docs-preview.mediux.io/api/reference/companies.md) - `GET /companies/chunks/{chunk}`: [Retrieve a Company index chunk](https://docs-preview.mediux.io/api/reference/companies/index-chunk.md) ### Categories - `GET /categories/{id}/assets`: [Retrieve a Category's Assets](https://docs-preview.mediux.io/api/reference/categories/retrieve-assets.md) - `GET /categories/{id}`: [Retrieve a Category](https://docs-preview.mediux.io/api/reference/categories/retrieve.md) - `GET /categories`: [Retrieve the Category index](https://docs-preview.mediux.io/api/reference/categories.md) - `GET /categories/chunks/{chunk}`: [Retrieve a Category index chunk](https://docs-preview.mediux.io/api/reference/categories/index-chunk.md) ### Games - `GET /games/{id}/assets`: [Retrieve a Game's Assets](https://docs-preview.mediux.io/api/reference/games/retrieve-assets.md) - `GET /games/{id}/sets`: [Retrieve a Game's Sets](https://docs-preview.mediux.io/api/reference/games/retrieve-sets.md) - `GET /games/{id}`: [Retrieve a Game](https://docs-preview.mediux.io/api/reference/games/retrieve.md) - `GET /games`: [Retrieve the Game index](https://docs-preview.mediux.io/api/reference/games.md) - `GET /games/chunks/{chunk}`: [Retrieve a Game index chunk](https://docs-preview.mediux.io/api/reference/games/index-chunk.md) ### Sets - `GET /show-set/{id}`: [Retrieve a Show Set](https://docs-preview.mediux.io/api/reference/sets/retrieve-show-set.md) - `GET /movie-set/{id}`: [Retrieve a Movie Set](https://docs-preview.mediux.io/api/reference/sets/retrieve-movie-set.md) - `GET /collection-set/{id}`: [Retrieve a Collection Set](https://docs-preview.mediux.io/api/reference/sets/retrieve-collection-set.md) - `GET /game-set/{id}`: [Retrieve a Game Set](https://docs-preview.mediux.io/api/reference/sets/retrieve-game-set.md) - `GET /show-set/{id}.yaml`: [Retrieve Show Set YAML](https://docs-preview.mediux.io/api/reference/sets/retrieve-show-set-yaml.md) - `GET /show-set/{id}.original.yaml`: [Retrieve Show Set Original YAML](https://docs-preview.mediux.io/api/reference/sets/retrieve-show-set-original-yaml.md) - `GET /movie-set/{id}.yaml`: [Retrieve Movie Set YAML](https://docs-preview.mediux.io/api/reference/sets/retrieve-movie-set-yaml.md) - `GET /movie-set/{id}.original.yaml`: [Retrieve Movie Set Original YAML](https://docs-preview.mediux.io/api/reference/sets/retrieve-movie-set-original-yaml.md) - `GET /collection-set/{id}.yaml`: [Retrieve Collection Set YAML](https://docs-preview.mediux.io/api/reference/sets/retrieve-collection-set-yaml.md) - `GET /collection-set/{id}.original.yaml`: [Retrieve Collection Set Original YAML](https://docs-preview.mediux.io/api/reference/sets/retrieve-collection-set-original-yaml.md) ### Boxsets and Loadouts - `GET /boxsets/{id}`: [Retrieve a Boxset](https://docs-preview.mediux.io/api/reference/boxsets-and-loadouts/retrieve-boxset.md) - `GET /loadouts/{id}`: [Retrieve a Loadout](https://docs-preview.mediux.io/api/reference/boxsets-and-loadouts/retrieve-loadout.md) ### Assets - `GET /assets/{id}`: [Retrieve an Asset](https://docs-preview.mediux.io/api/reference/assets/retrieve.md) ### Profiles - `GET /users`: [Retrieve the creators directory](https://docs-preview.mediux.io/api/reference/profiles.md) - `GET /users/chunks/{prefix}`: [Retrieve a creators directory bucket](https://docs-preview.mediux.io/api/reference/profiles/index-chunk.md) - `GET /users/{username}`: [Retrieve a User Profile](https://docs-preview.mediux.io/api/reference/profiles/retrieve.md) - `GET /users/{username}/sets/pages/{page}`: [List a creator's Sets](https://docs-preview.mediux.io/api/reference/profiles/list-sets.md) - `GET /users/{username}/boxsets/pages/{page}`: [List a creator's Boxsets](https://docs-preview.mediux.io/api/reference/profiles/list-boxsets.md) - `GET /users/{username}/loadouts/pages/{page}`: [List a creator's Loadouts](https://docs-preview.mediux.io/api/reference/profiles/list-loadouts.md) - `GET /users/{username}/assets/pages/{page}`: [List a creator's Assets](https://docs-preview.mediux.io/api/reference/profiles/list-assets.md) - `GET /users/{username}/lists/pages/{page}`: [List a creator's Public Lists](https://docs-preview.mediux.io/api/reference/profiles/list-lists.md) ### Lists - `GET /lists`: [Retrieve the List discovery index](https://docs-preview.mediux.io/api/reference/lists.md) - `GET /lists/chunks/{prefix}`: [Retrieve a List discovery bucket](https://docs-preview.mediux.io/api/reference/lists/index-chunk.md) - `GET /lists/{id}`: [Retrieve a List](https://docs-preview.mediux.io/api/reference/lists/retrieve.md) - `GET /lists/{id}/titles/{family}/{entity}`: [Retrieve a List title](https://docs-preview.mediux.io/api/reference/lists/retrieve-title.md) ### Activity feeds - `GET /feeds/media-sets`: [List today's Media Sets](https://docs-preview.mediux.io/api/reference/feeds/list-media-sets.md) - `GET /feeds/media-sets/{date}`: [List Media Sets changed on a day](https://docs-preview.mediux.io/api/reference/feeds/list-media-sets-day.md) - `GET /feeds/media-sets.atom`: [Retrieve the Media Set feed as Atom](https://docs-preview.mediux.io/api/reference/feeds/retrieve-media-sets-atom.md) - `GET /feeds/game-sets`: [List today's Game Sets](https://docs-preview.mediux.io/api/reference/feeds/list-game-sets.md) - `GET /feeds/game-sets/{date}`: [List Game Sets changed on a day](https://docs-preview.mediux.io/api/reference/feeds/list-game-sets-day.md) - `GET /feeds/game-sets.atom`: [Retrieve the Game Set feed as Atom](https://docs-preview.mediux.io/api/reference/feeds/retrieve-game-sets-atom.md) --- # Protected API > Read and manage one user's Lists, follows and notifications with their permission. The Protected API lets your app act for one Mediux user, within the [permissions](https://docs-preview.mediux.io/api/authentication.md#permissions) they approved. Routes live on `https://api.mediux.io` under `/account`, `/notifications` and `/relationships`. ## Before you start 1. [Register your app and connect a user](https://docs-preview.mediux.io/api/authentication.md). 2. Call from your server or native app with `Authorization: Bearer ACCESS_TOKEN`. Never send Mediux cookies. 3. Keep tokens out of logs, source control and web pages. Each request checks the connection, the granted permission and that the user owns what you touch. You always act as the user who approved the token: an ID in the request never changes whose data you change. Apps can't publish or change artwork, Sets, Boxsets or Loadouts, delete Lists, Like anything or manage the account. Owners do those on mediux.io. Responses are `Cache-Control: private, no-store`, and errors use the [shared error format](https://docs-preview.mediux.io/api/errors.md#errors). Send only the fields you change; omitted fields stay as they are. ## Routes | Area | Routes | Permission | | ------------- | --------------------------------------------------------------- | ---------------------------------------------- | | Identity | [`GET /account`](https://docs-preview.mediux.io/api/reference/account-identity/get.md) | Any | | Relationships | [Follows and hides](#all-operations) below | `relationships:read` or `relationships:manage` | | Lists | `/account/lists`, see [Read and edit Lists](https://docs-preview.mediux.io/api/guides/lists.md) | `lists:read` or `lists:write` | | Notifications | [`GET /notifications`](https://docs-preview.mediux.io/api/reference/notifications/list.md), [`POST /notifications/read`](https://docs-preview.mediux.io/api/reference/notifications/mark-read.md) | `notifications:read` | ### Notifications `GET /notifications` lists the user's notifications, newest first, paged with `?after=` and `?limit=` (see [protected lists](https://docs-preview.mediux.io/api/pagination.md#protected-lists)). `POST /notifications/read` marks them read: send `{ "ids": [...] }` with 1 to 100 IDs, or `{ "all": true }`. It answers `{ "data": { "markedRead": 3 } }`. IDs that aren't the user's change nothing. ## All operations ### Relationships - `GET /relationships`: [List relationships](https://docs-preview.mediux.io/api/reference/relationships/list.md) - `PUT /relationships/{username}`: [Follow or hide a User](https://docs-preview.mediux.io/api/reference/relationships/set.md) - `DELETE /relationships/{username}`: [Clear a relationship](https://docs-preview.mediux.io/api/reference/relationships/clear.md) ### Identity - `GET /account`: [Get the connected User](https://docs-preview.mediux.io/api/reference/account-identity/get.md) ### Your Lists - `GET /account/lists`: [List your Lists](https://docs-preview.mediux.io/api/reference/account-lists/list.md) - `POST /account/lists`: [Create a List](https://docs-preview.mediux.io/api/reference/account-lists/create.md) - `GET /account/lists/membership`: [Find your Lists holding a title](https://docs-preview.mediux.io/api/reference/account-lists/membership.md) - `GET /account/lists/{id}`: [Get one of your Lists](https://docs-preview.mediux.io/api/reference/account-lists/retrieve.md) - `PATCH /account/lists/{id}`: [Edit one of your Lists](https://docs-preview.mediux.io/api/reference/account-lists/update.md) - `GET /account/lists/{id}/titles/{family}/{entity}`: [Get a title in one of your Lists](https://docs-preview.mediux.io/api/reference/account-lists/retrieve-title.md) - `POST /account/lists/{id}/titles`: [Add titles to a List](https://docs-preview.mediux.io/api/reference/account-lists/add-titles.md) - `POST /account/lists/{id}/titles/remove`: [Remove titles from a List](https://docs-preview.mediux.io/api/reference/account-lists/remove-titles.md) - `POST /account/lists/{id}/assets`: [Add Assets to an Asset List](https://docs-preview.mediux.io/api/reference/account-lists/add-assets.md) - `POST /account/lists/{id}/assets/remove`: [Remove Assets from an Asset List](https://docs-preview.mediux.io/api/reference/account-lists/remove-assets.md) - `PUT /account/lists/{id}/subscription`: [Subscribe to or leave a Public List](https://docs-preview.mediux.io/api/reference/account-lists/set-subscription.md) ### Notifications - `GET /notifications`: [List your Notifications](https://docs-preview.mediux.io/api/reference/notifications/list.md) - `POST /notifications/read`: [Mark Notifications read](https://docs-preview.mediux.io/api/reference/notifications/mark-read.md) --- # Using Mediux > Find, choose and download community artwork for your media library. Mediux is a community library of artwork for shows, movies, collections and games. Browsing and downloading are open to everyone, with no account needed. Building an integration? See the [API docs](https://docs-preview.mediux.io/api.md). ## Find a title Search for a show, movie, collection, game, person, network, company or category, and check the year when several titles share a name. To browse for ideas, open the Shows, Movies, Collections, Games or Users indexes; a creator's profile is a good start when you already like their style. A show page links to its seasons and episodes, a collection page to its movies, and a game page to related games. A page link that holds only a numeric ID keeps working if the title is renamed. ## Sets, Boxsets and Loadouts A **Set** is one creator's artwork for one show, movie, collection or game. A show Set can include the show's seasons and episodes; a collection Set can include its movies. Empty positions are normal: a Set doesn't need every artwork type, and single images can use a different language or edition from the Set. A **Boxset** groups a creator's show, movie and collection Sets; a **Loadout** groups their game Sets. Standalone artwork sits outside any Set. The images that identify a title come from providers such as TMDB and IGDB. They are separate from community artwork, which has its own creator and downloadable file. ### Artwork types | Type | Shape | Use | | ---------- | -------- | ------------------ | | Poster | 2:3 | Vertical cover | | Backdrop | 16:9 | Wide background | | Logo | Flexible | Wordmark or emblem | | Square Art | 1:1 | Square image | | Thumb | 16:9 | Compact wide image | | Titlecard | 16:9 | Episode image | A show poster and a season poster share a shape but not a subject, so check both the type and the title it belongs to. Games use their own types: | Type | Shape | Minimum | Maximum | Maximum file size | | ------------ | -------- | --------- | --------- | ----------------- | | Cover | 2:3 | 600×900 | 2400×3600 | 20 MiB | | Wide Cover | 92:43 | 460×215 | 3680×1720 | 20 MiB | | Square Cover | 1:1 | 512×512 | 4096×4096 | 15 MiB | | Background | 16:9 | 1920×1080 | 3840×2160 | 20 MiB | | Hero | 96:31 | 1920×620 | 7680×2480 | 20 MiB | | Logo | Flexible | — | — | 7.5 MiB | | Icon | 1:1 | 256×256 | 1024×1024 | 5 MiB | ## Download artwork Use **Download** on an artwork to save the creator's original file with a descriptive filename. The smaller images on cards are previews: saving one gives you less detail than the creator uploaded. For several files, choose **Download assets** on a Set, Boxset or Loadout page and pick files one by one, by type or by group (such as a season). One file saves directly; two or more come in a ZIP built in your browser, up to 250 files at a time. Extract the ZIP before using the images. If some files fail, the rest still save and you're told it was partial; run the download again for the missing ones. Game Icons can also download as **ICO**, a static file with several icon sizes. ### Share a page, not an image A title or Set page tells the recipient who made the artwork and what else is available. An image URL points at one version of one file: when a creator replaces the artwork, the replacement gets a new URL and the old one may stop working. Copy links whole; editing the size or extension in an image URL isn't a reliable way to get another format. ## Apply artwork Your library app or launcher decides how artwork is applied. - **Kometa (Plex):** a show, movie or collection Set's **YAML export** applies the whole Set. See [Use Set YAML with Kometa](https://docs-preview.mediux.io/api/guides/kometa.md). - **Steam:** right-click the game in your Library, open **Properties → Customization**, and choose a downloaded file for each field: Cover for the portrait cover, Wide Cover for the wide capsule, Hero for the top of the game page and Logo over the Hero. Valve's [library asset reference](https://partner.steamgames.com/doc/store/assets/libraryassets) has the details. ## Follow new artwork [Activity](https://mediux.io/feed) lists Sets that were recently added or had artwork changed, with a [Games tab](https://mediux.io/feed/games). Renaming a Set doesn't bring it back into the feed. Follow a creator to hear about their new Sets; see [Your account](https://docs-preview.mediux.io/guides/account.md#notifications). ## Likes and Lists With an account you can **Like** a Set or an image. The count is public, who liked it is not, and a Like does nothing else: it doesn't notify the creator or save the artwork. A **List** is a collection you curate: - an **Asset List** holds individual images (about 1,000); - a **Media List** holds shows, movies and collections, with one chosen image per position, or none yet, so it can mirror your library (up to 500 titles); - a **Game List** does the same for games. Lists are private until you make them **Public**. Anyone can read a Public List; others can **Subscribe** to it or **Clone** their own copy. Public List changes can take up to an hour to show; making a List private or deleting it is immediate. Apps you connect can read and edit your Lists with your permission. --- # Publishing artwork > Upload Sets, group them into Boxsets and Loadouts, and handle artwork requests. Sign in with a verified email address to publish. Uploads happen on [mediux.io](https://mediux.io); apps can't publish for you. ## Choose a home for your artwork Use a **Set** for artwork that belongs to one show, movie, collection or game. A show Set can cover its seasons and episodes; a collection Set its movies. Episode titlecards always belong to a show Set. Use a standalone upload for a single image that doesn't belong in a Set. People, networks, companies and categories take standalone artwork too, which you can organise into Sets. For game artwork, check the [types and limits](https://docs-preview.mediux.io/guides.md#artwork-types) first. Game artwork is static: animated images are rejected. ## Place your files The uploader's **DropMap** lists every part your Set covers (the show, its seasons and episodes, or a collection's movies) against the artwork types each supports. A filled marker holds a file, an empty one is free, and a dash means the type doesn't apply. You don't need to fill every position. Filenames help Mediux suggest a position: | Filename | Placed as | | ------------------ | ----------------------------- | | `show-poster.png` | Show poster | | `S01-backdrop.png` | Season 1 backdrop | | `S01E02.png` | Season 1, episode 2 titlecard | Check each suggestion. A position holds one image, so resolve duplicates before you submit. Language and edition default from the Set, and single images can override them. ## Submit Mediux uploads your files six at a time, then saves the Set with every file that uploaded, in one step. A Set is never published half-saved. A file that fails shows why; add it later by editing the Set. If saving fails, nothing is published: choose **Start again** to return to the form with your files. Replacing published artwork gives it a new image URL, so old direct links may stop working. Replaced and deleted artwork can't be restored. ## Boxsets and Loadouts A **Boxset** groups your show, movie and collection Sets; a **Loadout** your game Sets. Pick one (or create one) as the **destination** when you create a Set, or fill one later from your Sets. - A Set belongs to at most one Boxset or Loadout, which holds only one Set per title. - A Boxset or Loadout needs a language, which also applies to its own Poster. It must hold at least one Set or a Poster. - Sets are ordered automatically, newest release first. - Removing a Set never deletes it. Removing the last item deletes the empty Boxset or Loadout, after you confirm. ## Artwork requests Anyone signed in can ask a creator for artwork on a title with **Request art** (on a title's Requests tab or a creator's profile). Add asset types and a note of up to 500 characters. If that creator already has an open request for the title, **Watch** it instead of sending another. A request is **Pending** until the creator accepts it, then **Accepted**, and **Done** once they link their artwork. You can have 50 open requests, and a creator receives up to 50 at a time. Creators choose whether to accept requests at all. Find yours in **Studio → My Requests**. ## Find gaps in your Sets **Studio → Set Audit** scans your Sets for empty positions by Set type and artwork slot. Results load in batches; save the gaps you want to work on to the **Planner**, which ticks them off as you add artwork. You can also plan artwork by hand for any title, including upcoming ones. --- # Your account > Sign in, manage settings and notifications, connect apps, or delete your account. You need an account to publish, make requests, keep Lists and Likes, follow creators and get notifications. Browsing and downloading don't need one. ## Sign up and sign in Choose **Sign up** with an email address, a username and a password of at least 8 characters. Your username names your public profile. Verify your email with the link Mediux sends (valid for 30 minutes); publishing needs a verified email. Forgot your password? **Forgot password** sends a reset link, also valid for 30 minutes. With two-factor authentication on, Mediux also asks for a code from your authenticator app or a backup code; you can trust a device for 30 days. ## Settings Your account settings hold: - **Public profile:** details, avatar, profile backdrop and links; - **Preferences:** artwork languages, request and notification choices; - **Relationships:** the creators you follow or hide; - **Security:** password, email verification and two-factor authentication; - **Sessions:** where you're signed in (sessions last 30 days); and - **Apps:** apps you've connected and apps you've registered. ## Notifications Open the bell for the newest notifications, or the Notifications page for all of them. You hear about requests you sent or received, issues reported on your artwork, new followers, announcements, and new or updated Sets from creators you follow with **Artwork notifications** turned on (under **Account → Relationships**). Likes and Lists never notify anyone. Notifications are deleted after 90 days. ## Connected apps A connected app uses your account within the permissions you approve. A website or desktop app sends you to Mediux to approve it. A tool on a TV, server or in Docker shows a short code: enter it at [mediux.io/link](https://mediux.io/link) within ten minutes. Only enter a code you started yourself. Before you approve, Mediux shows the app's name, its developer and the permissions it asks for. Mediux hasn't reviewed apps, so only connect ones you trust. An app can: | Permission | Lets the app | | ------------------ | ------------------------------------------------------ | | Relationships | Read, or read and manage, your follows and hides | | Lists: read | Read your Lists, including private and subscribed ones | | Lists: write | Create and edit Lists, add and remove titles or images, and subscribe | | Notifications | Read your notifications and mark them read | Apps never publish, change or delete artwork, Sets, Boxsets or Loadouts, delete Lists, Like for you, or change your account. An app stays connected until you choose **Disconnect** in **Account → Apps**, or until it goes 90 days unused. Disconnecting stops it straight away; anything it already did stays. Building an app? See [Authentication](https://docs-preview.mediux.io/api/authentication.md). ## Delete your account Request deletion in **Account → Security → Delete account** with your password (and a two-factor code if you use one). Your account stays active, and you can withdraw the request, until an administrator completes it. They either keep your published Sets and artwork under a placeholder Deleted User account (the default) or remove them. Either way your Lists and personal data are deleted, and deletion can't be undone.