API Reference
Trending
Calendar
Redirect
Sync
Changes
TV premieres (new + upcoming)
TV premieres — recently aired or upcoming new shows. Mirrors the Simkl TV Premieres page. No access_token required.
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 |
|---|---|
412 | Missing or invalid client_id |
500 | Server error |
Bogus param or type values silently fall back — no 400. The endpoint never returns 404.
Documentation Index
Fetch the complete documentation index at: https://api.simkl.org/llms.txt
Use this file to discover all available pages before exploring further.
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
Descriptive identifier for your app, ideally name/version. Examples: PlexMediaServer/1.43.1.10540, kodi-simkl/0.9.2, MyApp/2.4.1 (https://myapp.com).
Path Parameters
new for recent releases (sorted newest first), soon for upcoming titles (sorted soonest first). Anything other than new behaves like soon.
new, soon Query Parameters
Optional. Narrow by show type. Unknown values are ignored — you get the full list.
series, documentary Page number (1-based). Maximum 20.
1 <= x <= 20Items per page. Maximum 60 — higher values are reduced to 60.
1 <= x <= 60Your client_id from your Simkl developer settings. Required on every request.
Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.
Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.
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.
Display title.
Release date as an ISO-8601 timestamp with timezone offset. TV uses -05:00, anime uses +09:00 (Japan time).
"2026-05-18T00:00:00-05:00"
simkl.com URL relative to the root, with the slug appended. Non-ASCII characters in the slug come URL-encoded — don't encode them a second time.
"/tv/2750099/you%E2%80%99re-killing-me"
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://simkl.in/posters/{poster}_m.webp).
Anime catalog items only. Catalog format.
tv, movie, ova, ona, special, music Type 4 null — title isn't ranked yet. See Null and missing values. When present, the Simkl popularity rank (lower is more popular).
Aggregate ratings. Always carries simkl. TV items carry imdb; anime items carry mal.
Hide child attributes
Hide child attributes
Was this page helpful?