Xtream API Endpoints and Response Formats Explained

Xtream-compatible IPTV servers share a common request-and-response pattern that players use to retrieve content listings, account information, and programme guide data. This pattern is not defined by an official published specification — it emerged from community documentation and widespread adoption of a common server implementation. Because there is no authoritative standard, what one server supports may differ from another, and response field names and structures can vary between providers and server versions.

What Makes an API Xtream-Compatible?

The term "Xtream-compatible" describes servers that respond to a particular style of HTTP request originally associated with a widely used server platform. Over time, other server implementations adopted the same pattern, making it a de facto convention in the IPTV space. A player labelled as Xtream-compatible is designed to work with servers that follow this convention — but compatibility is not guaranteed across every provider, and servers may only partially implement the pattern.

From the player's perspective, Xtream compatibility means being able to retrieve a structured list of available content using a known set of request parameters. The server returns data in a format the player can parse and present as a channel or content library. How much of the pattern a given server implements depends on the software it runs and how it has been configured.

The Common Base Request Pattern

In many Xtream-compatible implementations, API requests are made to a single endpoint path — commonly referred to as the player API path — with the username, password, and a named action passed as query parameters. A typical request might look like the following:

https://HOST:PORT/player_api.php?username=USERNAME&password=PASSWORD&action=ACTION_NAME

HOST and PORT refer to the server address and port provided by the IPTV service. USERNAME and PASSWORD are the account credentials. ACTION_NAME is a string that tells the server what kind of data to return — such as a channel list, a content category, or account details. The specific actions a server accepts, and the exact path it uses for them, depend on the server implementation.

Account and Server Information

One of the first requests a player typically makes after receiving credentials is one that retrieves account and server information. This commonly returns details such as whether the account is active, any expiry information associated with it, and technical information about the server such as the server's public address and the streaming formats it offers. This information helps the player configure itself before requesting content.

The following is a simplified example of the kind of data this request commonly returns. Actual field names, values, and structure vary between server implementations:

{
  "user_info": {
    "auth": 1,
    "status": "Active",
    "exp_date": "1800000000",
    "max_connections": "2",
    "active_cons": "1"
  },
  "server_info": {
    "url": "HOST",
    "port": "PORT",
    "https_port": "PORT",
    "server_protocol": "https",
    "rtmp_port": "PORT",
    "timezone": "UTC",
    "timestamp_now": 1700000000
  }
}

Fields such as expiry date and connection limits are common in practice but are not guaranteed to appear on every server. A player may use the presence or absence of particular fields to determine how to display account status information.

Live TV Endpoints

Live TV content is typically organised using two separate requests: one that retrieves the list of available categories, and one that retrieves the channels within those categories. Two action values are commonly observed in implementations that follow this pattern: get_live_categories returns the category list, and get_live_streams returns the channel entries — optionally filtered by a category identifier. These action names are not part of a published standard and may not be present or functional on all servers.

• A categories request returns a list of named groups, each with an identifier that can be used to filter channel results.
• A streams request returns channel entries, each typically including a stream identifier, a display name, and an icon URL where one has been configured.
• Each channel entry commonly includes a numeric stream ID that is used to construct the playback URL.
• Some servers include additional fields such as the channel's EPG identifier, which can be used to associate programme guide data with the channel.

The data returned for each channel can vary considerably. One server may include detailed metadata for every channel; another may return only the minimum fields needed for playback. Robust Xtream-compatible clients should be prepared for missing, null, or unexpected fields.

VOD and Series Endpoints

On-demand content follows a similar category-then-items pattern to live TV. Commonly observed action values for VOD content include get_vod_categories, which returns a list of on-demand categories, and get_vod_streams, which returns the items within them. A further action — get_vod_info — is commonly observed for retrieving extended details for a specific VOD item, such as a synopsis, cast information, or poster images; this action is not present on all servers.

