REST API - Teamarr

All endpoints are prefixed with /api/v1/ unless otherwise noted. The API base URL is http://<host>:9195.

Interactive API docs are available at http://<host>:9195/docs (Swagger UI) and http://<host>:9195/redoc (ReDoc) when the container is running.

Health

`GET /health`

Health check with startup state. No /api/v1/ prefix — this endpoint is always available, even during startup.

status

string

"healthy" when fully started, "starting" during startup phases.

version

string

Application version string.

startup

object

Startup phase info including phase (e.g., READY, REFRESHING_CACHE) and is_ready boolean.

Example response (healthy)

{
  "status": "healthy",
  "version": "2.3.1",
  "startup": { "phase": "READY", "is_ready": true }
}

EPG

`POST /api/v1/epg/generate`

Run a full EPG generation. Handles M3U refresh, team and event group processing, XMLTV output, Dispatcharr integration, channel lifecycle, and reconciliation. Returns 409 if a generation is already running.

programmes_count

integer

Total XMLTV programmes generated.

teams_processed

integer

Number of team EPGs processed.

duration_seconds

float

Total generation time.

run_id

integer

Processing run ID for stats lookup.

match_stats

object

Stream matching summary: streams_fetched, streams_matched, streams_unmatched, match_rate.

`GET /api/v1/epg/generate/stream`

Run EPG generation with real-time progress via Server-Sent Events. Connect with EventSource. The generation starts immediately — the stream delivers progress updates and a final status event. Returns 409 via SSE if already running.

`GET /api/v1/epg/generate/status`

Poll current EPG generation progress. Use this if SSE is not available.

in_progress

boolean

Whether generation is currently running.

status

string

starting | progress | complete | error | idle

percent

integer

Progress percentage (0–100). Monotonically increasing.

phase

string

Current phase: teams, groups, saving, complete.

message

string

Human-readable progress message.

`POST /api/v1/epg/generate/cancel`

Request cancellation of the running generation. The run stops at the next phase boundary. Returns 409 if no generation is in progress.

`GET /api/v1/epg/xmltv`

Serve the most recently generated XMLTV file. Returns application/xml. Use this URL as the EPG source in Dispatcharr: http://<host>:9195/api/v1/epg/xmltv.

`GET /api/v1/epg/analysis`

Analyze the current EPG for issues. Returns channel counts (team vs event), programme counts by type (events, pregame, postgame, idle), date range, unreplaced template variables, and coverage gaps between programmes.

`GET /api/v1/epg/content`

Return raw XMLTV content as text for preview.

max_lines

integer

default:"2000"

Maximum lines to return. Set to 0 for the full file (up to 100,000 lines).

`GET /api/v1/epg/match-stats`

Get stream matching statistics summary for a generation run.

run_id

integer

Processing run ID. Defaults to the latest run.

`GET /api/v1/epg/matched-streams`

List streams that were successfully matched to events in a generation run.

run_id

integer

Processing run ID (defaults to latest).

group_id

integer

Filter by event group ID.

limit

integer

default:"500"

Max results (1–10,000).

`GET /api/v1/epg/failed-matches`

List streams that failed to match in a generation run. Failure reasons: unmatched, excluded_league, exception.

reason

string

Filter by failure reason.

`GET /api/v1/epg/events/search`

Search events for use in the manual match correction UI.

league

string

Filter by league code (e.g., nfl, nba).

team

string

Search by team name (partial match).

target_date

string

Date in YYYY-MM-DD format. Defaults to today.

`POST /api/v1/epg/streams/correct`

Manually correct an incorrect or failed stream match. User corrections are never auto-purged and take priority over algorithmic matching.

`DELETE /api/v1/epg/streams/correct/{group_id}/{stream_id}`

Remove a user correction. The stream will be re-matched algorithmically on the next generation.

`GET /api/v1/epg/streams/corrections`

List all user-corrected stream matches.

group_id

integer

Filter by group ID.

`POST /api/v1/epg/streams/match`

Batch match streams to events using the fingerprint cache. Returns match results, cache hit rate, and per-stream details.

`GET /api/v1/game-data-cache/stats`

Get statistics for the game data cache (schedules, scores, event data from providers).

`POST /api/v1/game-data-cache/clear`

Clear the game data cache. Forces fresh data from ESPN and TheSportsDB on the next generation. Does not affect the Team & League Directory or stream match cache.

Teams

`GET /api/v1/teams`

List all teams.

active_only

boolean

default:"false"

Return only active teams.

`POST /api/v1/teams`

Create a new team. Returns 409 if the channel_id or provider/team_id/sport combination already exists.

