API Reference

REST API Endpoints

Base URL: Configured via BuildConfig.API_BASE_URL (default: https://tv.cadnative.com/)

All requests include these headers (configured in NetworkModule):

Accept: application/json
Content-Type: application/json
X-TV-Code: <tv_code_from_settings>

Channels

GET /api/v1/channels

Fetch all channels.

Response: ChannelsResponse

{
  "success": true,
  "data": [
    {
      "channelId": "ch_123",
      "channelName": "BBC World",
      "channelUrl": "https://stream.example.com/bbc.m3u8",
      "channelImg": "https://img.example.com/bbc.png",
      "tvgLogo": "https://img.example.com/bbc-hd.png",
      "channelGroup": "News",
      "channelDrmKey": null,
      "channelDrmType": null,
      "tvgLanguage": "en",
      "tvgCountry": "GB",
      "tvgId": "BBCWorld.uk",
      "tvgName": "BBC World News",
      "isActive": true,
      "metadata": { "language": "English" }
    }
  ]
}

GET /api/v1/channels/{id}

Fetch a single channel by ID.

Path parameter: id — Channel identifier

Response: ChannelDto (same structure as items in the channels array)

Favorites

GET /api/v1/favorites

Pull server-stored favorites on app launch. Merged with local Room favorites (server timestamp wins on conflict).

Response: FavoritesResponse

{
  "channel_ids": ["ch_123", "ch_456"],
  "timestamp": 1710500000000
}

POST /api/v1/favorites

Sync local favorites to server.

Request body: FavoritesRequest

{
  "channel_ids": ["ch_123", "ch_456"],
  "device_id": "device_abc",
  "timestamp": 1710500000000
}

Response: 204 No Content on success

Stream Health Reporting

POST /api/v1/channels/{id}/report-status

Report a stream as dead, alive, or unresponsive. Called fire-and-forget from PlayerViewModel — never blocks playback.

Path parameter: id — Channel identifier

Request body: StreamStatusReport

{
  "status": "dead",
  "deviceId": "device_abc",
  "timestamp": "2026-04-02T10:00:00Z",
  "errorMessage": "Connection refused"
}

status: "dead" (5 retries exhausted), "alive" (stream confirmed working), "unresponsive" (buffering >30 s)
Rate limited server-side: 1 report per channel per device per 5 minutes

Response: Response<Unit> (body ignored)

POST /api/v1/channels/{id}/report-play

Report a successful play event (stream produced frames for ≥10 s). Also used when an alternate stream played — the streamUrl field triggers server-side auto-promotion of that alternate to primary.

Request body: StreamPlayReport

{
  "deviceId": "device_abc",
  "timestamp": "2026-04-02T10:05:00Z",
  "proxyPlay": false,
  "streamUrl": "https://alt-stream.example.com/live.m3u8"
}

proxyPlay: true when ExoPlayer fell back to the TV proxy
streamUrl (optional): actual stream URL played; if it matches an alternate, server auto-promotes it to primary
Rate limited server-side: 1 report per channel per device per minute

Response: Response<Unit> (body ignored)

POST /api/v1/channels/health-sync

Bulk sync results from a ChannelHealthScanner batch. Called after each scan cycle.

Request body: HealthSyncRequest

{
  "deviceId": "device_abc",
  "results": [
    {
      "channelId": "ch_123",
      "status": "alive",
      "responseTimeMs": 320,
      "timestamp": "2026-04-02T10:10:00Z"
    }
  ]
}

Up to 100 results per call; server uses MongoDB bulkWrite for efficiency
Rate limited: 1 sync per device per 5 minutes

Response: Response<Unit> (body ignored)

Fallback Streams

GET /api/v1/user-playlist/me/channels-with-fallbacks

Returns the user's assigned channels, each including up to 3 alternate stream URLs. Dead and flagged alternates are filtered server-side before sending. Used by ChannelRepositoryImpl to populate the in-memory fallback slot queue in ErrorRecoveryManager.

Response: same shape as /me/channels with an extra alternateStreams array on each channel:

{
  "streamUrl": "https://alt.example.com/live.m3u8",
  "quality": "720p"
}

Playlist

GET /api/v1/playlist.m3u

Download the full channel playlist in M3U format.

Response: ResponseBody (plain text M3U content)

App Updates (Legacy ApiClient)

GET /api/v1/app/version

Check for app updates.

Query parameter: currentVersion — Current app version code (integer)

Response:

{
  "updateAvailable": true,
  "isMandatory": false,
  "versionName": "1.6",
  "versionCode": 6,
  "downloadUrl": "https://tv.cadnative.com/api/v1/app/download",
  "fileSize": 15728640,
  "releaseNotes": "Bug fixes and performance improvements"
}

GET /api/v1/app/download

Download the latest APK binary.

Device Pairing (PairingViewModel)

POST /api/v1/tv/pairing/request

Request a new pairing PIN.

Request body:

{
  "deviceId": "...",
  "deviceName": "...",
  "deviceModel": "..."
}

Response:

{
  "pin": "123456",
  "expiresAt": "2026-03-15T12:00:00Z"
}

GET /api/v1/tv/pairing/status/{pin}

Poll pairing status.

Path parameter: pin — 6-digit PIN from pairing request

Response (pending):

{
  "status": "pending"
}

Response (paired):

{
  "status": "paired",
  "channelListCode": "ABC123",
  "username": "user@example.com"
}

Repository Interfaces

ChannelRepository

fun getChannels(): Flow<Result<List<Channel>>>
fun getChannelById(id: String): Flow<Result<Channel>>
fun getChannelsByCategory(category: String): Flow<Result<List<Channel>>>
fun searchChannels(query: String): Flow<Result<List<Channel>>>
suspend fun refreshChannels(): Result<Unit>
suspend fun addToFavorites(channelId: String): Result<Unit>
suspend fun removeFromFavorites(channelId: String): Result<Unit>
fun getFavoriteChannels(): Flow<Result<List<Channel>>>

CategoryRepository

fun getCategories(): Flow<Result<List<Category>>>
fun getCategoryById(id: String): Flow<Result<Category>>
suspend fun refreshCategories(): Result<Unit>

FavoriteRepository

fun getFavoriteChannels(): Flow<Result<List<Channel>>>
fun isFavorite(channelId: String): Flow<Result<Boolean>>
suspend fun addFavorite(channelId: String): Result<Unit>
suspend fun removeFavorite(channelId: String): Result<Unit>
suspend fun toggleFavorite(channelId: String): Result<Unit>
suspend fun updateFavoriteOrder(channelId: String, newOrder: Int): Result<Unit>
suspend fun syncFavorites(): Result<Unit>
suspend fun pullFavoritesFromServer(): Result<Unit>  // pulls & merges server favorites on app launch

PlaybackRepository

fun getPlaybackPosition(channelId: String): Flow<Result<Long?>>
suspend fun savePlaybackPosition(channelId: String, position: Long, duration: Long): Result<Unit>
suspend fun deletePlaybackPosition(channelId: String): Result<Unit>
fun getAllPlaybackPositions(): Flow<Result<Map<String, Long>>>
suspend fun clearOldPositions(keepCount: Int = 100): Result<Unit>

PlaylistRepository

suspend fun parsePlaylistFromUrl(url: String): Result<List<Channel>>
suspend fun parsePlaylistFromString(content: String): Result<List<Channel>>
suspend fun importChannels(channels: List<Channel>): Result<Unit>

SearchHistoryRepository

fun getRecentSearches(limit: Int = 10): Flow<Result<List<String>>>
suspend fun saveSearch(query: String): Result<Unit>
suspend fun clearHistory(): Result<Unit>
suspend fun removeSearch(query: String): Result<Unit>

UserPreferencesRepository

fun getTheme(): Flow<String>                              // default: "dark"
suspend fun setTheme(theme: String): Result<Unit>
fun getGridSize(): Flow<Int>                              // default: 3
suspend fun setGridSize(size: Int): Result<Unit>
fun getFontSize(): Flow<Float>                            // default: 1.0f
suspend fun setFontSize(scale: Float): Result<Unit>
fun getAnimationSpeed(): Flow<Float>                      // default: 1.0f
suspend fun setAnimationSpeed(speed: Float): Result<Unit>
fun getLayoutDensity(): Flow<String>                      // default: "comfortable"
suspend fun setLayoutDensity(density: String): Result<Unit>
suspend fun clearCache(): Result<Unit>

Use Cases

Use Case	Type	Input	Output
`GetChannelsUseCase`	Flow	`Unit`	`Flow<Result<List<Channel>>>`
`GetChannelByIdUseCase`	Flow	`String` (channelId)	`Flow<Result<Channel>>`
`GetChannelsByCategoryUseCase`	Flow	`String` (category)	`Flow<Result<List<Channel>>>`
`RefreshChannelsUseCase`	Suspend	`Unit`	`Result<Unit>`
`SearchChannelsUseCase`	Flow	`Params(query, filters)`	`Flow<Result<List<Channel>>>`
`GetRecentSearchesUseCase`	Flow	`Int` (limit)	`Flow<Result<List<String>>>`
`SaveSearchQueryUseCase`	Suspend	`String` (query)	`Result<Unit>`
`ClearSearchHistoryUseCase`	Suspend	`Unit`	`Result<Unit>`
`GetFavoriteChannelsUseCase`	Flow	`Unit`	`Flow<Result<List<Channel>>>`
`ToggleFavoriteUseCase`	Suspend	`String` (channelId)	`Result<Unit>`
`ReorderFavoritesUseCase`	Suspend	`Params(channelId, newOrder)`	`Result<Unit>`
`PullFavoritesUseCase`	Suspend	`Unit`	`Result<Unit>`
`GetPlaybackPositionUseCase`	Flow	`String` (channelId)	`Flow<Result<PlaybackState?>>`
`SavePlaybackPositionUseCase`	Suspend	`Params(channelId, position, duration)`	`Result<Unit>`
`ReportStreamStatusUseCase`	Suspend	`Params(channelId, status, deviceId, errorMessage?)`	`Result<Unit>`
`ReportStreamPlayUseCase`	Suspend	`Params(channelId, deviceId, proxyPlay, streamUrl?)`	`Result<Unit>`
`SyncHealthResultsUseCase`	Suspend	`Params(deviceId, results[])`	`Result<Unit>`

Database Schema

Entity Relationship Diagram

erDiagram
    channels ||--o{ favorites : "has"
    channels ||--o| channel_health : "has"

    channels {
        TEXT id PK
        TEXT name "NOT NULL, INDEXED"
        TEXT streamUrl "NOT NULL"
        TEXT logoUrl
        TEXT categoryId "NOT NULL, INDEXED"
        TEXT language
        TEXT country
        TEXT groupTitle
        TEXT tvgId
        TEXT tvgName
        INTEGER isActive "INDEXED, default 1"
        INTEGER lastUpdated
    }

    favorites {
        INTEGER id PK "AUTOINCREMENT"
        TEXT channelId FK "INDEXED, CASCADE"
        INTEGER addedAt
        INTEGER displayOrder "default 0"
    }

    channel_health {
        TEXT channelId PK "FK, CASCADE"
        TEXT status "INDEXED"
        INTEGER lastCheckedAt "INDEXED"
        INTEGER responseTimeMs
        TEXT errorMessage
        TEXT thumbnailPath
    }

    categories {
        TEXT id PK
        TEXT name
        INTEGER displayOrder "default 0"
        INTEGER channelCount "default 0"
    }

    playback_positions {
        TEXT channelId PK
        INTEGER position
        INTEGER duration
        INTEGER lastPlayed "INDEXED"
    }

    search_history {
        INTEGER id PK "AUTOINCREMENT"
        TEXT query
        INTEGER timestamp "INDEXED"
    }

Foreign Keys

Child Table	Parent Table	Column	On Delete
`favorites`	`channels`	`channelId` → `id`	CASCADE
`channel_health`	`channels`	`channelId` → `id`	CASCADE

Indices

Table	Index	Columns
`channels`	`index_channels_categoryId`	`categoryId`
`channels`	`index_channels_isActive`	`isActive`
`channels`	`index_channels_name`	`name`
`channel_health`	`index_channel_health_channelId` (unique)	`channelId`
`channel_health`	`index_channel_health_lastCheckedAt`	`lastCheckedAt`
`channel_health`	`index_channel_health_status`	`status`
`favorites`	`index_favorites_channelId`	`channelId`
`playback_positions`	`index_playback_positions_lastPlayed`	`lastPlayed`
`search_history`	`index_search_history_timestamp`	`timestamp`

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

API Reference

REST API Endpoints

Channels

GET /api/v1/channels

GET /api/v1/channels/{id}

Categories

GET /api/v1/categories

Favorites

GET /api/v1/favorites

POST /api/v1/favorites

Stream Health Reporting

POST /api/v1/channels/{id}/report-status

POST /api/v1/channels/{id}/report-play

POST /api/v1/channels/health-sync

Fallback Streams

GET /api/v1/user-playlist/me/channels-with-fallbacks

Playlist

GET /api/v1/playlist.m3u

App Updates (Legacy ApiClient)

GET /api/v1/app/version

GET /api/v1/app/download

Device Pairing (PairingViewModel)

POST /api/v1/tv/pairing/request

GET /api/v1/tv/pairing/status/{pin}

Repository Interfaces

ChannelRepository

CategoryRepository

FavoriteRepository

PlaybackRepository

PlaylistRepository

SearchHistoryRepository

UserPreferencesRepository

Use Cases

Database Schema

Entity Relationship Diagram

Foreign Keys

Indices