For subscription providers

Material Xray works with the subscription formats and headers that common panels already produce, including the Happ-compatible extensions. This section covers what the client sends, what it understands, and how to hand a subscription to a user in one tap.

How a refresh works

1. The client requests your URL with its request headers. With JSON first on (the default), it tries <url>/json first and falls back to the URL itself.
2. It reads response headers, along with any #key: value body comments.
3. It parses the body as Xray JSON, a plain share-link list, or base64. See subscription format.
4. It applies metadata, then routing and per-app rules if the user’s routing policy allows it.

Note

Refreshes require HTTPS unless the user turns on Allow insecure updates for the subscription. Redirects from HTTPS to plain HTTP are refused.

Subscription formatBody formats, the /json endpoint, redirects and URL migration.

Request headersUser-Agent, HWID and device headers the client sends.

Response headersEvery header the client reads, with formats and examples.

Routing headerPush routing rules as Xray JSON or Happ routing links.

Per-app routingTell the client which apps to proxy or bypass.

DeeplinksAdd a subscription with one tap from your site or bot.