`GET /api/v1/teams/{team_id}`

Get a single team by ID.

`PUT /api/v1/teams/{team_id}` / `PATCH /api/v1/teams/{team_id}`

Full or partial update of a team.

`DELETE /api/v1/teams/{team_id}`

Delete a team and its associated XMLTV content. Returns 204.

`POST /api/v1/teams/bulk-import`

Bulk import teams from the cache. Handles soccer consolidation (same team, multiple competitions) and deduplication.

Request body

{
  "teams": [
    {
      "team_name": "Chicago Bulls",
      "team_abbrev": "CHI",
      "provider": "espn",
      "provider_team_id": "4",
      "league": "nba",
      "sport": "basketball",
      "logo_url": "https://..."
    }
  ]
}

imported

integer

New teams created.

updated

integer

Teams that had new leagues added.

skipped

integer

Teams already in the database, unchanged.

`POST /api/v1/teams/bulk-channel-id`

Bulk update channel IDs using a format template. Supported variables: {team_name_pascal}, {team_abbrev}, {team_name}, {provider_team_id}, {league_id}, {league}, {sport}.

Event groups

`GET /api/v1/groups`

List all event EPG groups.

include_disabled

boolean

default:"false"

Include disabled groups.

include_stats

boolean

default:"false"

Include per-group channel counts.

`POST /api/v1/groups`

`GET /api/v1/groups/{group_id}`

Get a single group by ID.

`PUT /api/v1/groups/{group_id}` / `PATCH /api/v1/groups/{group_id}`

Update a group. Use clear_* boolean flags to explicitly set nullable fields to NULL (e.g., clear_stream_timezone: true).

`DELETE /api/v1/groups/{group_id}`

Delete a group and its channels. Returns 204.

`POST /api/v1/groups/bulk`

Create multiple groups from M3U groups in a single request.

`PUT /api/v1/groups/bulk`

Apply shared settings to multiple groups at once.

`POST /api/v1/groups/{group_id}/preview`

Test stream matching for a group without persisting results. Returns match details for inspection.

Channels

All channel endpoints are under /api/v1/channels/.

`GET /api/v1/channels/managed`

List all managed channels tracked by Teamarr.

group_id

integer

Filter by source group.

sport

string

Filter by sport (e.g., basketball).

league

string

Filter by league code (e.g., nba).

include_deleted

boolean

default:"false"

Include channels marked as deleted.

`GET /api/v1/channels/managed/{channel_id}`

Get a single managed channel by its Teamarr DB ID.

`DELETE /api/v1/channels/managed/{channel_id}`

Delete a managed channel. Removes from Dispatcharr (if configured) and marks as deleted in the DB.

`GET /api/v1/channels/pending-deletions`

List channels that are past their scheduled delete time and waiting for deletion.

`GET /api/v1/channels/history/{channel_id}`

Get the history of changes for a managed channel.

`POST /api/v1/channels/sync`

Trigger lifecycle sync: create channels that are due and delete expired channels. Requires Dispatcharr to be configured.

`GET /api/v1/channels/reconciliation/status`

Detect inconsistencies between the local DB and Dispatcharr without making changes. Returns issues by type: orphan_teamarr, orphan_dispatcharr, duplicate, drift.

`POST /api/v1/channels/reconciliation/fix`

Run reconciliation with optional auto-fix.

auto_fix

boolean

default:"false"

Automatically fix issues flagged as auto_fixable.

`GET /api/v1/channels/reset`

Preview all Teamarr-created channels (teamarr-event-* tvg_id) that would be deleted by a reset.

`POST /api/v1/channels/reset`

Delete all Teamarr-created channels from Dispatcharr and clear the managed channels table. Destructive. Returns 409 if EPG generation is in progress.

`DELETE /api/v1/channels/dispatcharr/{channel_id}`

Delete a channel directly from Dispatcharr by its Dispatcharr ID. Use this for orphan channels that exist in Dispatcharr but are not tracked by Teamarr.

Templates

`GET /api/v1/templates`

List all templates with usage counts.

`POST /api/v1/templates`

Create a new template. Returns 409 if the name already exists.

`GET /api/v1/templates/{template_id}`

Get a template by ID with all JSON fields parsed.

`PUT /api/v1/templates/{template_id}`

Update a template.

`DELETE /api/v1/templates/{template_id}`

Delete a template. Returns 204.

Variables

`GET /api/v1/variables`

Get all template variables grouped by category. Returns 197 variables across 17 categories, each with name, description, and supported suffixes (base, .next, .last).

`GET /api/v1/variables/samples`

Get sample values for all variables for a given sport. Used for live preview in the template form.

