RokuRemix Resolver — API

Title → Roku deep-link candidates. · Cache dashboard · Interactive Swagger · ReDoc

Authentication

Every /v1/resolve call sends X-RC-User-Id = the caller's RevenueCat app_user_id. The server verifies it against RevenueCat and allows only active entitlements — paying subscribers and valid free trials. Add X-API-Key if the deployment sets one. Per-user and per-IP hourly rate limits apply.

Endpoints

GET/v1/resolve

Resolve a spoken title to ranked Roku deep-link candidates. The app fires the first candidate whose roku_app_id is installed: launch/<roku_app_id>?contentId=<content_id>&mediaType=<media_type>. A content_id of null means app-launch only (open the app, not the title).

Query params

qThe title to resolve, e.g. "Stranger Things". Required.

Headers

X-RC-User-IdRevenueCat app_user_id. Required when gating is on; must be an active sub or trial.
X-API-KeyShared app key, only if API_KEY is configured.

Example

curl "https://tv.617sw.com/v1/resolve?q=Dexter" \
  -H "X-RC-User-Id: $RC_USER_ID"

Response

{
  "query": "Dexter",
  "title": "Dexter",
  "media_type": "series",
  "wikidata_id": "Q1082",
  "candidates": [
    { "provider": "Netflix",    "roku_app_id": "12",    "content_id": "70136126",
      "media_type": "series", "deep_link": true, "rank": 0 },
    { "provider": "Paramount+", "roku_app_id": "31440", "content_id": "61457176",
      "media_type": "series", "deep_link": true, "rank": 5 },
    { "provider": "Hulu",       "roku_app_id": "2285",  "content_id": "8162894c-...",
      "media_type": "series", "deep_link": true, "rank": 3 }
  ]
}

Errors

400 missing q
401 bad api key
402 subscription or trial required
429 rate limit exceeded

GET/health

Liveness check. Never gated.

Query params

none

Headers

none

Example

curl "https://tv.617sw.com/health"

Response

{ "ok": true, "gated": true }
GET/ · /dashboard

The local cache dashboard — every resolved title with its provider badges and content ids. Read-only; not entitlement-gated (protect with DASHBOARD_TOKEN on an untrusted network).

Query params

tokenRequired only if DASHBOARD_TOKEN is set.

Headers

none

Example

open http://<lan-ip>:8791/

Response

(HTML page)
POST/v1/revenuecat/webhook

Optional. Point RevenueCat's webhook here to refresh the entitlement cache instantly on purchase/expiry instead of waiting for the TTL.

Query params

none

Headers

AuthorizationMust match REVENUECAT_WEBHOOK_AUTH if set.

Example

curl -XPOST .../v1/revenuecat/webhook -H "Authorization: $AUTH" -d @event.json

Response

{ "ok": true }

Errors

401 bad webhook auth

Try it — /v1/resolve

response appears here…