Maintainerr

https://docs.maintainerr.info/
Admin
Maintainerr is a self-hosted tool that automates media clean-up and management by finding media on...
Tokens:188,494
Snippets:1,138
Trust Score:5.7
Update:6 days ago
Show doc for...
Tokens:
Raw
### GET /api/collections/media response example

Source: https://docs.maintainerr.info/api/collections

Example JSON response for the GET /api/collections/media endpoint, showing a raw membership row with fields like id, collectionId, mediaServerId, tmdbId, addDate, image_path, isManual, includedByRule, manualMembershipSource, sizeBytes, and ruleEvaluationFailed.

```json
[

  {

    "id": 1,

    "collectionId": 1,

    "mediaServerId": "12345",

    "tmdbId": 550,

    "addDate": "2026-06-05T00:00:00.000Z",

    "image_path": null,

    "isManual": true,

    "includedByRule": false,

    "manualMembershipSource": "local",

    "sizeBytes": null,

    "ruleEvaluationFailed": false

  }

]
```

--------------------------------

### Start local development server with npm start

Source: https://docs.maintainerr.info/contributing

Starts the local development server for the documentation site.

```bash
npm start  
```

--------------------------------

### GET /api/notifications/configurations - Response

Source: https://docs.maintainerr.info/api/notifications

Example JSON response from the GET endpoint. Returns an array of configurations; an empty array means no agents are configured. Secrets are returned in cleartext.

```json
[
  {
    "id": 1,
    "name": "My Discord",
    "agent": "discord",
    "enabled": true,
    "types": [2, 4],
    "options": {
      "agent": "discord",
      "webhookUrl": "https://discord.com/api/webhooks/..."
    },
    "aboutScale": 3
  }
]
```

--------------------------------

### Install dependencies with npm install

Source: https://docs.maintainerr.info/contributing

Run this command in the project root to install all required dependencies for the documentation site.

```bash
npm install  
```

--------------------------------

### GET /api/media-server/meta/{id}/maintainerr-status - Response Example

Source: https://docs.maintainerr.info/api/media-server

Example JSON response explaining why an item is excluded from or manually added to Maintainerr collections. A 'Global' entry with no targetPath means a global exclusion. The '(5d left)' suffix is the remaining countdown, computed at request time.

```json
{
  "excludedFrom": [
    { "label": "Global" },
    { "label": "Example collection", "targetPath": "/collections/1/exclusions" }
  ],
  "manuallyAddedTo": [
    { "label": "Example collection (5d left)", "targetPath": "/collections/1" }
  ]
}
```

--------------------------------

### GET /api/overlays/settings

Source: https://docs.maintainerr.info/api/overlays

Returns the current overlay settings, including enabled flag, cron schedule, and legacy style blocks. On a fresh install, it creates default settings before responding.

```APIDOC
## GET /api/overlays/settings

### Description
Returns the overlay settings. On a fresh install, if the settings row does not exist, it is created from defaults before the response is built.

### Method
GET

### Endpoint
/api/overlays/settings

### Response
#### Success Response (200)
- **enabled** (boolean) - Whether overlays are enabled.
- **cronSchedule** (string) - The cron schedule for overlay generation.
- **posterOverlayText** (object) - Legacy style block.
- **posterOverlayStyle** (object) - Legacy style block.
- **posterFrame** (object) - Legacy style block.
- **titleCardOverlayText** (object) - Legacy style block.
- **titleCardOverlayStyle** (object) - Legacy style block.
- **titleCardFrame** (object) - Legacy style block.

#### Response Example
{
  "enabled": true,
  "cronSchedule": "0 4 * * *",
  "posterOverlayText": {},
  "posterOverlayStyle": {},
  "posterFrame": {},
  "titleCardOverlayText": {},
  "titleCardOverlayStyle": {},
  "titleCardFrame": {}
}

#### Error Responses
- **500** - The read, or the first-run write described below, failed.
```

