Relaygate Canonical API (v0.6-beta)

This is the stable contract for addon backends calling Relaygate.

Goal: one consistent set of URLs and JSON shapes; Relaygate maps them to each debrid provider.

Machine-readable contract: relaygate.oas.1.0.yml.

Canonical operations mapped to TorBox and planned upstream paths (SmokeDebrid omitted): Canonical API → upstream mapping.

Provider capability matrix

Rows are Relaygate canonical operations. Columns are upstream providers. Cells describe support and the primary upstream surface.

Legend: Y full mapping planned in Relaygate, P partial / best-effort, N not mapped (returns rg.feature_unsupported or upstream error), or not applicable.

Canonical operation	real_debrid	alldebrid	torbox	premiumize	smokedebrid
`account.session`	`GET /user`	user / account endpoint	`GET /v1/api/user/me`	account / user info	placeholder
`hoster.links.unlock`	`POST /unrestrict/link` (+ check/folder)	`link/unlock` family	N (use `jobs` + `web_fetch` or proxy)	`transfer/directdl` or link resolve	N
`jobs.list`	`GET /torrents` (+ filters)	magnet / downloads list	`mylist` per modality	`transfer/list`	placeholder
`jobs.create`	`POST /torrents/addMagnet` etc.	magnet upload / link	create torrent / usenet / webdl	`transfer/create`	placeholder
`jobs.get`	`GET /torrents/{id}`	detail endpoint	P (list + filter by id in adapter)	transfer detail	placeholder
`jobs.cancel`	torrent delete / control	control endpoints	control torrent / usenet / webdl	transfer stop/delete	placeholder
`jobs.files.list`	`GET /torrents/{id}` (files in payload)	file listing	P (from list item `files`)	folder/file listing	placeholder
`jobs.files.playback`	unrestrict link for file / link endpoint	link unlock	`requestdl` + `redirect=false`	stream / link	placeholder
`torrents.cache_check`	instant-availability / hash cache checks	(per docs)	`GET /v1/api/torrents/checkcached`	cache check endpoints	placeholder

Notes

