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