TV premieres (new + upcoming)
TV premieres — recently aired or upcoming new shows. Mirrors the Simkl TV Premieres page. No access_token needed on AUTH V1. AUTH V2 apps must send the user’s token — an anonymous call returns 401 user_token_required. See AUTH V2 overview.
Pass new for shows that already premiered (newest first), or soon for shows premiering in the next few weeks (soonest first). Any path value other than new is treated as soon.
The two shapes differ slightly: items in the new response include rank and ratings; items in the soon response don’t carry those fields at all (the show hasn’t aired enough to be ranked or rated yet).
US and Canada only. The list is restricted to shows produced in the US or Canada — there’s no opt-out. If you want premieres from other regions, use GET /tv/genres/{genre}/{type}/{country}/{network}/{year}/{sort} with the country segment set to your target (kr, jp, gb, etc.).
Query parameters
| Param | Default | Notes |
|---|---|---|
type | (any) | Optional. series or documentary. Anything else is ignored and you get the full list. |
page | 1 | 1 to 20. Higher values are reduced to 20. |
limit | 60 | 1 to 60. Higher values are reduced to 60. |
X-Pagination-* headers on every response — see Pagination.
The full per-item shape is in the Response panel on the right.
Errors
| Status | When |
|---|---|
401 user_token_required | AUTH V2 app called without the user’s token |
412 | Missing or invalid client_id |
500 | Server error |
Bogus param or type values silently fall back — no 400. The endpoint never returns 404.
Authorizations
Preferred form: your client_id as a URL query parameter on every request. Self-describing in logs and curl commands. See Headers and required parameters.
Headers
Path Parameters
Response
OK — array of items. Shape depends on {param} (see oneOf branches).
- Item from ?param=new (with rank + ratings) · object[]
- Item from ?param=soon (no rank or ratings) · object[]
Items returned when you call /tv/premieres/new or /anime/premieres/new. Includes rank and ratings on top of the base fields. Anime items also carry anime_type.
Type 4 null — release date isn't known yet. See Null and missing values. Otherwise the premiere year as an integer.
Type 4 null — no poster on file. See Null and missing values. When present, it's an image path fragment — build the full URL using the patterns in Image conventions (e.g. https://wsrv.nl/?url=https://simkl.in/posters/{poster}_m.webp&q=90).
Type 4 null — title isn't ranked yet. See Null and missing values. When present, the Simkl popularity rank (lower is more popular).