API Overview

Introduction to the Dispatcharr REST API for managing IPTV streams, channels, EPG data, and more

Dispatcharr provides a comprehensive REST API for programmatic access to all platform features. The API enables you to manage streams, channels, EPG data, recordings, user accounts, and system settings.

Base URL

All API endpoints are served under the /api/ path:

http://your-server:8000/api/

The API base path includes a trailing slash. Both /api and /api/ are valid, with automatic redirects in place.

API Structure

The Dispatcharr API is organized into the following modules:

Core Modules

• /api/accounts/ - User authentication, API keys, user management, and permissions
• /api/channels/ - Channel management, streams, logos, groups, and profiles
• /api/epg/ - Electronic Program Guide data and management
• /api/m3u/ - M3U playlist accounts and configuration
• /api/core/ - Core settings, user agents, and stream profiles

Additional Modules

• /api/hdhr/ - HDHomeRun integration endpoints
• /api/vod/ - Video-on-Demand content management
• /api/backups/ - System backup and restore operations
• /api/connect/ - Client connection management
• /api/plugins/ - Plugin system integration

Response Format

All API responses use JSON format with consistent structure:

Success Response

{
  "id": 1,
  "name": "Example Channel",
  "channel_number": "100",
  "enabled": true
}

List Response (Paginated)

{
  "count": 150,
  "next": "http://your-server:8000/api/channels/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Channel 1",
      "channel_number": "100"
    },
    {
      "id": 2,
      "name": "Channel 2",
      "channel_number": "101"
    }
  ]
}

Error Response

{
  "detail": "Authentication credentials were not provided."
}

Or for validation errors:

{
  "channel_number": [
    "This field is required."
  ],
  "name": [
    "Ensure this field has no more than 255 characters."
  ]
}

HTTP Status Codes

The API uses standard HTTP status codes:

Code	Description
200 OK	Request succeeded
201 Created	Resource successfully created
204 No Content	Request succeeded with no response body (typically DELETE)
400 Bad Request	Invalid request data or parameters
401 Unauthorized	Authentication required or failed
403 Forbidden	Authenticated but lacking required permissions
404 Not Found	Resource not found
500 Internal Server Error	Server-side error occurred

Interactive API Documentation

Dispatcharr includes interactive API documentation powered by Swagger UI and ReDoc:

Swagger UI

Access the interactive Swagger UI at:

http://your-server:8000/api/swagger/

Swagger UI provides:

• Full endpoint documentation with request/response schemas
• Try-it-out functionality to test endpoints directly
• Authentication support (JWT tokens and API keys)
• Request/response examples

ReDoc

Access the alternative ReDoc documentation at:

http://your-server:8000/api/redoc/

ReDoc offers a clean, three-panel reading experience ideal for comprehensive API exploration.

OpenAPI Schema

Download the raw OpenAPI 3.0 schema:

http://your-server:8000/api/schema/
http://your-server:8000/api/swagger.json

The OpenAPI schema can be imported into tools like Postman, Insomnia, or used to generate client libraries.

Common API Patterns

ViewSet Endpoints

Most resources use Django REST Framework ViewSets with standard CRUD operations:

• GET /api/resource/ - List all resources (paginated)
• POST /api/resource/ - Create a new resource
• GET /api/resource/{id}/ - Retrieve a specific resource
• PUT /api/resource/{id}/ - Update a resource (full)
• PATCH /api/resource/{id}/ - Partially update a resource
• DELETE /api/resource/{id}/ - Delete a resource

Filtering and Search

Many list endpoints support filtering via query parameters:

# Filter channels by group
GET /api/channels/?channel_group=5

# Search streams by name
GET /api/channels/streams/?search=sports

# Filter by multiple criteria
GET /api/channels/streams/?m3u_account=1&enabled=true

Pagination

List endpoints return paginated results by default:

# Get page 2 of results
GET /api/channels/?page=2

# Adjust page size (if supported)
GET /api/channels/?page_size=50

Example Requests

Here are some common API operations:

List All Channels

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://your-server:8000/api/channels/

Create a Channel

curl -X POST \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HBO",
    "channel_number": "500",
    "enabled": true
  }' \
  http://your-server:8000/api/channels/

Update a Channel

curl -X PATCH \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}' \
  http://your-server:8000/api/channels/123/

Delete a Channel

curl -X DELETE \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://your-server:8000/api/channels/123/

Rate Limiting

While Dispatcharr does not currently enforce API rate limits, be mindful of server resources when making bulk operations or frequent requests. Consider implementing exponential backoff for failed requests.

WebSocket Support

Dispatcharr provides real-time updates via WebSockets for certain events. WebSocket connections use the same authentication mechanism as the REST API. See the WebSocket documentation for details on available channels and event formats.

Next Steps

• Authentication - Learn how to authenticate API requests
• Interactive API Docs - Explore all available endpoints