Series content — television programmes organised into seasons and episodes — follows the same general approach, with action values such as get_series_categories, get_series, and get_series_info observed in some implementations. Series support is significantly less consistent across server implementations and versions than live or VOD support. A server may implement none, some, or all of these actions, and the response structure for series data varies more than for live or VOD content.

EPG and Programme Guide Requests

Electronic programme guide data tells a player what is currently on each channel and what is scheduled next. Xtream-compatible servers that support EPG data may offer more than one way to retrieve it. Two action values are commonly observed: get_short_epg, which requests a limited set of EPG entries for a specified stream, and get_simple_data_table, which requests a broader EPG listing associated with a stream. Neither action is universally supported, and the number of entries returned, the fields present, and the response structure vary between implementations.

Some Xtream-compatible implementations also expose a larger XMLTV guide export through a separate path. Where supported, this is commonly observed at a path such as the following:

https://HOST:PORT/xmltv.php?username=USERNAME&password=PASSWORD

This export, where available, is typically in XMLTV format — a structured XML format widely used for programme guide data. It is a separate mechanism from the get_short_epg and get_simple_data_table actions and should not be treated as equivalent to them.

EPG data quality and coverage depend entirely on what the service provider supplies to the server. A server may support EPG endpoints without having meaningful data behind them, or may have data for some channels but not others.

What Response Data Typically Contains

Most Xtream-compatible API responses return data in JSON format. The structure varies between response types — a categories response returns an array of category objects, a streams response returns an array of stream objects, and an account info response returns a single object with nested sections. The following is a simplified example of what a live stream entry in a streams response commonly contains:

{
  "num": 1,
  "name": "Example Channel",
  "stream_type": "live",
  "stream_id": 12345,
  "stream_icon": "https://HOST/images/example.png",
  "epg_channel_id": "ExampleChannel",
  "added": "1600000000",
  "category_id": "1",
  "tv_archive": 0,
  "direct_source": ""
}

Field names shown above are representative of what is commonly observed, but they are not guaranteed. Some servers use different names for the same data, include additional fields, or omit fields that other servers provide. Robust Xtream-compatible clients should be prepared for missing, null, or differently named fields.

How Stream URLs Are Constructed

Once a player has retrieved a channel or VOD item and its stream identifier, it constructs a playback URL to pass to the media player. In many Xtream-compatible implementations, live stream URLs follow a pattern that incorporates the username, password, and stream ID:

https://HOST:PORT/live/USERNAME/PASSWORD/STREAM_ID.EXT

VOD and series episode URLs follow a similar structure, typically with a different path segment in place of "live". The suffix or output format in a playback URL can indicate a container or delivery format. Live streams are commonly observed using formats such as MPEG-TS or HLS with an M3U8 manifest, while VOD container formats vary by implementation and source media. The formats a server supports depend on what the server provides and how it has been configured.

Because credentials are embedded directly in the stream URL, the same security considerations that apply to API requests also apply to these URLs. A stream URL that is copied or shared exposes the account credentials it contains.

Security and Credential Handling

In the Xtream-compatible pattern, the username and password appear as query parameters in API requests and as path segments in stream URLs. This means credentials are present in the URL itself rather than transmitted through a separate authentication mechanism. There are practical consequences to this approach that are worth understanding.

• Credentials in URLs may be recorded in server access logs, proxy logs, or network appliance logs at either end of the connection.
• Browser history and application logs on the player device may retain URLs containing credentials.
• Copying or sharing a stream URL for debugging or testing also shares the credentials embedded in it.
• HTTPS protects credentials from interception while in transit but does not prevent them from appearing in logs or other records at the server or client.
• Treat Xtream credentials with the same care as a password — avoid sharing them, avoid pasting them in places where they may be retained.

Some server implementations support additional access controls such as connection limits, which restrict how many simultaneous streams can be opened with the same credentials. These limits are enforced at the server level and are set by the service provider rather than by the player.