thegame_1980/xtream-codes-api-documentation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
xtream-codes-api-documentation/XTREAM_CODES_API_DOCUMENTATION.md
T
worldofiptvcomandClaude Opus 4.5 28cdada37f Initial commit: Xtream Codes API Documentation 
Comprehensive API documentation for Xtream Codes IPTV Panel v2.9.2

Includes:
- Complete endpoint reference for all 8 APIs
- Request/response examples with curl commands
- Authentication methods documentation
- IPTV-specific patterns and integrations
- Data models and error codes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-24 10:08:26 +00:00

1764 lines
40 KiB
Markdown
Raw Permalink Blame History

# Xtream Codes IPTV Panel - Comprehensive API Documentation
**Version:** 2.9.2
**Analysis Date:** 2025-12-24
**Codebase Location:** /home/xtream-codes-decoded
---
## Table of Contents
1. [Overview](#overview)
2. [Base Configuration](#base-configuration)
3. [Authentication Methods](#authentication-methods)
4. [Rate Limiting & Security](#rate-limiting--security)
5. [API Categories](#api-categories)
6. [Player API Endpoints](#1-player-api-player_apiphp)
7. [Panel API Endpoints](#2-panel-api-panel_apiphp)
8. [Admin/Management API Endpoints](#3-adminmanagement-api-apiphp)
9. [System API Endpoints](#4-system-api-system_apiphp)
10. [MAG Portal API Endpoints](#5-mag-portal-api-portalphp)
11. [Enigma2 API Endpoints](#6-enigma2-api-enigma2php)
12. [Streaming Endpoints](#7-streaming-endpoints)
13. [Data Models](#data-models)
14. [Error Codes](#error-codes)
15. [Integration Guide](#integration-guide)
---
## Overview
Xtream Codes is an IPTV panel management system that provides APIs for:
- User authentication and management
- Live TV streaming
- Video on Demand (VOD/Movies)
- TV Series management
- Electronic Program Guide (EPG)
- MAG/Stalker portal support
- Enigma2 device support
- Multi-server load balancing
---
## Base Configuration
### Default Ports
| Service | Port | Protocol |
|---------|------|----------|
| HTTP | 25461 | HTTP |
| HTTPS | 25463 | HTTPS/SSL |
| MySQL | 7999 | TCP |
### Base URL Pattern
```
http://{server_ip}:{port}/
https://{server_ip}:{port}/
```
### Directory Structure
```
/home/xtreamcodes/iptv_xtream_codes/
├── wwwdir/ # Web root
│ ├── api.php # Admin API
│ ├── player_api.php # Player/Client API
│ ├── panel_api.php # Panel API
│ ├── system_api.php # System API
│ ├── portal.php # MAG Portal API
│ ├── enigma2.php # Enigma2 API
│ ├── xmltv.php # EPG/XMLTV API
│ ├── get.php # Playlist Generator
│ └── streaming/ # Streaming handlers
├── streams/ # Live stream segments
├── movies/ # VOD files
├── tv_archive/ # TV Archive/Catchup
└── tmp/ # Temporary files
```
---
## Authentication Methods
### 1. Username/Password Authentication (Most Common)
Used by: Player API, Panel API, Streaming Endpoints
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| username | string | Yes | User's login username |
| password | string | Yes | User's login password |
**Example:**
```bash
curl "http://server:25461/player_api.php?username=user1&password=pass123"
```
### 2. IP-Based Authentication (Admin API)
Used by: Admin/Management API
The Admin API restricts access based on server IP addresses. Only requests from authorized server IPs are accepted.
**Source:** `api.php:5-8`
```php
if (!in_array(ipTV_streaming::getUserIP(), array_column(ipTV_lib::$StreamingServers, 'server_ip'))) {
die;
}
```
### 3. MAC Address Authentication (MAG Portal)
Used by: MAG Portal API
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| mac | string | Yes | Device MAC address |
| sn | string | No | Serial number |
| stb_type | string | No | STB device type |
| ver | string | No | Firmware version |
### 4. Token-Based Authentication (HLS/Stalker)
Used for secure HLS streaming and MAG device sessions.
**Token Generation:**
- Handshake generates a random token: `strtoupper(md5(uniqid(rand(), true)))`
- Token stored in database and sent to device
- Required in Authorization header: `Authorization: Bearer {token}`
---
## Rate Limiting & Security
### Nginx Rate Limiting
**Source:** `nginx/conf/nginx.conf:34`
```nginx
limit_req_zone $binary_remote_addr zone=one:10m rate=20r/s;
```
- **Rate:** 20 requests per second per IP
- **Burst:** Configured per location
- **Zone:** 10MB shared memory
### Flood Protection
Failed authentication attempts trigger flood protection:
- Tracked in database `blocked_ips` table
- Configurable block duration
- Implemented via `CheckFlood()` function
### GeoIP Restrictions
- Uses MaxMind GeoLite2 database
- Per-user country restrictions
- Global allowed countries list
- ISP-based restrictions
### User Agent Validation
- Empty user agents can be blocked
- Per-user allowed user agent lists
- Global blocked user agent patterns
---
## API Categories
| Category | Endpoint | Authentication | Purpose |
|----------|----------|----------------|---------|
| Player API | `/player_api.php` | Username/Password | Client apps, media players |
| Panel API | `/panel_api.php` | Username/Password | Panel applications |
| Admin API | `/api.php` | IP-Based | Server management |
| System API | `/system_api.php` | IP-Based | Inter-server communication |
| MAG Portal | `/portal.php` | MAC/Token | MAG/Stalker devices |
| Enigma2 | `/enigma2.php` | Username/Password | Enigma2 receivers |
| EPG/XMLTV | `/xmltv.php` | Username/Password | Program guide data |
| Playlist | `/get.php` | Username/Password | M3U playlist generation |
| Live Streaming | `/live/...` | Username/Password | Live TV streams |
| VOD Streaming | `/movie/...` | Username/Password | Movie/VOD streams |
| Series Streaming | `/series/...` | Username/Password | TV series streams |
| Timeshift | `/timeshift/...` | Username/Password | Catch-up TV |
---
## 1. Player API (`player_api.php`)
**Source:** `wwwdir/player_api.php`
The Player API is the primary interface for client applications (IPTV players, mobile apps).
### Authentication
```
GET /player_api.php?username={username}&password={password}
```
### Default Action (User & Server Info)
Returns user account information and server details.
**Request:**
```bash
curl "http://server:25461/player_api.php?username=user1&password=pass123"
```
**Response:**
```json
{
"user_info": {
"username": "user1",
"password": "pass123",
"message": "Welcome message",
"auth": 1,
"status": "Active",
"exp_date": "1735689600",
"is_trial": "0",
"active_cons": "1",
"created_at": "1609459200",
"max_connections": "2",
"allowed_output_formats": ["ts", "m3u8"]
},
"server_info": {
"url": "http://server.example.com",
"port": "25461",
"https_port": "25463",
"server_protocol": "http",
"rtmp_port": "25462",
"timezone": "Europe/London",
"timestamp_now": 1735084800,
"time_now": "2025-12-24 12:00:00"
}
}
```
**Source:** `player_api.php:110-153`
---
### GET Live Categories
**Action ID:** 201
**Request:**
```bash
curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_live_categories"
```
**Response:**
```json
[
{
"category_id": "1",
"category_name": "Sports",
"parent_id": 0
},
{
"category_id": "2",
"category_name": "Movies",
"parent_id": 0
}
]
```
**Source:** `player_api.php:24-28`
---
### GET Live Streams
**Action ID:** 202
**Request:**
```bash
curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_live_streams"
# Optional: Filter by category
curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_live_streams&category_id=1"
```
**Response:**
```json
[
{
"num": 1,
"name": "Channel Name",
"stream_type": "live",
"stream_id": 123,
"stream_icon": "http://example.com/icon.png",
"epg_channel_id": "channel.epg",
"added": "1609459200",
"category_id": "1",
"custom_sid": "",
"tv_archive": 1,
"direct_source": "",
"tv_archive_duration": 7
}
]
```
**Source:** `player_api.php:29-33`
---
### GET VOD Categories
**Action ID:** 200
**Request:**
```bash
curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_vod_categories"
```
**Response:**
```json
[
{
"category_id": "10",
"category_name": "Action",
"parent_id": 0
}
]
```
---
### GET VOD Streams
**Action ID:** 203
**Request:**
```bash
curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_vod_streams"
# Optional: Filter by category
curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_vod_streams&category_id=10"
```
**Response:**
```json
[
{
"num": 1,
"name": "Movie Title",
"stream_type": "movie",
"stream_id": 456,
"stream_icon": "http://example.com/poster.jpg",
"rating": "8.5",
"rating_5based": 4.25,
"added": "1609459200",
"category_id": "10",
"container_extension": "mkv",
"custom_sid": "",
"direct_source": ""
}
]
```
---
### GET VOD Info
**Action ID:** 209
**Request:**
```bash
curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_vod_info&vod_id=456"
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| vod_id | integer | Yes | Movie/VOD stream ID |
**Response:**
```json
{
"info": {
"movie_image": "http://example.com/poster.jpg",
"tmdb_id": "12345",
"backdrop_path": ["http://example.com/backdrop.jpg"],
"youtube_trailer": "dQw4w9WgXcQ",
"genre": "Action, Adventure",
"plot": "Movie description...",
"cast": "Actor 1, Actor 2",
"rating": "8.5",
"director": "Director Name",
"releasedate": "2025-01-01",
"duration_secs": 7200,
"duration": "02:00:00"
},
"movie_data": {
"stream_id": 456,
"name": "Movie Title",
"added": "1609459200",
"category_id": "10",
"container_extension": "mkv"
}
}
```
**Source:** `player_api.php:60-76`
---
### GET Series Categories
**Action ID:** 206
**Request:**
```bash
curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_series_categories"
```
**Response:**
```json
[
{
"category_id": "20",
"category_name": "Drama",
"parent_id": 0
}
]
```
---
### GET Series
**Action ID:** 208
**Request:**
```bash
curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_series"
# Optional: Filter by category
curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_series&category_id=20"
```
**Response:**
```json
[
{
"num": 1,
"name": "Series Title",
"series_id": 789,
"cover": "http://example.com/cover.jpg",
"plot": "Series description...",
"cast": "Actor 1, Actor 2",
"director": "Director Name",
"genre": "Drama",
"releaseDate": "2025-01-01",
"last_modified": "1609459200",
"rating": "9.0",
"rating_5based": 4.5,
"backdrop_path": ["http://example.com/backdrop.jpg"],
"youtube_trailer": "abc123",
"episode_run_time": "45",
"category_id": "20"
}
]
```
---
### GET Series Info
**Action ID:** 204
**Request:**
```bash
curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_series_info&series_id=789"
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| series_id | integer | Yes | Series ID |
**Response:**
```json
{
"seasons": [
{
"air_date": "2025-01-01",
"episode_count": 10,
"id": 1,
"name": "Season 1",
"overview": "Season description...",
"season_number": 1,
"cover": "http://example.com/season1.jpg",
"cover_big": "http://example.com/season1_big.jpg"
}
],
"info": {
"name": "Series Title",
"cover": "http://example.com/cover.jpg",
"plot": "Series description...",
"cast": "Actor 1, Actor 2",
"director": "Director Name",
"genre": "Drama",
"releaseDate": "2025-01-01",
"last_modified": "1609459200",
"rating": "9.0",
"rating_5based": 4.5,
"backdrop_path": ["http://example.com/backdrop.jpg"],
"youtube_trailer": "abc123",
"episode_run_time": "45",
"category_id": "20"
},
"episodes": {
"1": [
{
"id": "1001",
"episode_num": 1,
"title": "Episode 1 Title",
"container_extension": "mkv",
"info": {
"movie_image": "http://example.com/ep1.jpg",
"plot": "Episode description...",
"releasedate": "2025-01-01",
"rating": "8.5",
"duration_secs": 2700,
"duration": "00:45:00"
}
}
]
}
}
```
**Source:** `player_api.php:39-54`
---
### GET Short EPG
**Action ID:** 205
**Request:**
```bash
curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_short_epg&stream_id=123"
# Optional: Limit results
curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_short_epg&stream_id=123&limit=5"
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| stream_id | integer | Yes | Live stream ID |
| limit | integer | No | Number of EPG entries (default: 4) |
**Response:**
```json
{
"epg_listings": [
{
"id": "12345",
"epg_id": "67",
"title": "Program Title",
"lang": "en",
"start": "2025-12-24 12:00:00",
"end": "2025-12-24 13:00:00",
"description": "Program description...",
"channel_id": "channel.epg",
"start_timestamp": 1735041600,
"stop_timestamp": 1735045200,
"now_playing": 1,
"has_archive": 1
}
]
}
```
**Source:** `player_api.php:55-58`
---
### GET Simple Data Table
**Action ID:** 207
**Request:**
```bash
curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_simple_data_table&stream_id=123"
```
Returns EPG data in a simplified table format.
---
## 2. Panel API (`panel_api.php`)
**Source:** `wwwdir/panel_api.php`
The Panel API provides comprehensive data for panel applications with all content in a single response.
### Default Action (Full Data)
Returns complete user info, server info, and all available content.
**Request:**
```bash
curl "http://server:25461/panel_api.php?username=user1&password=pass123"
```
**Response:**
```json
{
"user_info": {
"username": "user1",
"password": "pass123",
"message": "",
"auth": 1,
"status": "Active",
"exp_date": "1735689600",
"is_trial": "0",
"active_cons": "1",
"created_at": "1609459200",
"max_connections": "2",
"allowed_output_formats": ["ts", "m3u8"]
},
"server_info": {
"url": "http://server.example.com",
"port": "25461",
"https_port": "25463",
"server_protocol": "http",
"rtmp_port": "25462",
"timezone": "Europe/London",
"timestamp_now": 1735084800,
"time_now": "2025-12-24 12:00:00"
},
"categories": {
"live": [...],
"movie": [...],
"series": [...]
},
"available_channels": [...]
}
```
**Source:** `panel_api.php:44-98`
---
### GET EPG
**Request:**
```bash
curl "http://server:25461/panel_api.php?username=user1&password=pass123&action=get_epg&stream_id=123"
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| stream_id | integer | Yes | Live stream ID |
**Response:**
```json
{
"epg_listings": [
{
"id": "12345",
"epg_id": "67",
"title": "Program Title",
"lang": "en",
"start": "2025-12-24 12:00:00",
"end": "2025-12-24 13:00:00",
"description": "Program description...",
"channel_id": "channel.epg"
}
]
}
```
**Source:** `panel_api.php:16-42`
---
## 3. Admin/Management API (`api.php`)
**Source:** `wwwdir/api.php`
**Important:** This API is IP-restricted. Only requests from authorized streaming server IPs are accepted.
### Authentication
No username/password required - authentication is IP-based.
---
### List Servers
**Request:**
```bash
curl "http://server:25461/api.php?action=server&sub=list"
```
**Response:**
```json
{
"servers": [
{
"id": 1,
"server_name": "Main Server",
"server_ip": "192.168.1.1",
"vpn_ip": null,
"http_broadcast_port": "25461",
"total_clients": 100,
"status": "online"
}
]
}
```
**Source:** `api.php:14-20`
---
### Stream Control
#### Start Stream
```bash
curl "http://server:25461/api.php?action=stream&sub=start&stream_id=123"
```
#### Stop Stream
```bash
curl "http://server:25461/api.php?action=stream&sub=stop&stream_id=123"
```
#### List Streams
```bash
curl "http://server:25461/api.php?action=stream&sub=list"
```
#### Get Online Streams
```bash
curl "http://server:25461/api.php?action=stream&sub=online"
```
#### Get Offline Streams
```bash
curl "http://server:25461/api.php?action=stream&sub=offline"
```
**Source:** `api.php:40-76`
---
### VOD Control
#### Start VOD Encoding
```bash
curl "http://server:25461/api.php?action=vod&sub=start&stream_id=456"
```
#### Stop VOD Encoding
```bash
curl "http://server:25461/api.php?action=vod&sub=stop&stream_id=456"
```
**Source:** `api.php:21-39`
---
### User Management
#### Get User Info
```bash
curl "http://server:25461/api.php?action=user&sub=info&user_id=100"
# Or by username
curl "http://server:25461/api.php?action=user&sub=info&username=user1"
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| user_id | integer | Yes* | User ID |
| username | string | Yes* | Username (alternative to user_id) |
**Response:**
```json
{
"user_info": {
"user_id": 100,
"username": "user1",
"password": "pass123",
"exp_date": 1735689600,
"max_connections": 2,
"is_restreamer": 0,
"is_trial": 0,
"created_at": 1609459200,
"created_by": 1,
"admin_enabled": 1,
"enabled": 1,
"bouquet": [1, 2, 3],
"allowed_ips": [],
"allowed_ua": [],
"forced_country": "ALL"
}
}
```
**Source:** `api.php:92-131`
---
#### Create User
```bash
curl -X POST "http://server:25461/api.php" \
-d "action=user" \
-d "sub=create" \
-d "username=newuser" \
-d "password=newpass" \
-d "max_connections=2" \
-d "exp_date=1735689600" \
-d "bouquet=[1,2,3]" \
-d "reseller_id=5"
```
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| username | string | Yes | New username |
| password | string | Yes | Password |
| max_connections | integer | No | Max simultaneous connections |
| exp_date | integer | No | Expiration timestamp (null = never) |
| bouquet | array/json | No | Bouquet IDs |
| reseller_id | integer | No | Owner reseller ID |
| is_restreamer | integer | No | 0=normal user, 1=restreamer |
| is_trial | integer | No | 0=paid, 1=trial |
| allowed_ips | array | No | Allowed IP addresses |
| allowed_ua | array | No | Allowed user agents |
| forced_country | string | No | Country code restriction |
**Response:**
```json
{
"result": true,
"user_id": 101,
"username": "newuser"
}
```
**Source:** `api.php:160-223`
---
#### Edit User
```bash
curl -X POST "http://server:25461/api.php" \
-d "action=user" \
-d "sub=edit" \
-d "user_id=100" \
-d "max_connections=3" \
-d "exp_date=1767225600"
```
**Parameters:**
Same as Create User, plus:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| user_id | integer | Yes | User ID to edit |
**Source:** `api.php:132-159`
---
### STB (MAG Device) Management
#### Get STB Info
```bash
curl "http://server:25461/api.php?action=stb&sub=info&mag_id=50"
# Or by MAC address
curl "http://server:25461/api.php?action=stb&sub=info&mac=00:1A:79:XX:XX:XX"
```
#### Create STB
```bash
curl -X POST "http://server:25461/api.php" \
-d "action=stb" \
-d "sub=create" \
-d "mac=00:1A:79:XX:XX:XX" \
-d "user_id=100"
```
#### Edit STB
```bash
curl -X POST "http://server:25461/api.php" \
-d "action=stb" \
-d "sub=edit" \
-d "mag_id=50" \
-d "user_id=101"
```
**Source:** `api.php:224-294`
---
### Reseller Management
#### List Resellers
```bash
curl "http://server:25461/api.php?action=reg_user&sub=list"
```
#### Get Reseller Credits
```bash
curl "http://server:25461/api.php?action=reg_user&sub=credits&reg_user_id=5"
```
**Source:** `api.php:77-91`
---
## 4. System API (`system_api.php`)
**Source:** `wwwdir/system_api.php`
Internal API for server-to-server communication. IP-restricted.
### Save Opened Connections
```bash
curl -X POST "http://server:25461/system_api.php" \
-d "action=save_opened_cons" \
-d "data={json_encoded_connections}"
```
### Save Closed Connections
```bash
curl -X POST "http://server:25461/system_api.php" \
-d "action=save_closed_cons" \
-d "data={json_encoded_connections}"
```
### Kill Connection
```bash
curl "http://server:25461/system_api.php?action=pid_kill&activity_id=12345"
```
### Redirect Connection
```bash
curl "http://server:25461/system_api.php?action=pid_redirect&activity_id=12345&stream_id=456"
```
### Get Active Connections
```bash
curl "http://server:25461/system_api.php?action=get_active_cons&server_id=1"
```
**Source:** `system_api.php:1-80`
---
## 5. MAG Portal API (`portal.php`)
**Source:** `wwwdir/portal.php`
Stalker/MAG middleware portal API for MAG set-top boxes.
### Handshake
**Request:**
```bash
curl "http://server:25461/portal.php?type=stb&action=handshake&mac=00:1A:79:XX:XX:XX"
```
**Response:**
```json
{
"js": {
"token": "A1B2C3D4E5F6..."
}
}
```
**Source:** `portal.php:29-38`
---
### Get Profile
**Request:**
```bash
curl "http://server:25461/portal.php?type=stb&action=get_profile" \
-H "Authorization: Bearer {token}" \
-H "Cookie: mac=00:1A:79:XX:XX:XX"
```
**Response:**
```json
{
"js": {
"id": 1,
"name": "MAG Device",
"mac": "00:1A:79:XX:XX:XX",
"status": 0,
"hd": "1",
"locale": "en_GB.utf8",
"default_timezone": "Europe/London",
"allowed_stb_types": ["MAG250", "MAG254", "MAG322"],
"watchdog_timeout": 100,
...
}
}
```
**Source:** `portal.php:64-90`
---
### Get Modules
**Request:**
```bash
curl "http://server:25461/portal.php?type=stb&action=get_modules"
```
**Response:**
```json
{
"js": {
"all_modules": ["tv", "vclub", "sclub", "radio", "apps", ...],
"disabled_modules": ["karaoke", "game.mastermind", ...],
"template": "default"
}
}
```
**Source:** `portal.php:97-99`
---
### ITV (Live TV) Actions
#### Get Genres (Categories)
```bash
curl "http://server:25461/portal.php?type=itv&action=get_genres"
```
#### Get Ordered List (Channels)
```bash
curl "http://server:25461/portal.php?type=itv&action=get_ordered_list"
# With filters
curl "http://server:25461/portal.php?type=itv&action=get_ordered_list&genre=1&sortby=number&fav=1"
```
#### Get All Channels
```bash
curl "http://server:25461/portal.php?type=itv&action=get_all_channels"
```
#### Create Link (Generate Stream URL)
```bash
curl "http://server:25461/portal.php?type=itv&action=create_link&cmd=http://localhost/ch/123"
```
**Response:**
```json
{
"js": {
"id": 123,
"cmd": "ffmpeg http://server:25461/live/user/pass/123.ts"
}
}
```
**Source:** `portal.php:293-309`
#### Get Short EPG
```bash
curl "http://server:25461/portal.php?type=itv&action=get_short_epg&ch_id=123"
```
#### Get EPG Info (Full)
```bash
curl "http://server:25461/portal.php?type=itv&action=get_epg_info&period=3"
```
#### Set Favorite
```bash
curl "http://server:25461/portal.php?type=itv&action=set_fav&fav_ch=123,456,789"
```
#### Get Favorite IDs
```bash
curl "http://server:25461/portal.php?type=itv&action=get_fav_ids"
```
**Source:** `portal.php:291-474`
---
### VOD Actions
#### Get Categories
```bash
curl "http://server:25461/portal.php?type=vod&action=get_categories"
```
#### Get Ordered List
```bash
curl "http://server:25461/portal.php?type=vod&action=get_ordered_list"
# With filters
curl "http://server:25461/portal.php?type=vod&action=get_ordered_list&category=10&sortby=added&search=action"
```
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| category | integer | Filter by category ID |
| sortby | string | Sort by: added, name, rating, year |
| search | string | Search query |
| abc | string | Filter by first letter |
| genre | string | Filter by genre |
| years | string | Filter by year |
| fav | integer | Show favorites only (1) |
#### Create Link (VOD)
```bash
curl "http://server:25461/portal.php?type=vod&action=create_link&cmd={base64_encoded_cmd}"
```
**Source:** `portal.php:503-626`
---
### Series Actions
#### Get Categories
```bash
curl "http://server:25461/portal.php?type=series&action=get_categories"
```
#### Get Ordered List
```bash
curl "http://server:25461/portal.php?type=series&action=get_ordered_list"
```
**Source:** `portal.php:628-699`
---
### Watchdog Actions
#### Get Events
```bash
curl "http://server:25461/portal.php?type=watchdog&action=get_events"
```
**Response:**
```json
{
"js": {
"data": {
"msgs": 1,
"id": 123,
"event": "send_msg",
"msg": "Welcome message",
"need_confirm": 1,
"auto_hide_timeout": 0
}
}
}
```
#### Confirm Event
```bash
curl "http://server:25461/portal.php?type=watchdog&action=confirm_event&event_active_id=123"
```
**Source:** `portal.php:103-131`
---
### STB Settings Actions
#### Set Volume
```bash
curl "http://server:25461/portal.php?type=stb&action=set_volume&vol=70"
```
#### Set Locale
```bash
curl "http://server:25461/portal.php?type=stb&action=set_locale&locale=en_GB.utf8"
```
#### Set Parent Password
```bash
curl "http://server:25461/portal.php?type=stb&action=set_parent_password&pass=1234&repeat_pass=1234"
```
#### Get Settings Profile
```bash
curl "http://server:25461/portal.php?type=stb&action=get_settings_profile"
```
**Source:** `portal.php:140-274`
---
## 6. Enigma2 API (`enigma2.php`)
**Source:** `wwwdir/enigma2.php`
XML-based API for Enigma2 satellite receivers.
### Authentication
```
GET /enigma2.php?username={username}&password={password}&type={action}
```
### Default (Main Menu)
**Request:**
```bash
curl "http://server:25461/enigma2.php?username=user1&password=pass123"
```
**Response (XML):**
```xml
<?xml version="1.0" encoding="utf-8"?>
<items>
<playlist_name>Provider Name</playlist_name>
<category>
<category_id>1</category_id>
<category_title>Provider Name</category_title>
</category>
<channel>
<title>TGl2ZSBTdHJlYW1z</title>
<description>TGl2ZSBTdHJlYW1zIENhdGVnb3J5</description>
<category_id>0</category_id>
<playlist_url><![CDATA[http://server/enigma2.php?username=user1&password=pass123&type=get_live_categories]]></playlist_url>
</channel>
<channel>
<title>Vm9k</title>
<description>VmlkZW8gT24gRGVtYW5kIENhdGVnb3J5</description>
<category_id>1</category_id>
<playlist_url><![CDATA[http://server/enigma2.php?username=user1&password=pass123&type=get_vod_categories]]></playlist_url>
</channel>
<channel>
<title>VFYgU2VyaWVz</title>
<description>VFYgU2VyaWVzIENhdGVnb3J5</description>
<category_id>2</category_id>
<playlist_url><![CDATA[http://server/enigma2.php?username=user1&password=pass123&type=get_series_categories]]></playlist_url>
</channel>
</items>
```
**Note:** Titles and descriptions are Base64 encoded.
**Source:** `enigma2.php:289-319`
---
### Get Live Categories
```bash
curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_live_categories"
```
### Get Live Streams
```bash
curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_live_streams&cat_id=1"
```
### Get VOD Categories
```bash
curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_vod_categories"
```
### Get VOD Streams
```bash
curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_vod_streams&cat_id=10"
```
### Get Series Categories
```bash
curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_series_categories"
```
### Get Series
```bash
curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_series&cat_id=20"
```
### Get Seasons
```bash
curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_seasons&series_id=789"
```
### Get Series Streams (Episodes)
```bash
curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_series_streams&series_id=789&season=1"
```
**Source:** `enigma2.php:41-288`
---
## 7. Streaming Endpoints
### Live Streaming
**URL Patterns:**
```
/live/{username}/{password}/{stream_id}.{extension}
/{username}/{password}/{stream_id} (new rewrite format)
```
**Supported Extensions:**
| Extension | MIME Type | Description |
|-----------|-----------|-------------|
| ts | video/mp2t | MPEG Transport Stream |
| m3u8 | application/x-mpegurl | HLS Playlist |
**Source:** `streaming/clients_live.php`
**Request:**
```bash
# Direct TS stream
curl "http://server:25461/live/user1/pass123/123.ts" -o stream.ts
# HLS playlist
curl "http://server:25461/live/user1/pass123/123.m3u8"
```
**HLS Response:**
```m3u
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:3
#EXT-X-MEDIA-SEQUENCE:1000
#EXTINF:3.0,
/live/user1/pass123/123_1000.ts?token=abc123
#EXTINF:3.0,
/live/user1/pass123/123_1001.ts?token=def456
```
---
### VOD/Movie Streaming
**URL Pattern:**
```
/movie/{username}/{password}/{stream_id}.{extension}
```
**Supported Extensions:**
| Extension | MIME Type |
|-----------|-----------|
| mp4 | video/mp4 |
| mkv | video/x-matroska |
| avi | video/x-msvideo |
| 3gp | video/3gpp |
| flv | video/x-flv |
| wmv | video/x-ms-wmv |
| mov | video/quicktime |
| ts | video/mp2t |
**Source:** `streaming/clients_movie.php`
**Request:**
```bash
curl "http://server:25461/movie/user1/pass123/456.mkv" -o movie.mkv
```
**Range Requests Supported:**
```bash
curl "http://server:25461/movie/user1/pass123/456.mkv" \
-H "Range: bytes=0-1048575" -o part1.mkv
```
---
### Series Streaming
**URL Pattern:**
```
/series/{username}/{password}/{stream_id}.{extension}
```
Same behavior as VOD streaming.
---
### Timeshift/Catchup Streaming
**URL Pattern:**
```
/timeshift/{username}/{password}/{duration}/{start}/{stream_id}
```
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| username | string | User login |
| password | string | User password |
| duration | integer | Duration in minutes |
| start | string | Start time (format: YYYY-MM-DD:HH-MM or YYYYMMDD-HH) |
| stream_id | integer | Live stream ID |
**Source:** `streaming/timeshift.php`
**Examples:**
```bash
# Get last 60 minutes from channel 123
curl "http://server:25461/timeshift/user1/pass123/60/2025-12-24:10-00/123"
# HLS format
curl "http://server:25461/timeshift/user1/pass123/60/2025-12-24:10-00/123.m3u8"
```
---
### HLS Segment Streaming
**URL Pattern:**
```
/hls/{username}/{password}/{stream_id}/{segment}
```
Used internally by HLS playlists for segment delivery.
---
## 8. EPG/XMLTV API (`xmltv.php`)
**Source:** `wwwdir/xmltv.php`
### Get XMLTV EPG Data
**Request:**
```bash
curl "http://server:25461/xmltv.php?username=user1&password=pass123"
# With date range
curl "http://server:25461/xmltv.php?username=user1&password=pass123&prev_days=1&next_days=3"
```
**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| username | string | - | User login |
| password | string | - | User password |
| prev_days | integer | 1 | Days of past EPG data |
| next_days | integer | 1 | Days of future EPG data |
**Response (XML):**
```xml
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE tv SYSTEM "xmltv.dtd">
<tv generator-info-name="Server Name" generator-info-url="http://server:25461/">
<channel id="channel.epg">
<display-name>Channel Name</display-name>
<icon src="http://example.com/icon.png"/>
</channel>
<programme start="20251224120000 +0000" stop="20251224130000 +0000" channel="channel.epg">
<title>Program Title</title>
<desc>Program description...</desc>
</programme>
</tv>
```
---
## 9. Playlist Generator (`get.php`)
**Source:** `wwwdir/get.php`
### Generate M3U Playlist
**Request:**
```bash
curl "http://server:25461/get.php?username=user1&password=pass123&type=m3u_plus&output=ts"
```
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| username | string | User login |
| password | string | User password |
| type | string | Playlist type: m3u_plus, m3u, m3u8 |
| output | string | Stream format: ts, m3u8, rtmp |
**Response (M3U):**
```m3u
#EXTM3U
#EXTINF:-1 tvg-id="channel.epg" tvg-name="Channel Name" tvg-logo="http://example.com/icon.png" group-title="Sports",Channel Name
http://server:25461/live/user1/pass123/123.ts
#EXTINF:-1 tvg-id="" tvg-name="Movie Title" tvg-logo="http://example.com/poster.jpg" group-title="Action",Movie Title
http://server:25461/movie/user1/pass123/456.mkv
```
---
## Data Models
### User Object
```json
{
"id": 100,
"username": "user1",
"password": "pass123",
"exp_date": 1735689600,
"max_connections": 2,
"is_restreamer": 0,
"is_trial": 0,
"created_at": 1609459200,
"created_by": 1,
"admin_enabled": 1,
"enabled": 1,
"bouquet": [1, 2, 3],
"allowed_ips": [],
"allowed_ua": [],
"forced_country": "ALL",
"pair_id": null,
"isp_desc": null,
"bypass_ua": 0
}
```
### Stream Object (Live)
```json
{
"id": 123,
"stream_display_name": "Channel Name",
"stream_icon": "http://example.com/icon.png",
"category_id": 1,
"channel_id": "channel.epg",
"epg_id": 67,
"tv_archive": 1,
"tv_archive_duration": 7,
"direct_source": 0,
"stream_source": null
}
```
### Stream Object (VOD)
```json
{
"id": 456,
"stream_display_name": "Movie Title",
"stream_icon": "http://example.com/poster.jpg",
"category_id": 10,
"target_container": "mkv",
"movie_properties": {
"movie_image": "http://example.com/poster.jpg",
"tmdb_id": "12345",
"genre": "Action",
"plot": "Description...",
"cast": "Actor 1, Actor 2",
"rating": "8.5",
"director": "Director Name",
"releasedate": "2025-01-01",
"duration": "02:00:00"
}
}
```
### Series Object
```json
{
"id": 789,
"title": "Series Title",
"category_id": 20,
"plot": "Series description...",
"cast": "Actor 1, Actor 2",
"director": "Director Name",
"genre": "Drama",
"release_date": "2025-01-01",
"rating": "9.0",
"cover": "http://example.com/cover.jpg",
"backdrop_path": "http://example.com/backdrop.jpg",
"youtube_trailer": "abc123"
}
```
### MAG Device Object
```json
{
"mag_id": 50,
"user_id": 100,
"mac": "00:1A:79:XX:XX:XX",
"sn": "ABC123456",
"stb_type": "MAG254",
"ver": "218",
"image_version": "1.0.0",
"token": "A1B2C3D4...",
"locale": "en_GB.utf8",
"parent_password": "0000",
"volume": 70,
"last_watchdog": 1735084800
}
```
### EPG Entry Object
```json
{
"id": 12345,
"epg_id": 67,
"channel_id": "channel.epg",
"title": "UHJvZ3JhbSBUaXRsZQ==",
"description": "UHJvZ3JhbSBkZXNjcmlwdGlvbi4uLg==",
"start": "2025-12-24 12:00:00",
"end": "2025-12-24 13:00:00",
"start_timestamp": 1735041600,
"stop_timestamp": 1735045200
}
```
**Note:** Title and description are Base64 encoded in the database.
---
## Error Codes
### HTTP Status Codes
| Code | Meaning | Scenarios |
|------|---------|-----------|
| 200 | Success | Request completed successfully |
| 206 | Partial Content | Range request for VOD |
| 400 | Bad Request | Missing required parameters |
| 401 | Unauthorized | Authentication failed, user expired/banned |
| 403 | Forbidden | Access denied (IP/token mismatch) |
| 404 | Not Found | Resource/file not found |
| 405 | Method Not Allowed | Extension not allowed for user |
| 406 | Not Acceptable | Stream not in user's bouquet |
| 416 | Range Not Satisfiable | Invalid range request |
### Client Log Codes
| Code | Description |
|------|-------------|
| AUTH_FAILED | Invalid username/password |
| USER_EXPIRED | User subscription expired |
| USER_BAN | User banned by admin |
| USER_DISABLED | User account disabled |
| USER_ALREADY_CONNECTED | Max connections reached |
| NOT_IN_BOUQUET | Stream not in user's bouquet |
| IP_BAN | IP not in allowed list |
| COUNTRY_DISALLOW | Country not allowed |
| USER_AGENT_BAN | User agent not allowed |
| EMPTY_UA | Empty user agent blocked |
| ISP_LOCK_FAILED | ISP restriction failed |
| CON_SVP | Connection from server/VPN |
| CRACKED | Known cracked IP detected |
| MAG_TOKEN_INVALID | Invalid MAG device token |
| STALKER_KEY_EXPIRED | Stalker key expired |
| STALKER_IP_MISMATCH | IP changed during session |
| USER_DISALLOW_EXT | Extension not allowed |
---
## Integration Guide
### Quick Start - Player App Integration
#### 1. Authenticate and get user info
```bash
curl "http://server:25461/player_api.php?username=USER&password=PASS"
```
#### 2. Get live categories
```bash
curl "http://server:25461/player_api.php?username=USER&password=PASS&action=get_live_categories"
```
#### 3. Get channels by category
```bash
curl "http://server:25461/player_api.php?username=USER&password=PASS&action=get_live_streams&category_id=1"
```
#### 4. Play a stream
```bash
# Direct play
ffplay "http://server:25461/live/USER/PASS/123.ts"
# HLS
ffplay "http://server:25461/live/USER/PASS/123.m3u8"
```
### MAG Device Integration
#### 1. Handshake
```bash
curl "http://server:25461/portal.php?type=stb&action=handshake&mac=00:1A:79:XX:XX:XX"
```
#### 2. Store token and add to all subsequent requests
```bash
curl "http://server:25461/portal.php?type=stb&action=get_profile" \
-H "Authorization: Bearer TOKEN" \
-H "Cookie: mac=00:1A:79:XX:XX:XX"
```
#### 3. Get channels
```bash
curl "http://server:25461/portal.php?type=itv&action=get_all_channels" \
-H "Authorization: Bearer TOKEN"
```
### Code Examples
#### Python - Get Live Streams
```python
import requests
server = "http://server:25461"
username = "user1"
password = "pass123"
# Authenticate
response = requests.get(f"{server}/player_api.php", params={
"username": username,
"password": password
})
user_info = response.json()
if user_info.get("user_info", {}).get("auth") == 1:
# Get live categories
categories = requests.get(f"{server}/player_api.php", params={
"username": username,
"password": password,
"action": "get_live_categories"
}).json()
# Get live streams
streams = requests.get(f"{server}/player_api.php", params={
"username": username,
"password": password,
"action": "get_live_streams"
}).json()
for stream in streams:
print(f"{stream['name']}: {server}/live/{username}/{password}/{stream['stream_id']}.ts")
```
#### JavaScript - Get VOD Info
```javascript
async function getVODInfo(server, username, password, vodId) {
const url = new URL(`${server}/player_api.php`);
url.searchParams.set('username', username);
url.searchParams.set('password', password);
url.searchParams.set('action', 'get_vod_info');
url.searchParams.set('vod_id', vodId);
const response = await fetch(url);
return await response.json();
}
// Usage
const vodInfo = await getVODInfo('http://server:25461', 'user1', 'pass123', 456);
console.log(vodInfo.info.plot);
console.log(`Play: http://server:25461/movie/user1/pass123/${vodInfo.movie_data.stream_id}.${vodInfo.movie_data.container_extension}`);
```
#### cURL - Admin Create User
```bash
curl -X POST "http://server:25461/api.php" \
-d "action=user" \
-d "sub=create" \
-d "username=newuser" \
-d "password=securepass123" \
-d "max_connections=2" \
-d 'bouquet=[1,2,3,4,5]' \
-d "exp_date=1767225600" \
-d "reseller_id=1"
```
---
## Appendix: File Reference
| File | Location | Purpose |
|------|----------|---------|
| api.php | wwwdir/api.php | Admin/Management API |
| player_api.php | wwwdir/player_api.php | Player/Client API |
| panel_api.php | wwwdir/panel_api.php | Panel API |
| system_api.php | wwwdir/system_api.php | Internal System API |
| portal.php | wwwdir/portal.php | MAG Portal API |
| enigma2.php | wwwdir/enigma2.php | Enigma2 API |
| xmltv.php | wwwdir/xmltv.php | EPG/XMLTV API |
| get.php | wwwdir/get.php | Playlist Generator |
| clients_live.php | wwwdir/streaming/ | Live Stream Handler |
| clients_movie.php | wwwdir/streaming/ | VOD Stream Handler |
| timeshift.php | wwwdir/streaming/ | Timeshift Handler |
| init.php | wwwdir/init.php | Bootstrap/Initialization |
| functions.php | wwwdir/includes/ | Helper Functions |
| lib.php | wwwdir/includes/ | Core Library |
| streaming.php | wwwdir/includes/ | Streaming Functions |
| mysql.php | wwwdir/includes/ | Database Layer |
---
*Documentation generated from source code analysis of Xtream Codes v2.9.2*
Reference in New Issue View Git Blame Copy Permalink