TorBox exposes torrent, usenet, and webdl queues; canonical kind values are torrent, usenet, and web_fetch respectively.
Playback: Relaygate forces redirect=false upstream so you receive JSON with data.locations[].url instead of an HTTP redirect.
Hoster unlock is not mapped for TorBox (per-provider data.torbox.error with 501 / rg.feature_unsupported when TorBox is requested); use POST /api/v0.6-beta/canonical/jobs with kind: web_fetch or the proxy path.
Real-Debrid splits instant hoster flows (/unrestrict/*) from torrent jobs (/torrents/*); hoster.links.unlock maps to the former, not to jobs.
Premiumize prefers transfer and folder vocabulary; detailed mapping is implemented.
For unsupported combinations, integrators should use /api/v0.6-beta/proxy/{path} with X-Relaygate-Provider until first-class mapping exists.

Base paths

Canonical resources (below) live under:

https://<host>/api/v0.6-beta/canonical/...

Raw JSON proxy (provider-relative path after the prefix):

https://<host>/api/v0.6-beta/proxy/<provider-path>

Proxy routes require exactly one provider in X-Relaygate-Provider (comma-separated lists are rejected with 400).

Required headers (every request)

Header	Purpose
`X-Relaygate-Provider: <slug>[,<slug>...]`	Comma-separated provider ids (`real_debrid`, `alldebrid`, `torbox`, `premiumize`, `smokedebrid`, …). No duplicate slugs.
`X-Relaygate-Addon-Id`	Approved addon identifier
`X-Relaygate-Addon-Secret`	Developer secret (TLS only)
`Authorization: Bearer <user_proxy_key>`	or direct keys below — with Bearer, the vault resolves per provider from the user’s stored credentials
`X-Relaygate-Provider-Api-Key: <token>[,<token>...]`	or Bearer — comma-separated upstream tokens aligned by position with `X-Relaygate-Provider`; same entry count; never send both Bearer and this header

Tokens in X-Relaygate-Provider-Api-Key must not contain commas (no escaping).

Optional: raw upstream JSON

X-Relaygate-Include-Provider-Response: true — on success for a given provider, adds debug.upstream with that provider’s raw JSON (non-contractual), under that provider’s entry in data.

Success envelope (canonical)

Successful aggregation responses use HTTP 200 and Content-Type: application/json. The top-level object maps each requested provider to either a normalized success fragment or a per-provider error (see below).

{
  "data": {
    "torbox": {
      "data": { },
      "meta": {
        "request_id": "uuid",
        "provider": "torbox",
        "schema": "relaygate.account.session.v1"
      },
      "debug": { "upstream": { } }
    },
    "premiumize": {
      "error": {
        "type": "https://relaygate.invalid/docs/errors#rg.vault_missing",
        "title": "Vault credential missing",
        "status": 404,
        "detail": "No vault credential for this provider.",
        "instance": "uuid",
        "code": "rg.vault_missing"
      }
    }
  },
  "meta": {
    "request_id": "uuid",
    "providers": ["torbox", "real_debrid"],
    "schema": "relaygate.account.session.v1"
  }
}

meta.schema (outer) identifies the operation’s payload type for each successful data.<provider>.data (stable string per operation).
meta.providers lists the providers in request order.
Per-provider meta.schema matches the outer meta.schema for that operation.
Missing scalar fields in per-provider data are usually null rather than omitted.
debug appears only when X-Relaygate-Include-Provider-Response: true and that provider succeeded.

Errors

Global errors (RFC 7807)

For failures that apply to the whole request (invalid provider list, missing addon headers, conflicting credentials, body too large, JSON required when required, rate limits, invalid developer, etc.), Relaygate returns Problem Details as before — not the multi-provider data object.

Content-Type: application/problem+json

{
  "type": "https://relaygate.invalid/docs/errors#rg.invalid_provider",
  "title": "Invalid provider",
  "status": 400,
  "detail": "Human readable explanation.",
  "instance": "uuid",
  "code": "rg.invalid_provider"
}

Common code values (all use the rg. prefix): rg.invalid_provider, rg.missing_addon_id, rg.missing_developer_secret, rg.missing_end_user_credential, rg.conflicting_gateway_credentials, rg.invalid_developer, rg.invalid_proxy_key, rg.vault_missing, rg.addon_access_denied, rg.addon_not_allowlisted, rg.edge_ip_required, rg.ip_access_denied, rg.ip_not_allowlisted, rg.rate_limited, rg.upstream_unreachable, rg.upstream_non_json, rg.validation_error, rg.resource_not_found, rg.feature_unsupported, rg.provider_adapter_missing, rg.internal_error.

Rate limits: HTTP 429, code: rg.rate_limited, optional retry_after, header Retry-After: 60.

Per-provider errors (inside HTTP 200)

When one provider fails (vault missing, adapter missing, upstream problem, etc.) but the request is otherwise valid, that provider’s entry in data.<provider> is { "error": { ...Problem Details... } }. Other providers are unaffected. If every provider fails, the HTTP status is still 200 with each key under data carrying an error object — clients must inspect each provider.

Endpoints (canonical)

Method	Path	Purpose
GET	`/api/v0.6-beta/canonical/account`	Account session / account overview
POST	`/api/v0.6-beta/canonical/hoster/links/unlock`	One-shot hoster unlock (not all providers)
GET	`/api/v0.6-beta/canonical/jobs?kind=...`	List jobs (`kind`: `torrent`, `usenet`, `web_fetch`)
POST	`/api/v0.6-beta/canonical/jobs`	Create job (JSON body includes `kind`)
GET	`/api/v0.6-beta/canonical/jobs/{jobId}?kind=...`	Get one job
POST	`/api/v0.6-beta/canonical/jobs/{jobId}/cancel?kind=...`	Control / cancel (provider-specific JSON body)
GET	`/api/v0.6-beta/canonical/jobs/{jobId}/files?kind=...`	List files on the job
POST	`/api/v0.6-beta/canonical/jobs/{jobId}/files/{fileId}/playback?kind=...`	Resolve playback URLs (`data.locations[]` under each provider’s success `data`)
POST	`/api/v0.6-beta/canonical/torrents/cache-check`	Batch cache / instant-availability check for info hashes (`data.items[]` per provider)

Example: account (single provider)

curl --location '{{baseUrl}}/api/v0.6-beta/canonical/account' \
  --header 'Authorization: Bearer {{proxyKey}}' \
  --header 'X-Relaygate-Provider: torbox' \
  --header 'X-Relaygate-Addon-Id: {{addonId}}' \
  --header 'X-Relaygate-Addon-Secret: {{addonSecret}}'

Example: account (multiple providers, proxy key)

curl --location '{{baseUrl}}/api/v0.6-beta/canonical/account' \
  --header 'X-Relaygate-Provider: torbox, real_debrid' \
  --header 'X-Relaygate-Provider-Api-Key: <torbox_token>, <real_debrid_token>' \
  --header 'X-Relaygate-Addon-Id: {{addonId}}' \
  --header 'X-Relaygate-Addon-Secret: {{addonSecret}}'

Example: torrent job list

curl --location '{{baseUrl}}/api/v0.6-beta/canonical/jobs?kind=torrent' \
  --header 'Authorization: Bearer {{proxyKey}}' \
  --header 'X-Relaygate-Provider: torbox' \
  --header 'X-Relaygate-Addon-Id: {{addonId}}' \
  --header 'X-Relaygate-Addon-Secret: {{addonSecret}}'

Example: playback URL

curl --location --request POST '{{baseUrl}}/api/v0.6-beta/canonical/jobs/{{jobId}}/files/{{fileId}}/playback?kind=torrent' \
  --header 'Authorization: Bearer {{proxyKey}}' \
  --header 'X-Relaygate-Provider: torbox' \
  --header 'X-Relaygate-Addon-Id: {{addonId}}' \
  --header 'X-Relaygate-Addon-Secret: {{addonSecret}}'

Example: torrents cache check (TorBox)

curl --location '{{baseUrl}}/api/v0.6-beta/canonical/torrents/cache-check' \
  --header 'Authorization: Bearer {{proxyKey}}' \
  --header 'Content-Type: application/json' \
  --header 'X-Relaygate-Provider: torbox' \
  --header 'X-Relaygate-Addon-Id: {{addonId}}' \
  --header 'X-Relaygate-Addon-Secret: {{addonSecret}}' \
  --data '{"hashes":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"],"list_files":false}'

OpenAPI and Postman

Use the OpenAPI file linked above in the docs site or import into Postman for request templates.

Provider capability matrix​

Notes​

Base paths​

Required headers (every request)​

Optional: raw upstream JSON​

Success envelope (canonical)​

Errors​

Global errors (RFC 7807)​

Per-provider errors (inside HTTP 200)​

Endpoints (canonical)​

Example: account (single provider)​

Example: account (multiple providers, proxy key)​

Example: torrent job list​

Example: playback URL​

Example: torrents cache check (TorBox)​

OpenAPI and Postman​