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

40 KiB
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
  2. Base Configuration
  3. Authentication Methods
  4. Rate Limiting & Security
  5. API Categories
  6. Player API Endpoints
  7. Panel API Endpoints
  8. Admin/Management API Endpoints
  9. System API Endpoints
  10. MAG Portal API Endpoints
  11. Enigma2 API Endpoints
  12. Streaming Endpoints
  13. Data Models
  14. Error Codes
  15. 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:

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

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

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:

curl "http://server:25461/player_api.php?username=user1&password=pass123"

Response:

{
  "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:

curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_live_categories"

Response:

[
  {
    "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:

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:

[
  {
    "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:

curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_vod_categories"

Response:

[
  {
    "category_id": "10",
    "category_name": "Action",
    "parent_id": 0
  }
]

GET VOD Streams

Action ID: 203

Request:

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:

[
  {
    "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:

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:

{
  "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:

curl "http://server:25461/player_api.php?username=user1&password=pass123&action=get_series_categories"

Response:

[
  {
    "category_id": "20",
    "category_name": "Drama",
    "parent_id": 0
  }
]

GET Series

Action ID: 208

Request:

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:

[
  {
    "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:

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:

{
  "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:

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:

{
  "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:

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:

curl "http://server:25461/panel_api.php?username=user1&password=pass123"

Response:

{
  "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:

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:

{
  "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:

curl "http://server:25461/api.php?action=server&sub=list"

Response:

{
  "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

curl "http://server:25461/api.php?action=stream&sub=start&stream_id=123"

Stop Stream

curl "http://server:25461/api.php?action=stream&sub=stop&stream_id=123"

List Streams

curl "http://server:25461/api.php?action=stream&sub=list"

Get Online Streams

curl "http://server:25461/api.php?action=stream&sub=online"

Get Offline Streams

curl "http://server:25461/api.php?action=stream&sub=offline"

Source: api.php:40-76

VOD Control

Start VOD Encoding

curl "http://server:25461/api.php?action=vod&sub=start&stream_id=456"

Stop VOD Encoding

curl "http://server:25461/api.php?action=vod&sub=stop&stream_id=456"

Source: api.php:21-39

User Management

Get User Info

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:

{
  "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

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:

{
  "result": true,
  "user_id": 101,
  "username": "newuser"
}

Source: api.php:160-223

Edit User

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

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

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

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

curl "http://server:25461/api.php?action=reg_user&sub=list"

Get Reseller Credits

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

curl -X POST "http://server:25461/system_api.php" \
  -d "action=save_opened_cons" \
  -d "data={json_encoded_connections}"

Save Closed Connections

curl -X POST "http://server:25461/system_api.php" \
  -d "action=save_closed_cons" \
  -d "data={json_encoded_connections}"

Kill Connection

curl "http://server:25461/system_api.php?action=pid_kill&activity_id=12345"

Redirect Connection

curl "http://server:25461/system_api.php?action=pid_redirect&activity_id=12345&stream_id=456"

Get Active Connections

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:

curl "http://server:25461/portal.php?type=stb&action=handshake&mac=00:1A:79:XX:XX:XX"

Response:

{
  "js": {
    "token": "A1B2C3D4E5F6..."
  }
}

Source: portal.php:29-38

Get Profile

Request:

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:

{
  "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:

curl "http://server:25461/portal.php?type=stb&action=get_modules"

Response:

{
  "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)

curl "http://server:25461/portal.php?type=itv&action=get_genres"

Get Ordered List (Channels)

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

curl "http://server:25461/portal.php?type=itv&action=get_all_channels"

Create Link (Generate Stream URL)

curl "http://server:25461/portal.php?type=itv&action=create_link&cmd=http://localhost/ch/123"

Response:

{
  "js": {
    "id": 123,
    "cmd": "ffmpeg http://server:25461/live/user/pass/123.ts"
  }
}

Source: portal.php:293-309

Get Short EPG

curl "http://server:25461/portal.php?type=itv&action=get_short_epg&ch_id=123"

Get EPG Info (Full)

curl "http://server:25461/portal.php?type=itv&action=get_epg_info&period=3"

Set Favorite

curl "http://server:25461/portal.php?type=itv&action=set_fav&fav_ch=123,456,789"

Get Favorite IDs

curl "http://server:25461/portal.php?type=itv&action=get_fav_ids"

Source: portal.php:291-474

VOD Actions

Get Categories

curl "http://server:25461/portal.php?type=vod&action=get_categories"

Get Ordered List

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)

curl "http://server:25461/portal.php?type=vod&action=create_link&cmd={base64_encoded_cmd}"

Source: portal.php:503-626

Series Actions

Get Categories

curl "http://server:25461/portal.php?type=series&action=get_categories"

Get Ordered List

curl "http://server:25461/portal.php?type=series&action=get_ordered_list"

Source: portal.php:628-699

Watchdog Actions

Get Events

curl "http://server:25461/portal.php?type=watchdog&action=get_events"

Response:

{
  "js": {
    "data": {
      "msgs": 1,
      "id": 123,
      "event": "send_msg",
      "msg": "Welcome message",
      "need_confirm": 1,
      "auto_hide_timeout": 0
    }
  }
}

Confirm Event

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

curl "http://server:25461/portal.php?type=stb&action=set_volume&vol=70"

Set Locale

curl "http://server:25461/portal.php?type=stb&action=set_locale&locale=en_GB.utf8"

Set Parent Password

curl "http://server:25461/portal.php?type=stb&action=set_parent_password&pass=1234&repeat_pass=1234"

Get Settings Profile

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:

curl "http://server:25461/enigma2.php?username=user1&password=pass123"

Response (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

curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_live_categories"

Get Live Streams

curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_live_streams&cat_id=1"

Get VOD Categories

curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_vod_categories"

Get VOD Streams

curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_vod_streams&cat_id=10"

Get Series Categories

curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_series_categories"

Get Series

curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_series&cat_id=20"

Get Seasons

curl "http://server:25461/enigma2.php?username=user1&password=pass123&type=get_seasons&series_id=789"

Get Series Streams (Episodes)

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:

# 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:

#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:

curl "http://server:25461/movie/user1/pass123/456.mkv" -o movie.mkv

Range Requests Supported:

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:

# 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:

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 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:

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):

#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

{
  "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)

{
  "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)

{
  "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

{
  "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

{
  "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

{
  "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

curl "http://server:25461/player_api.php?username=USER&password=PASS"

2. Get live categories

curl "http://server:25461/player_api.php?username=USER&password=PASS&action=get_live_categories"

3. Get channels by category

curl "http://server:25461/player_api.php?username=USER&password=PASS&action=get_live_streams&category_id=1"

4. Play a stream

# 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

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

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

curl "http://server:25461/portal.php?type=itv&action=get_all_channels" \
  -H "Authorization: Bearer TOKEN"

Code Examples

Python - Get Live Streams

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

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

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