--------------------------------

### Response JSON for GET /api/storage-metrics/library-sizes

Source: https://docs.maintainerr.info/api/metadata-and-storage

Example response showing the generatedAt timestamp and a sizeBytesByLibrary map with library IDs as keys. Keys are media-server library ids; Plex and Jellyfin set an entry for every library (possibly 0), while Emby only includes libraries with a total above zero.

```json
{
  "generatedAt": "2026-06-05T12:00:00.000Z",
  "sizeBytesByLibrary": { "1": 0, "2": 0 }
}
```

--------------------------------

### GET /api/logs/settings response example

Source: https://docs.maintainerr.info/api/logs

Returns the saved log level, rotation size, and backup count. The response includes level, max_size (in MB), and max_files (retention count).

```json
{ "level": "info", "max_size": 20, "max_files": 7 }
```

--------------------------------

### Start Maintainerr with Docker Compose

Source: https://docs.maintainerr.info/downgrade

Pull the pinned image and start the container using Docker Compose.

```bash
docker compose pull

docker compose up -d
```

--------------------------------

### GET /api/media-server/meta/{id} - Response Example

Source: https://docs.maintainerr.info/api/media-server

Example JSON response for fetching full metadata for a single media item. The 'path' field is the server's filesystem path for the item; movies and episodes return the media file, while shows and seasons return the folder. Watch fields (viewCount, lastViewedAt, userRating) are per-user and cached for 5 minutes.

```json
{
  "id": "12345",
  "title": "An example title",
  "guid": "plex://movie/abc",
  "type": "movie",
  "addedAt": "2026-01-01T00:00:00.000Z",
  "providerIds": { "tmdb": ["550"] },
  "mediaSources": [{ "id": "1", "sizeBytes": 0 }],
  "path": "/media/movies/An example title (2026)/An example title (2026).mkv",
  "library": { "id": "1", "title": "Movies" }
}
```

--------------------------------

### GET /api/settings/telemetry/status response example

Source: https://docs.maintainerr.info/api/settings

Example JSON response from the telemetry status endpoint. The fields nextSendAtWeekly and nextSendAtRich are null when reporting is off or when the scheduled job failed to register.

```json
{
  "forcedOff": false,
  "nextSendAtWeekly": "2026-06-08T04:12:00.000Z",
  "nextSendAtRich": "2026-09-14T04:12:00.000Z"
}
```

--------------------------------

### GET /api/settings/test/setup

Source: https://docs.maintainerr.info/api/settings

Reports whether the required media server settings are filled in. Returns a boolean; no connection attempt is made.

```APIDOC
## [GET] /api/settings/test/setup

### Description
Reports whether the required media server settings are filled in. If the fields for the configured media server are populated, returns true; otherwise returns false. The response is a bare boolean and no connection attempt is made.

### Method
GET

### Endpoint
/api/settings/test/setup

### Parameters
None

### Response
#### Success Response (200)
Returns a bare boolean: true if setup is complete (fields are populated), false otherwise. Fields required: Plex (hostname, name, port, token), Jellyfin/Emby (URL, API key). User id is optional for Jellyfin/Emby. Any internal error is reported as false.

#### Response Example
`true`
```

--------------------------------

### GET /api/rules/community/karma/history

Source: https://docs.maintainerr.info/api/rules

Lists which community rules this install has already voted on. Returns an array of objects with the rule ID and community rule ID.

```APIDOC
## GET /api/rules/community/karma/history

### Description
List which community rules this install has already voted on.

### Method
GET

### Endpoint
/api/rules/community/karma/history

### Response
#### Success Response (200)
- **id** (number) - The ID of the vote record.
- **community_rule_id** (number) - The ID of the community rule that was voted on.

#### Response Example
```json
[
  {
    "id": 1,
    "community_rule_id": 12
  }
]
```

#### Error Response (500)
- The database read failed.
```

