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.

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.

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 typical public call looks like:

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