Skip to main content

Relaygate API spec (v0.6-beta)

Provider slugs, headers, envelopes, and error codes. Endpoints and examples: relaygate-canonical-api.md.

Provider selection (X-Relaygate-Provider)​

Comma-separated list of provider ids (no duplicates), same order as X-Relaygate-Provider-Api-Key when using direct upstream tokens:

X-Relaygate-Provider: torbox, real_debrid
SlugUpstream
real_debridReal-Debrid REST API
alldebridAllDebrid API
torboxTorBox API
premiumizePremiumize API
smokedebridSmokeDebrid placeholder adapter

Unknown slugs or duplicate slugs: 400, Problem response with code: rg.invalid_provider or rg.validation_error.

Raw proxy routes require exactly one slug in this header.

Auth (required headers every request)​

  • X-Relaygate-Addon-Id
  • X-Relaygate-Addon-Secret (TLS only; hashed at rest by Relaygate)
  • Exactly one of:
    • Authorization: Bearer <user_proxy_key>, or
    • X-Relaygate-Provider-Api-Key with one comma-separated token per provider, aligned with X-Relaygate-Provider

Success envelope (Canonical API)​

Top-level HTTP 200; data is an object whose keys are provider slugs. Each value is either:

  • { "data": …, "meta": … } — same normalized shape as before, plus optional debug when X-Relaygate-Include-Provider-Response: true, or
  • { "error": … } — RFC 7807 Problem object for that provider only.

Outer meta:

{
  "request_id": "uuid",
  "providers": ["torbox", "real_debrid"],
  "schema": "relaygate.jobs.list.v1"
}

Problem JSON (global errors)​

Content-Type: application/problem+json. Extension field code uses the rg.* namespace (see canonical API doc for a non-exhaustive list).

Audit storage still records the same string in gateway_request_audits.error_code.

Scope​

  • JSON control plane only; no streaming through Relaygate.
  • Playback operations return URLs for the client to fetch directly.

Rate limits​

429, code: rg.rate_limited, Retry-After: 60.

Raw proxy​

/api/v0.6-beta/proxy/<provider-relative-path> — passthrough JSON (sanitized headers). Use when a canonical operation is not implemented yet for a provider. Single provider only in X-Relaygate-Provider.