Headers and required parameters

Every Simkl API request needs three URL parameters that identify your app, plus a User-Agent header. Endpoints that read or write user data also need an Authorization: Bearer token — and the cached catalog endpoints want you to leave that header off.

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

Parameter	Required	Value
`client_id`	always	Your `client_id` from your developer settings.
`app-name`	always	Short, lowercase identifier for your app (e.g. `plex-scrobbler`, `kodi-trakt-bridge`).
`app-version`	always	The 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.

Required HTTP headers

Header	Required	Value
`Content-Type`	on POST	`application/json`
`User-Agent`	always	A descriptive identifier for your app, ideally `name/version`. Examples: `PlexMediaServer/1.43.1.10540`, `kodi-simkl/0.9.2`, `MyAppName/2.4.1 (https://myapp.com)`.
`Authorization`	when token-required	`Bearer YOUR_ACCESS_TOKEN`. Required for endpoints that read or modify the user’s library, scrobble session, ratings, settings, or playbacks. The scheme name is case-insensitive, so `bearer` works too — the token itself is not, so send it exactly as issued. Leave the header off the cached catalog endpoints — see below.

Do not send Authorization on the Cloudflare-cached endpoints. An Authorization header makes Cloudflare treat the request as private and stop serving it from the edge, so the call goes to Simkl’s origin instead — slower for your user, and heavier for everyone else, for a response that is identical either way.Send it on nothing in this list:

Movie, show and anime summaries by Simkl ID — /movies, /tv, /anime
Episode lists — /tv/episodes and /anime/episodes
The Trending and Calendar data files on data.simkl.in

These carry no per-user state, so a token changes nothing about the response. They are the same endpoints that need no user token at all, including on AUTH V2, and that do not count against your quota.The three URL parameters and the User-Agent header are still required on these calls. Only Authorization comes off.

As an alternative to the client_id query parameter, you may pass it as a simkl-api-key header. Either works; query-param form is preferred because it makes the request fully self-describing in URL form.

Putting it together

A typical authenticated call looks like:

curl "https://api.simkl.com/sync/activities?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
  -H "User-Agent: my-app-name/1.0" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

A cached catalog call looks like — note the absence of Authorization, even if your app is holding a perfectly good token:

curl "https://api.simkl.com/tv/17465?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
  -H "User-Agent: my-app-name/1.0"

In the API Reference playground these values are auto-filled — paste your client_id, app-name, app-version, and access_token once and they’ll be reused.

HTTP verbs

Verb	Use	Success status
`GET`	Retrieve a resource.	`200 OK`
`POST`	Create or update.	`201 Created`
`DELETE`	Remove a resource.	`200 OK` or `204 No Content`

The full list of status codes Simkl returns lives on the Errors page.

Get started

Authentication

Conventions

Guides

API Debug

Resources

Headers and required parameters

Required URL parameters

Required HTTP headers

Putting it together

HTTP verbs

​Required URL parameters

​Required HTTP headers

​Putting it together

​HTTP verbs

Required URL parameters

Required HTTP headers

Putting it together

HTTP verbs