sport

string

default:"NBA"

Sport to generate samples for (e.g., NBA, NFL, NHL).

`GET /api/v1/variables/conditions`

Get available conditions for conditional descriptions.

template_type

string

default:"team"

team returns all conditions. event returns only combat sports conditions.

Settings

`GET /api/v1/settings`

Get all application settings in a single response, organized into sections.

Show Response sections

Section	Key fields
`dispatcharr`	`enabled`, `url`, `username`, `epg_id`, `default_channel_group_id`, `default_channel_profile_ids`, `default_stream_profile_id`
`lifecycle`	`channel_create_timing`, `channel_delete_timing`, `channel_pre_buffer_minutes`, `channel_post_buffer_minutes`
`reconciliation`	`reconcile_on_epg_generation`, `auto_fix_orphan_teamarr`, `auto_fix_duplicates`
`scheduler`	`enabled`, `interval_minutes`, `cron_expression`
`epg`	`team_schedule_days_ahead`, `event_match_days_ahead`, `epg_output_days_ahead`, `epg_timezone`
`durations`	Per-sport event duration defaults (basketball, football, hockey, baseball, soccer, mma, golf)
`display`	`time_format`, `channel_id_format`, `tsdb_api_key`
`channel_numbering`	`global_channel_mode`, `channel_numbering_mode`, `league_channel_starts`
`stream_ordering`	`rules` array (type, value, priority)
`feed_separation`	`enabled`, `home_terms`, `away_terms`, `detect_team_names`
`update_check`	`enabled`, `notify_stable`, `notify_dev`

Section-specific GET and PATCH endpoints

Each settings section has its own endpoint for targeted reads and updates:

Section	GET	PATCH
Dispatcharr	`GET /api/v1/settings/dispatcharr`	`PATCH /api/v1/settings/dispatcharr`
Lifecycle	`GET /api/v1/settings/lifecycle`	`PATCH /api/v1/settings/lifecycle`
EPG	`GET /api/v1/settings/epg`	`PATCH /api/v1/settings/epg`
Display	`GET /api/v1/settings/display`	`PATCH /api/v1/settings/display`
Channel numbering	`GET /api/v1/settings/channel-numbering`	`PATCH /api/v1/settings/channel-numbering`
Stream ordering	`GET /api/v1/settings/stream-ordering`	`PATCH /api/v1/settings/stream-ordering`
Feed separation	`GET /api/v1/settings/feed-separation`	`PATCH /api/v1/settings/feed-separation`
Update check	`GET /api/v1/settings/update-check`	`PATCH /api/v1/settings/update-check`
Team filter	`GET /api/v1/settings/team-filter`	`PATCH /api/v1/settings/team-filter`
Emby	`GET /api/v1/settings/emby`	`PATCH /api/v1/settings/emby`

Cache

The team and league cache (/api/v1/cache/) stores provider data for the Team Importer and stream matching.

`GET /api/v1/cache/status`

Get cache statistics: last refresh time, league and team counts, staleness, and whether a refresh is in progress.

`POST /api/v1/cache/refresh`

Trigger a full cache refresh from all providers with SSE progress streaming. Connect with EventSource.

`GET /api/v1/cache/refresh/status`

Poll cache refresh progress (alternative to SSE).

`GET /api/v1/cache/leagues`

List all available leagues.

sport

string

Filter by sport (e.g., soccer).

provider

string

Filter by provider (espn, tsdb, etc.).

import_only

boolean

default:"false"

Return only import-enabled leagues.

`GET /api/v1/cache/teams/search`

Search for teams in the cache by name.

string

required

Search query — minimum 2 characters.

league

string

Filter by league slug.

sport

string

Filter by sport.

`GET /api/v1/cache/leagues/{league_slug}/teams`

Get all teams for a specific league.

`GET /api/v1/cache/candidate-leagues`

Find leagues where both teams exist. Used by the event matching engine.

team1

string

required

First team name.

team2

string

required

Second team name.

`GET /api/v1/cache/sports`

Get all sport codes and their display names.

Dispatcharr

All Dispatcharr endpoints require Dispatcharr to be configured and reachable. They return 503 if the connection is unavailable.

`GET /api/v1/dispatcharr/m3u-accounts`

List all M3U accounts from Dispatcharr.

`GET /api/v1/dispatcharr/m3u-accounts/{account_id}/groups`

List M3U channel groups that have streams from a specific account.

`GET /api/v1/dispatcharr/m3u-accounts/{account_id}/groups/{group_id}/streams`

List streams in a specific M3U group, sorted with natural ordering (ESPN+ 2 before ESPN+ 10).

