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.

The Simkl API is a JSON-over-HTTPS REST API for Movies, TV Shows, and Anime. Every endpoint listed in this reference returns JSON, accepts JSON for POST bodies, and follows the conventions described below. If you’ve never made a Simkl API call before, start with the Quickstart — you’ll have an access_token and a working request in under five minutes.

​
Base URL

All endpoints live under a single host: 
https://api.simkl.com
Pre-built JSON files (Trending, Calendar) are served from a separate CDN host: 
https://data.simkl.in

​
Required URL parameters

Append these to every request URL — both public catalog calls and authenticated user calls: 
/endpoint?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0
ParameterRequiredValue
client_idalwaysYour client_id from your developer settings.
app-namealwaysShort, lowercase identifier for your app (e.g. plex-scrobbler, kodi-trakt-bridge).
app-versionalwaysThe current version of your app, e.g. 1.0, 2.4.1.
These three parameters help us see which apps are using the API, debug issues you report, and route around outages. They’re cheap to send — please always include them.
See Headers and required parameters for the full reference, including the User-Agent and Authorization headers.

​
Authentication

Endpoints that read or write user data require an Authorization: Bearer ACCESS_TOKEN header. You obtain a token via one of two flows:

OAuth 2.0

For iOS, Android, web, and desktop apps that can open a browser.

PIN

For TVs, consoles, watches, CLIs, and media-server plugins.
Endpoints that don’t need a user token are marked No auth in the API Reference.

​
Conventions you’ll see throughout

Pagination

page and limit URL parameters; X-Pagination-* response headers.

Rate limits

What signals Simkl returns when traffic is throttled and how to back off.

Errors

Every HTTP status code, with a stable anchor for each.

Standard media objects

The Movie / Show / Anime / Episode shapes every endpoint speaks.

Extended info

The extended URL parameter for richer fields.

Images

How to compose poster and fanart URLs from the path fragments returned in responses.

​
Try it in the playground

Every endpoint in the API Reference has an interactive playground. Paste your client_id, app-name, app-version, and access_token once at the top of any reference page and they’re reused across the rest.
Need a client_id? Create an app — free, no approval required.

​
Tooling & codegen

This entire API reference is generated from a hand-curated OpenAPI 3.1 specification. The same file is served at a stable URL so you can plug it into your own tooling — Postman / Insomnia for ad-hoc requests, an OpenAPI codegen tool (openapi-generator, oapi-codegen, kiota, etc.) for a typed client in your language, or an LLM tool that ingests OpenAPI for tool-use mapping.

OpenAPI 3.1 spec (JSON)

https://api.simkl.org/openapi.json — the full machine-readable spec for every endpoint on this site. Import into Postman, Insomnia, or your codegen of choice.

LLM-friendly docs

The whole doc site flattened into a single text file for ingestion by Claude / ChatGPT / Perplexity-style agents. See also the shorter llms.txt index.