Developer API

Versioned BFF at /api/v1 — for Stremio addons, players, and future native apps

Listick never exposes upstream media API keys to clients. Authenticate with a scrobbler token (lstk_…) or a Supabase session JWT. Create tokens under Settings → Scrobbler API tokens.

Authentication

Send Authorization: Bearer <token> on protected routes. API tokens are prefixed with lstk_ and shown once at creation. Revoke unused tokens in Settings.

curl -sS "https://listick.tv/api/v1/health"

curl -sS "https://listick.tv/api/v1/stremio/catalogs" \
  -H "Authorization: Bearer lstk_…"

Health

GET/api/v1/healthnone

Probe for uptime checks and client bootstrap.

{ "ok": true, "service": "listick", "version": "v1", "time": "…" }

Title metadata

GET/api/v1/title?id=tmdb-movie-550none

Resolve catalog metadata for deep links and clients. Also accepts ?type=movie&externalId=550 or ?slug=movie/550.

curl -sS "https://listick.tv/api/v1/title?id=tmdb-movie-550"

Scrobble

POST/api/v1/scrobbleBearer

Report playback from Stremio, Kodi, or custom players. At least one id is required: imdb, tmdb (+ tmdbType), or kitsu. TV and anime need season and episode for scrobble / unscrobble.

Actions: start, progress, scrobble (≥80% progress), unscrobble.

curl -sS -X POST "https://listick.tv/api/v1/scrobble" \
  -H "Authorization: Bearer lstk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "scrobble",
    "ids": { "imdb": "tt0903747", "tmdb": 1396, "tmdbType": "tv" },
    "season": 1,
    "episode": 1,
    "progress": 92
  }'

Stremio content ids like tt1234567:1:5 map to IMDb + season + episode. Shared types live in @listick/sdk (ScrobbleRequestSchema).

Stremio addon API

The official community addon in apps/stremio-addon wraps these endpoints. Mark lists Public or subscribe on /l/[id] to publish catalogs.

GET/api/v1/stremio/catalogsBearer

Returns catalog definitions for your manifest (own public lists + subscriptions).

GET/api/v1/stremio/catalog/{listId}?type=movie|series&skip=0Bearer

Paginated Stremio metas. Subscribed lists use id prefix sub__+ list UUID. Smart lists are cached server-side (6h TTL).

GET/api/v1/poster?src=…&tmdb=…&imdb=…&rt=…none

Composited poster with rating badges. TMDB (all plans), IMDb (Plus+), RT (Pro+) — gated by the token owner's plan when fetched through the addon.

curl -sS "https://listick.tv/api/v1/stremio/catalogs" \
  -H "Authorization: Bearer lstk_…"

curl -sS "https://listick.tv/api/v1/stremio/catalog/sub__<list-uuid>?type=movie&skip=0" \
  -H "Authorization: Bearer lstk_…"

Public lists (no auth)

GET/api/lists/public/{listId}none

JSON for share pages at /l/[id]. Smart lists use the same cached list_items rows as Stremio.

{ "list", "owner", "items", "lastRefreshedAt" }

Rate limits

Metered routes return 429 with plan details when daily caps are exceeded. Limits vary by plan (Free / Plus / Pro); owner accounts are unlimited.

scrobble — per token owner
smart-list — preview, refresh, cron
search — discover / BFF search

Other read endpoints (health, public lists, episode guides) are cached and not user-metered.

Need the Stremio addon locally? See apps/stremio-addon/README.md in the repo.