`GET /api/v1/dispatcharr/channel-groups`

List Dispatcharr channel groups for channel assignment.

exclude_m3u

boolean

default:"true"

Exclude groups originating from M3U accounts.

`POST /api/v1/dispatcharr/channel-groups`

Create a new channel group in Dispatcharr.

name

string

required

Group name.

`GET /api/v1/dispatcharr/channel-profiles`

List all channel profiles from Dispatcharr.

`POST /api/v1/dispatcharr/channel-profiles`

Create a new channel profile in Dispatcharr.

`GET /api/v1/dispatcharr/stream-profiles`

List all stream profiles (ffmpeg, VLC, proxy, etc.) from Dispatcharr.

Stats

`GET /api/v1/stats`

Get current aggregate stats: run counts, stream matching rates, channel lifecycle stats, programme counts by type, and last 24-hour summary.

`GET /api/v1/stats/dashboard`

Get stats organized for the dashboard’s four quadrants: Teams, Event Groups, EPG, and Channels.

`GET /api/v1/stats/live`

Get live game statistics from the EPG. Parses the stored XMLTV to calculate games today and events currently in progress.

epg_type

string

Filter by team or event.

`GET /api/v1/stats/history`

Get daily stats history for charting.

days

integer

default:"7"

Number of days of history (1–90).

`GET /api/v1/stats/runs`

Get recent processing runs.

limit

integer

default:"50"

Max runs to return (1–500).

run_type

string

Filter by run type.

status

string

Filter by status.

`GET /api/v1/stats/runs/{run_id}`

Get a specific processing run by ID.

`DELETE /api/v1/stats/runs/cleanup`

Delete processing runs older than N days.

days

integer

default:"30"

Delete runs older than this many days (1–365).

`DELETE /api/v1/stats/runs`

Delete all processing run history.

Settings — Dispatcharr connection test

`POST /api/v1/settings/dispatcharr/test`

Test the Dispatcharr connection with optional credential overrides. Returns connection status, Dispatcharr version, and account/group/channel counts.

Request body (all fields optional)

{
  "url": "http://dispatcharr:9999",
  "username": "admin",
  "password": "secret"
}

success

boolean

Whether the connection succeeded.

version

string

Dispatcharr version string.

error

string

Error message on failure.

Template Variables

Supported Leagues

Data Providers

Architecture & Deployment

​Health

​GET /health

​EPG

​POST /api/v1/epg/generate

​GET /api/v1/epg/generate/stream

​GET /api/v1/epg/generate/status

​POST /api/v1/epg/generate/cancel

​GET /api/v1/epg/xmltv

​GET /api/v1/epg/analysis

​GET /api/v1/epg/content

​GET /api/v1/epg/match-stats

​GET /api/v1/epg/matched-streams

​GET /api/v1/epg/failed-matches

​GET /api/v1/epg/events/search

​POST /api/v1/epg/streams/correct

​DELETE /api/v1/epg/streams/correct/{group_id}/{stream_id}

​GET /api/v1/epg/streams/corrections

​POST /api/v1/epg/streams/match

​GET /api/v1/game-data-cache/stats

​POST /api/v1/game-data-cache/clear

​Teams

​GET /api/v1/teams

​POST /api/v1/teams

​GET /api/v1/teams/{team_id}

​PUT /api/v1/teams/{team_id} / PATCH /api/v1/teams/{team_id}

​DELETE /api/v1/teams/{team_id}

​POST /api/v1/teams/bulk-import

​POST /api/v1/teams/bulk-channel-id

​Event groups

​GET /api/v1/groups

​POST /api/v1/groups

​GET /api/v1/groups/{group_id}

​PUT /api/v1/groups/{group_id} / PATCH /api/v1/groups/{group_id}

​DELETE /api/v1/groups/{group_id}

​POST /api/v1/groups/bulk

​PUT /api/v1/groups/bulk

​POST /api/v1/groups/{group_id}/preview

​Channels

​GET /api/v1/channels/managed

​GET /api/v1/channels/managed/{channel_id}

​DELETE /api/v1/channels/managed/{channel_id}

​GET /api/v1/channels/pending-deletions

​GET /api/v1/channels/history/{channel_id}

​POST /api/v1/channels/sync

​GET /api/v1/channels/reconciliation/status

​POST /api/v1/channels/reconciliation/fix

​GET /api/v1/channels/reset

​POST /api/v1/channels/reset

​DELETE /api/v1/channels/dispatcharr/{channel_id}

​Templates

​GET /api/v1/templates

​POST /api/v1/templates

​GET /api/v1/templates/{template_id}

​PUT /api/v1/templates/{template_id}

