Skip to main content

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.

No auth required. Calendar data is public — send the standard required URL parameters (client_id, app-name, app-version) and a User-Agent header, but no user Authorization token.
Which IDs can I send/expect? All accepted input identifiers and the keys you’ll see echoed back in responses are listed at Standard media objects → Supported ID keys. Send every ID you have on writes — Simkl picks the first that resolves and ignores the rest. Reminder: slug is response-only (never send it on a request).
Simkl publishes pre-built JSON calendars on its CDN. Use them to power the “Upcoming”, “Next”, “Schedule”, or “Calendar” sections of your app — without per-user API calls. The files are regenerated every 6 hours and cached on a CDN for 5 hours. Check the response’s Last-Modified header to know when they were last refreshed.
The CDN ignores all query strings. Don’t append ?random=... or similar — you’ll just bust the cache for everyone with no benefit. The same URL serves identical content.

​
Why use these instead of API calls

  • No user Authorization token required (still send client_id, app-name, app-version, and User-Agent like every Simkl request).
  • Hugely cheaper — one file covers thousands of titles.
  • Cacheable on the user’s device for hours.
A typical pattern: when the user opens their watchlist, combine the calendar JSON (cached locally for 3–6 hours) with the user’s synced watchlist (also cached) to compute “Next episode airs in 3 days” — without re-syncing the user’s watchlist every time.

​
Files

​
Airing next (rolling window — yesterday + next 33 days)

CatalogURL
TVhttps://data.simkl.in/calendar/tv.json?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0
Animehttps://data.simkl.in/calendar/anime.json?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0
Movie releaseshttps://data.simkl.in/calendar/movie_release.json?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0

​
Monthly archives

The current month is regenerated every 6 hours; previous months are regenerated every 24 hours for the last 12 months. URL pattern: 
https://data.simkl.in/calendar/{YEAR}/{MONTH}/{tv|anime|movie_release}.json?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0
Example for May 2026: 
https://data.simkl.in/calendar/2026/5/tv.json?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0
https://data.simkl.in/calendar/2026/5/anime.json?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0
https://data.simkl.in/calendar/2026/5/movie_release.json?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0

​
What’s in each item

Every calendar entry carries everything you need to render the schedule without a second API call per item — display title + slug, poster image path, Simkl rank + ratings, an airing timestamp with a timezone offset, plus IDs across Simkl, TMDB, IMDB, TVDB, MAL, AniDB, AniList, and Kitsu where available.
Sample item (TV)
{
  "title": "Ruin Road",
  "poster": "94/941b16f3a4d2f5e0c8",
  "date": "2026-05-16T00:00:00-05:00",
  "release_date": "2016-10-15",
  "rank": 0,
  "url": "https://simkl.com/tv/1520136/ruin-road",
  "ratings": {
    "simkl": { "rating": 7.4, "votes": 132 },
    "imdb":  { "rating": 7.6, "votes": 4218 }
  },
  "ids": {
    "simkl_id": 1520136,
    "slug": "ruin-road",
    "imdb": "tt12345678",
    "tmdb": "204821",
    "tvdb": "418273"
  },
  "episode": {
    "season": 2,
    "episode": 7,
    "url": "https://simkl.com/tv/1520136/ruin-road/season-2/episode-7"
  }
}

​
Field reference

​
title
string
required
Display title.
​
poster
string | null
Image path fragment. Combine with the prefixes in Image conventions — for example https://simkl.in/posters/{poster}_m.webp. null when no poster is on file (Type 4 null — see Null and missing values); fall back to https://simkl.in/poster_no_pic.png (see fallbacks).
​
date
string
required
Air / release timestamp with the catalog’s timezone offset (e.g. 2026-05-16T00:00:00-05:00 for US TV, +09:00 for Japanese anime). Use this for chronological sorting and timezone-aware display.
​
release_date
string (YYYY-MM-DD)
required
Original premiere date — the show or movie’s first-ever release, not the per-episode air date (that’s in date).
​
rank
integer
required
Simkl popularity rank. 0 for items that aren’t yet ranked (common on new / regional titles). Lower non-zero values = more popular.
​
url
string
required
Absolute simkl.com URL with slug (e.g. https://simkl.com/tv/1520136/ruin-road).
​
ratings
object
Aggregate ratings keyed by source. Only sources with on-file data appear.
​
ids
object
required
External and Simkl IDs. Always carries simkl_id + slug. tmdb is near-universal; imdb appears on TV / movies, mal / anidb / anilist / kitsu on anime. Additional slug variants (letterslug, traktmslug, tvdbslug, mdlslug, …) may appear on items with those platform links — the response is permissive.
​
episode
object
TV / anime only — omitted on movie files. Episode reference for the airing.
​
anime_type
string
Anime files only — omitted on TV and movie files. Catalog format. One of tv, movie, ova, ona, special, music.