API Reference

API Reference

Prunerr has a REST API you can use for automation, scripts, or integrating with other tools.

Authentication

All external API requests need an API key. The key is auto-generated when Prunerr starts for the first time. You can find it in Settings > API Key.

Pass it in the X-Api-Key header:

curl -H "X-Api-Key: your-key-here" http://your-server:3000/api/stats

The web UI doesn't need the key — it's detected as same-origin automatically.

You can also set the key via the PRUNERR_API_KEY environment variable if you want to control it at the Docker level.

Endpoints

Dashboard

Method	Endpoint	Description
GET	/api/stats	Dashboard statistics (library counts, storage, queue stats)
GET	/api/health	Service connection status and response times

Library

Method	Endpoint	Description
GET	/api/library	List library items. Supports page, limit, type, status, search, sortBy, sortOrder query params.
GET	/api/library/:id	Get a single item's full details
POST	/api/library/:id/mark-deletion	Queue an item for deletion. Body: { gracePeriodDays?, deletionAction?, resetOverseerr? }
POST	/api/library/bulk/mark-deletion	Queue multiple items. Body: { ids: number[], gracePeriodDays?, deletionAction?, resetOverseerr? }
POST	/api/library/:id/protect	Protect an item
DELETE	/api/library/:id/protect	Remove protection
POST	/api/library/sync	Trigger a library scan

Rules

Method	Endpoint	Description
GET	/api/rules	List all rules
POST	/api/rules	Create a rule
PUT	/api/rules/:id	Update a rule
DELETE	/api/rules/:id	Delete a rule
POST	/api/rules/:id/run	Run a rule manually
POST	/api/rules/preview	Preview which items a rule would match
GET	/api/rules/suggestions	Get template suggestions based on your library

Collections

Method	Endpoint	Description
GET	/api/collections	List all collections
GET	/api/collections/:id	Get collection details
GET	/api/collections/:id/items	List items in a collection
POST	/api/collections/sync	Sync collections from Radarr
PATCH	/api/collections/:id/protection	Toggle protection. Body: { isProtected: boolean, reason?: string }
POST	/api/collections/:id/queue	Queue collection for deletion. Body: { deletionAction, gracePeriodDays?, resetOverseerr? }

Queue

Method	Endpoint	Description
GET	/api/queue	List items in the deletion queue
DELETE	/api/queue/:id	Remove an item from the queue
POST	/api/queue/process	Process pending deletions (items past grace period)

Activity

Method	Endpoint	Description
GET	/api/activity	Activity log. Supports page, limit, eventTypes, search query params.
GET	/api/activity/item/:itemId	Activity for a specific item (includes collection-level events)

Users

Method	Endpoint	Description
GET	/api/users	List synced Plex users
POST	/api/users/sync	Sync users from Plex

Settings

Method	Endpoint	Description
GET	/api/settings	Get all settings
GET	/api/settings/api-key	Get the current API key
POST	/api/settings/api-key/regenerate	Generate a new API key (invalidates the old one)

Response Format

All responses follow the same format:

{
  "success": true,
  "data": { ... },
  "message": "optional message"
}

Errors:

{
  "success": false,
  "error": "What went wrong"
}

Paginated endpoints include:

{
  "success": true,
  "data": {
    "items": [...],
    "total": 807,
    "page": 1,
    "totalPages": 34
  }
}