​DELETE /api/v1/templates/{template_id}

​Variables

​GET /api/v1/variables

​GET /api/v1/variables/samples

​GET /api/v1/variables/conditions

​Settings

​GET /api/v1/settings

​Section-specific GET and PATCH endpoints

​Cache

​GET /api/v1/cache/status

​POST /api/v1/cache/refresh

​GET /api/v1/cache/refresh/status

​GET /api/v1/cache/leagues

​GET /api/v1/cache/teams/search

​GET /api/v1/cache/leagues/{league_slug}/teams

​GET /api/v1/cache/candidate-leagues

​GET /api/v1/cache/sports

​Dispatcharr

​GET /api/v1/dispatcharr/m3u-accounts

​GET /api/v1/dispatcharr/m3u-accounts/{account_id}/groups

​GET /api/v1/dispatcharr/m3u-accounts/{account_id}/groups/{group_id}/streams

​GET /api/v1/dispatcharr/channel-groups

Health

`GET /health`

EPG

`POST /api/v1/epg/generate`

`GET /api/v1/epg/generate/stream`

`GET /api/v1/epg/generate/status`

`POST /api/v1/epg/generate/cancel`

`GET /api/v1/epg/xmltv`

`GET /api/v1/epg/analysis`

`GET /api/v1/epg/content`

`GET /api/v1/epg/match-stats`

`GET /api/v1/epg/matched-streams`

`GET /api/v1/epg/failed-matches`

`GET /api/v1/epg/events/search`

`POST /api/v1/epg/streams/correct`

`DELETE /api/v1/epg/streams/correct/{group_id}/{stream_id}`

`GET /api/v1/epg/streams/corrections`

`POST /api/v1/epg/streams/match`

`GET /api/v1/game-data-cache/stats`

`POST /api/v1/game-data-cache/clear`

Teams

`GET /api/v1/teams`

`POST /api/v1/teams`

`GET /api/v1/teams/{team_id}`

`PUT /api/v1/teams/{team_id}` / `PATCH /api/v1/teams/{team_id}`

`DELETE /api/v1/teams/{team_id}`

`POST /api/v1/teams/bulk-import`

`POST /api/v1/teams/bulk-channel-id`

Event groups

`GET /api/v1/groups`

`POST /api/v1/groups`

`GET /api/v1/groups/{group_id}`

`PUT /api/v1/groups/{group_id}` / `PATCH /api/v1/groups/{group_id}`

`DELETE /api/v1/groups/{group_id}`

`POST /api/v1/groups/bulk`

`PUT /api/v1/groups/bulk`

`POST /api/v1/groups/{group_id}/preview`

Channels

`GET /api/v1/channels/managed`

`GET /api/v1/channels/managed/{channel_id}`

`DELETE /api/v1/channels/managed/{channel_id}`

`GET /api/v1/channels/pending-deletions`

`GET /api/v1/channels/history/{channel_id}`

`POST /api/v1/channels/sync`

`GET /api/v1/channels/reconciliation/status`

`POST /api/v1/channels/reconciliation/fix`

`GET /api/v1/channels/reset`

`POST /api/v1/channels/reset`

`DELETE /api/v1/channels/dispatcharr/{channel_id}`

Templates

`GET /api/v1/templates`

`POST /api/v1/templates`

`GET /api/v1/templates/{template_id}`

`PUT /api/v1/templates/{template_id}`

`DELETE /api/v1/templates/{template_id}`

Variables

`GET /api/v1/variables`

`GET /api/v1/variables/samples`

`GET /api/v1/variables/conditions`

Settings

`GET /api/v1/settings`

Section-specific GET and PATCH endpoints

Cache

`GET /api/v1/cache/status`

`POST /api/v1/cache/refresh`

`GET /api/v1/cache/refresh/status`

`GET /api/v1/cache/leagues`

`GET /api/v1/cache/teams/search`

`GET /api/v1/cache/leagues/{league_slug}/teams`

`GET /api/v1/cache/candidate-leagues`

`GET /api/v1/cache/sports`

Dispatcharr

`GET /api/v1/dispatcharr/m3u-accounts`

`GET /api/v1/dispatcharr/m3u-accounts/{account_id}/groups`

`GET /api/v1/dispatcharr/m3u-accounts/{account_id}/groups/{group_id}/streams`

`GET /api/v1/dispatcharr/channel-groups`

`POST /api/v1/dispatcharr/channel-groups`

`GET /api/v1/dispatcharr/channel-profiles`

`POST /api/v1/dispatcharr/channel-profiles`

`GET /api/v1/dispatcharr/stream-profiles`