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.

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
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.

​
Required HTTP headers

HeaderRequiredValue
Content-Typeon POSTapplication/json
User-AgentalwaysA 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).
Authorizationwhen token-requiredBearer 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

VerbUseSuccess status
GETRetrieve a resource.200 OK
POSTCreate or update.201 Created
DELETERemove a resource.200 OK or 204 No Content
The full list of status codes Simkl returns lives on the Errors page.