# Maintainerr API

**Canonical:** https://apis.io/apis/maintainerr/maintainerr-api/  
**Provider:** Maintainerr — https://apis.io/providers/maintainerr/  
**Documentation:** https://docs.maintainerr.info/3.8.0/api

Maintainerr API is one of 2 APIs that [Maintainerr](https://apis.io/providers/maintainerr/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. This API exposes 1 JSON Schema definition. The published artifact set on APIs.io includes an OpenAPI specification and 1 JSON Schema.

Maintainerr API as documented publicly: 43 operations. Contract generated from the documentation by API Evangelist (2026-10-28); not the provider's own document.

## Operations (43)

| Method | Path | Summary |
|---|---|---|
| POST | `/api/collections/media/handle` | Run the configured collection action immediately for one item from the collection detail modal |
| GET | `/api/collections/overlay-data` | Returns collections with full media membership for overlay consumers, including the Calendar page |
| GET | `/api/metadata/backdrop/{type}` | Resolve a backdrop image for a movie or show from the configured metadata providers |
| GET | `/api/metadata/image/{type}` | Resolve a poster image for a movie or show from the configured metadata providers |
| GET | `/api/overlays/fonts` | List available fonts |
| POST | `/api/overlays/fonts` | Upload a .ttf , .otf , or .woff font |
| GET | `/api/overlays/fonts/{name}` | Read a bundled or uploaded font file |
| GET | `/api/overlays/images` | List uploaded overlay image assets |
| POST | `/api/overlays/images` | Upload a .png , .jpg / .jpeg , or .webp image for template image elements |
| DELETE | `/api/overlays/images/{name}` | Delete an uploaded overlay image asset |
| GET | `/api/overlays/images/{name}` | Read an uploaded overlay image asset |
| GET | `/api/overlays/poster` | Proxy media artwork for template preview |
| POST | `/api/overlays/process` | Run overlay processing for all eligible collections |
| POST | `/api/overlays/process/{collectionid}` | Run overlay processing for one collection |
| GET | `/api/overlays/random-episode` | Get a random episode for title-card preview |
| GET | `/api/overlays/random-item` | Get a random media item for poster-template preview |
| DELETE | `/api/overlays/reset` | Revert all overlays |
| POST | `/api/overlays/revert/{collectionid}` | Revert overlays for one collection |
| GET | `/api/overlays/sections` | GET /api/overlays/sections |
| GET | `/api/overlays/settings` | Read global overlay settings |
| PUT | `/api/overlays/settings` | Update global overlay settings |
| GET | `/api/overlays/status` | Read the latest overlay processing status |
| GET | `/api/overlays/templates` | List overlay templates |
| POST | `/api/overlays/templates` | Create a template |
| DELETE | `/api/overlays/templates/{id}` | Delete a non-preset template |
| GET | `/api/overlays/templates/{id}` | Fetch one template |
| PUT | `/api/overlays/templates/{id}` | Update a template |
| POST | `/api/overlays/templates/{id}/default` | Set a template as the default for its mode |
| POST | `/api/overlays/templates/{id}/duplicate` | Clone a template into an editable copy |
| POST | `/api/overlays/templates/{id}/export` | Export a template as JSON |
| POST | `/api/overlays/templates/{id}/preview` | Render a server-side preview of a template on real artwork |
| POST | `/api/overlays/templates/import` | Import a template from JSON |
| GET | `/api/settings/metadata-provider` | Read which metadata provider is currently primary |
| POST | `/api/settings/metadata-provider` | Change the primary metadata provider |
| POST | `/api/settings/metadata/refresh/{provider}` | Clear cached metadata for TMDB or TVDB and queue a media-server refresh pass |
| DELETE | `/api/settings/tmdb` | Remove the saved TMDB API key |
| GET | `/api/settings/tmdb` | Read the saved TMDB API key state |
| POST | `/api/settings/tmdb` | Save a TMDB API key |
| DELETE | `/api/settings/tvdb` | Remove the saved TVDB API key |
| GET | `/api/settings/tvdb` | Read the saved TVDB API key state |
| POST | `/api/settings/tvdb` | Save a TVDB API key |
| GET | `/api/storage-metrics` | Return aggregated disk usage, instance health, and collection-size summaries |
| GET | `/api/storage-metrics/library-sizes` | Compute per-library sizes on demand; potentially slow on large libraries |

## Machine-readable artifacts (2)

- **OpenAPI** — https://artifacts.apis.io/maintainerr/openapi/_ae-authored/maintainerr-openapi-generated.yml
- **JSONSchema** — https://artifacts.apis.io/maintainerr/json-schema/maintainerr-post-api-overlays-images-request-schema.json

## Other Maintainerr APIs (1)

- [Maintainerr API](https://apis.io/apis/maintainerr/maintainerr-api-2/)

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/maintainerr/maintainerr-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/maintainerr/.