Skip to content

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=show
Authorization: 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.

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.

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=tvdb

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.