Finding titles
Every endpoint names a title by its ids.refract. A client that only knows another service’s ids, a media centre
or a tracker export, finds it first:
GET /v1/search/tmdb/95396?type=showAuthorization: Bearer rfk_…{ "data": [ { "type": "show", "is_anime": false, "ids": { "refract": "8b0e5c1a-4f2d-4b7e-9a31-2c6d0f5e9b14", "tmdb": 95396, "imdb": "tt11280740", "tvdb": 371980 }, "title": "Severance", "original_title": "Severance", "year": 2022 } ]}It needs the library:read scope.
What an id can name
Section titled “What an id can name”type |
id_type |
The id |
|---|---|---|
movie |
tmdb, imdb |
The movie’s id. TheTVDB movie ids are not supported. |
show |
tmdb, tvdb, imdb |
The show’s id. |
episode |
tmdb, tvdb, imdb |
The episode’s own id, or its show’s id with season and number. |
game |
igdb, steam, rmdb |
The game’s IGDB id, a Steam app id, or its id in RMDB, Refract’s game catalogue. See Games. |
type=game goes with igdb, steam and rmdb, and those id types go with type=game only: a game is answered only
to a client that asks for one.
Episodes
Section titled “Episodes”An episode comes back with its show and its place in TMDB’s numbering, ready for
PUT /v1/history/episodes/{id}/{season}/{number}:
{ "data": [ { "type": "episode", "show": { "type": "show", "ids": { "refract": "8b0e…", "tmdb": 95396, "imdb": "tt11280740", "tvdb": 371980 }, "…": "…" }, "episode": { "season": 1, "number": 3 } } ]}When you only know the show, send its id with season and number, and say how they count with numbering:
tmdb (the default), tvdb for TheTVDB’s aired order, or absolute, where number is the absolute episode number
and season is ignored. Refract translates them to TMDB’s order; anime are where the orders differ most.
GET /v1/search/tvdb/371980?type=episode&season=1&number=3&numbering=tvdbNo match
Section titled “No match”An id Refract cannot match answers 200 with an empty data, never a 404: do not retry it. A title no member has
tracked yet is added to Refract’s catalogue on the way, so the answer may take a moment the first time. When TMDB
cannot be reached to match an id, the answer is UNAVAILABLE, with a Retry-After;
so is a game id while the game catalogue cannot be reached.