--------------------------------

### GET /api/media-server/overview/bootstrap

Source: https://docs.maintainerr.info/api/media-server

Fetches the library list plus the first library's first content page in one request. A convenience route for the Overview page, so it can render in one round trip.

```APIDOC
## GET /api/media-server/overview/bootstrap

### Description
Fetches the library list plus the first library's first content page in one request. A convenience route for the Overview page, so it can render in one round trip.

### Method
GET

### Endpoint
/api/media-server/overview/bootstrap

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Page size for the embedded content page, default `50`
- **sort** (string) - Optional - Same values as the content route
- **sortOrder** (string) - Optional - `asc` or `desc`

### Response
#### Success Response (200)
- **libraries** (array) - List of libraries, each with `id`, `title`, `type`
- **selectedLibraryId** (string) - The ID of the first library
- **content** (object) - Contains `items`, `totalSize`, `offset`, `limit`

#### Response Example
{
  "libraries": [{ "id": "1", "title": "Movies", "type": "movie" }],
  "selectedLibraryId": "1",
  "content": { "items": [], "totalSize": 0, "offset": 0, "limit": 50 }
}

### Error Responses
- **400** - `limit` is not an integer, or `sort` or `sortOrder` is outside its allowed values
- **500** - The page read failed, or the Maintainerr state lookup failed
- **503** - The library list is unavailable because the server could not be reached

### Notes
There is no way to choose which library is bootstrapped. It is always the first one the media server returned. The embedded page is always filtered to that library's own type, so a show library returns shows and never seasons or episodes. A `sort` of `manual` or `excluded` pays the full-library sweep described above, at page load.
```

--------------------------------

### Radarr disk space response example

Source: https://docs.maintainerr.info/api/servarr

Example JSON response from GET /api/servarr/radarr/{id}/diskspace. Shows a merged mount list with fields id, path, label, freeSpace, totalSpace, and hasAccurateTotalSpace. Entries from root folders have label null and hasAccurateTotalSpace false.

```json
[
  {
    "id": 1,
    "path": "/movies",
    "label": "/",
    "freeSpace": 0,
    "totalSpace": 0,
    "hasAccurateTotalSpace": true
  }
]
```

--------------------------------

### Create production build with npm run build

Source: https://docs.maintainerr.info/contributing

Builds the documentation site for production. Run this before opening a pull request when making structural or formatting changes.

```bash
npm run build  
```

--------------------------------

### Serve production build locally with npm run serve

Source: https://docs.maintainerr.info/contributing

Serves the production build locally to preview the site.

```bash
npm run serve  
```

--------------------------------

### Create data directory and start Podman Quadlet unit

Source: https://docs.maintainerr.info/installation

Creates the data directory, reloads systemd, starts the maintainerr unit, and enables linger to keep it running while logged out.

```bash
mkdir -p ~/maintainerr/data
```

```bash
systemctl --user daemon-reload
```

```bash
systemctl --user start maintainerr
```

```bash
loginctl enable-linger "$USER" # keeps it running while you are logged out
```

--------------------------------

### GET /api/streamystats/items/{itemId} response

Source: https://docs.maintainerr.info/api/streamystats

Example JSON response from the /api/streamystats/items/{itemId} endpoint. episodeStats is only present for series, and firstWatched and lastWatched are null when nothing has been watched.

