-
Notifications
You must be signed in to change notification settings - Fork 0
API Documentation
NeXroll provides a comprehensive REST API for programmatic access. The API is built with FastAPI and includes interactive documentation at http://localhost:9393/docs.
http://localhost:9393
Most endpoints do not require authentication as NeXroll is designed for local use. Some endpoints may require API keys for external integrations.
All responses are in JSON format. Successful responses return HTTP 200, errors return appropriate HTTP status codes with error details.
Health check endpoint.
Response:
{
"status": "healthy"
}Get API and installed version information.
Response:
{
"api_version": "1.4.6",
"registry_version": "1.4.6",
"install_dir": "C:\\Program Files\\NeXroll"
}Get FFmpeg installation status.
Response:
{
"ffmpeg_present": true,
"ffmpeg_version": "ffmpeg version 6.0",
"ffprobe_present": true,
"ffprobe_version": "ffprobe version 6.0"
}List all prerolls with optional filtering.
Query Parameters:
-
category_id(optional): Filter by category ID -
tags(optional): Filter by tags (comma-separated)
Response:
[
{
"id": 1,
"filename": "intro.mp4",
"display_name": null,
"path": "/data/prerolls/Default/intro.mp4",
"thumbnail": "prerolls/thumbnails/Default/1_intro.mp4.jpg",
"tags": "holiday,christmas",
"category_id": 1,
"category": {"id": 1, "name": "Default"},
"categories": [{"id": 1, "name": "Default"}],
"description": "Christmas intro",
"duration": 30.5,
"file_size": 5242880,
"managed": true,
"upload_date": "2024-01-01T00:00:00Z"
}
]Upload a single preroll file.
Form Data:
-
file: Video file -
tags: Comma-separated tags -
category_id: Primary category ID -
category_ids: JSON array of category IDs -
description: Description text
Response:
{
"uploaded": true,
"id": 1,
"filename": "intro.mp4",
"thumbnail": "prerolls/thumbnails/Default/1_intro.mp4.jpg",
"duration": 30.5,
"file_size": 5242880,
"category_id": 1,
"categories": [{"id": 1, "name": "Default"}]
}Upload multiple preroll files.
Form Data: Same as single upload, but files is an array.
Response:
{
"total_files": 3,
"successful_uploads": 3,
"failed_uploads": 0,
"results": [...]
}Update a preroll's metadata.
Request Body:
{
"tags": ["holiday", "christmas"],
"category_id": 2,
"description": "Updated description",
"display_name": "Christmas Intro",
"new_filename": "christmas_intro.mp4"
}Delete a preroll.
List all categories.
Response:
[
{
"id": 1,
"name": "Default",
"description": "Default category",
"apply_to_plex": false,
"plex_mode": "shuffle"
}
]Create a new category.
Request Body:
{
"name": "Halloween",
"description": "Halloween themed prerolls",
"apply_to_plex": false,
"plex_mode": "shuffle"
}Update a category.
Delete a category (if not in use).
Apply category prerolls to Plex.
Query Parameters:
-
rotation_hours: Rotation interval (default: 24)
Add preroll to category.
Query Parameters:
-
set_primary: Set as primary category (default: false)
List all schedules.
Response:
[
{
"id": 1,
"name": "Holiday Schedule",
"type": "holiday",
"start_date": "2024-12-01T00:00:00Z",
"end_date": "2024-12-31T23:59:59Z",
"category_id": 2,
"shuffle": true,
"playlist": false,
"is_active": true,
"last_run": "2024-12-01T12:00:00Z",
"next_run": "2024-12-02T00:00:00Z",
"recurrence_pattern": "0 0 * * *",
"preroll_ids": "1,2,3",
"fallback_category_id": 1
}
]Create a new schedule.
Request Body:
{
"name": "Daily Rotation",
"type": "recurring",
"start_date": "2024-01-01T00:00:00Z",
"category_id": 1,
"shuffle": true,
"recurrence_pattern": "0 0 * * *",
"fallback_category_id": 1
}Update a schedule.
Delete a schedule.
Connect to Plex server.
Request Body:
{
"url": "http://192.168.1.100:32400",
"token": "your-plex-token"
}Get Plex connection status.
Response:
{
"connected": true,
"url": "http://192.168.1.100:32400",
"server_name": "My Plex Server",
"version": "1.32.0"
}Auto-discover and connect to Plex server.
Request Body:
{
"token": "your-token",
"urls": ["http://192.168.1.100:32400"],
"prefer_local": true
}Probe Plex server connectivity.
Query Parameters:
-
url: Plex server URL -
token: Optional token -
verify: TLS verification (default: true)
Connect to Jellyfin server.
Request Body:
{
"url": "http://192.168.1.100:8096",
"api_key": "your-api-key"
}Get Jellyfin connection status.
Create genre-to-category mapping.
Request Body:
{
"genre": "Horror",
"category_id": 3
}List all genre mappings.
Apply preroll by genre list.
Request Body:
{
"genres": ["Horror", "Thriller"]
}Query Parameters:
-
ttl: Override TTL in minutes (default: 15)
Apply preroll by Plex rating key (for webhooks).
Query Parameters:
-
key: Plex rating key -
ttl: Override TTL in minutes -
intercept: Enable aggressive intercept (default: false)
Get path mappings for Plex.
Response:
{
"mappings": [
{
"local": "\\\\NAS\\PreRolls",
"plex": "Z:\\PreRolls"
}
]
}Update path mappings.
Query Parameters:
-
merge: Merge with existing (default: false)
Request Body:
{
"mappings": [
{
"local": "\\\\NAS\\PreRolls",
"plex": "Z:\\PreRolls"
}
]
}Test path translations.
Request Body:
{
"paths": ["\\\\NAS\\PreRolls\\intro.mp4"]
}Get scheduler status.
Response:
{
"running": true,
"active_schedules": 2
}Start the scheduler.
Stop the scheduler.
Trigger immediate scheduler execution.
Export database to JSON.
Create ZIP archive of preroll files.
Import database from JSON backup.
Import preroll files from ZIP.
Plex webhook receiver for automatic preroll application.
Headers:
-
X-Plex-Signature: Optional signature verification
Query Parameters:
-
ttl: Override TTL in minutes -
intercept: Enable aggressive intercept
Serve preroll thumbnail (generates on-demand if missing).
Serve preroll video file.
All errors follow this format:
{
"detail": "Error description"
}Common HTTP status codes:
-
400: Bad Request -
404: Not Found -
409: Conflict (duplicate) -
422: Validation Error -
500: Internal Server Error
The API includes built-in rate limiting for most endpoints to prevent abuse.
Visit http://localhost:9393/docs for interactive API documentation with testing capabilities.