```json
{
  "item": { "id": "abc123", "name": "Example title", "type": "Series" },
  "totalViews": 12,
  "totalWatchTime": 34567,
  "completionRate": 0.87,
  "firstWatched": "2026-01-02T10:00:00.000Z",
  "lastWatched": "2026-03-04T21:15:00.000Z",
  "usersWatched": [
    {
      "user": { "id": "u1", "name": "example-user" },
      "watchCount": 3,
      "totalWatchTime": 8400,
      "completionRate": 1,
      "firstWatched": "2026-01-02T10:00:00.000Z",
      "lastWatched": "2026-02-01T20:00:00.000Z"
    }
  ],
  "watchHistory": [
    {
      "user": { "id": "u1", "name": "example-user" },
      "watchDate": "2026-02-01T20:00:00.000Z",
      "watchDuration": 2800,
      "completionPercentage": 98,
      "playMethod": "DirectPlay",
      "deviceName": "Living room",
      "clientName": "Jellyfin Web"
    }
  ],
  "watchCountByMonth": [
    {
      "month": 2,
      "year": 2026,
      "watchCount": 4,
      "uniqueUsers": 2,
      "totalWatchTime": 11200
    }
  ],
  "episodeStats": {
    "totalSeasons": 3,
    "totalEpisodes": 30,
    "watchedEpisodes": 21,
    "watchedSeasons": 2
  }
}
```

--------------------------------

### POST /api/settings/emby

Source: https://docs.maintainerr.info/api/settings

Test, then store Emby credentials and make Emby the active media server.

```APIDOC
## POST /api/settings/emby

### Description
Test, then store Emby credentials and make Emby the active media server. This changes the active media server without clearing anything.

### Method
POST

### Endpoint
/api/settings/emby

### Parameters
#### Request Body
- `emby_url` (string) - Required - Emby server URL
- `emby_api_key` (string) - Required - Emby API key
- `emby_user_id` (string) - Optional - Emby user ID

### Response
#### Success Response (201)
- Saved. On failure, returns `status: "NOK"`.

#### Error Response (400)
- Validation failed

### Response Example
```json
{
  "status": "OK"
}
```

```

--------------------------------

### GET /api/notifications/types - Response

Source: https://docs.maintainerr.info/api/notifications

Example response from the types endpoint. Lists subscribable notification event types with their numeric values. The route always returns 200 and cannot fail.

```json
[

  { "title": "Media Added To Collection", "id": 2 },  

  { "title": "Media Removed From Collection", "id": 4 },  

  { "title": "Media About To Be Handled", "id": 8 },  

  { "title": "Media Handled", "id": 16 },  

  { "title": "Rule Handling Failed", "id": 32 },  

  { "title": "Collection Handling Failed", "id": 64 },  

  { "title": "Overlay Applied", "id": 256 },  

  { "title": "Overlay Reverted", "id": 512 },  

  { "title": "Update Available", "id": 1024 }  

]
```

--------------------------------

### Start Docker Compose services

Source: https://docs.maintainerr.info/installation

Starts all services defined in the docker-compose.yml file. Run from the directory containing the file.

```bash
docker compose up -d
```

--------------------------------

### GET /api/notifications/agents - Response

Source: https://docs.maintainerr.info/api/notifications

Example response from the agents endpoint. Lists a fixed set of supported agents and their option fields. The route always returns 200 and cannot fail.

```json
[

  {  

    "name": "discord",  

    "friendlyName": "Discord",  

    "options": [  

      {  

        "field": "webhookUrl",  

        "type": "text",  

        "required": true,  

        "extraInfo": ""  

      },  

      {  

        "field": "botUsername",  

        "type": "text",  

        "required": false,  

        "extraInfo": ""  

      },  

      {  

        "field": "botAvatarUrl",  

        "type": "text",  

        "required": false,  

        "extraInfo": ""  

      }  

    ]  

  }  

]
```

--------------------------------

### GET /api/overlays/status response

Source: https://docs.maintainerr.info/api/overlays

Response body for the status endpoint. The status field is 'idle', 'running', or 'error'. Poll this endpoint until status is no longer 'running' after starting a fire-and-forget run.

```json
{
  "status": "idle",
  "lastRun": "2026-06-05T04:00:00.000Z",
  "lastResult": { "processed": 12, "reverted": 0, "skipped": 3, "errors": 0 }
}
```
Tokens:
Raw