API Reference
Trending
Calendar
Redirect
Sync
Changes
curl --request POST \
--url 'https://api.simkl.com/users/settings?client_id=' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'User-Agent: <user-agent>' \
--data '{}'{
"user": {
"name": "jane_doe",
"joined_at": "2018-06-12T14:23:08.000Z",
"gender": "female",
"avatar": "https://simkl.in/avatars/12/12345678abcdef9/user_100.jpg",
"bio": "Big into sci-fi shows and slice-of-life anime.",
"loc": "Lisbon, Portugal",
"age": "27 years"
},
"account": {
"id": 12345,
"timezone": "Europe/Lisbon",
"type": "free"
}
}Get the authenticated user's settings
Returns the authenticated user’s profile (name, avatar, bio, location, age) and account settings (timezone, plan type). POST for historical reasons — no body.
Response shape
{
"user": {
"name": "username",
"joined_at": "2018-01-15T00:00:00Z",
"gender": "Male",
"avatar": "https://simkl.in/avatars/.../user_100.jpg",
"bio": "I like anime.",
"loc": "Spain",
"age": 28
},
"account": {
"id": 12345,
"timezone": "Europe/Madrid",
"type": "vip"
}
}
account.type is one of free, pro, vip. Fields like gender are blank if the user disabled them in their privacy settings.
When to refetch
User settings are set-and-forget in practice — most users configure their timezone / date format / privacy preferences once and never touch them again. Don’t refetch on a timer or on every app launch / wake from background. Instead, gate the refetch on /sync/activities, which returns a settings.all timestamp that bumps when the user changes any account-level preference. Refetch only when that timestamp moves since the value you saved last time. Most launches will do zero extra calls. Full pattern + code example at Dates and timezones → User timezone preference.
curl --request POST \
--url 'https://api.simkl.com/users/settings?client_id=' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'User-Agent: <user-agent>' \
--data '{}'{
"user": {
"name": "jane_doe",
"joined_at": "2018-06-12T14:23:08.000Z",
"gender": "female",
"avatar": "https://simkl.in/avatars/12/12345678abcdef9/user_100.jpg",
"bio": "Big into sci-fi shows and slice-of-life anime.",
"loc": "Lisbon, Portugal",
"age": "27 years"
},
"account": {
"id": 12345,
"timezone": "Europe/Lisbon",
"type": "free"
}
}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.
Authorizations
Preferred form: your client_id as a URL query parameter on every request. Self-describing in logs and curl commands. See Headers and required parameters.
OAuth 2.0 or PIN-flow access_token. Required for endpoints that read or modify the user's library, scrobble session, ratings, settings, or playbacks. See Authentication.
Headers
Descriptive identifier for your app, ideally name/version. Examples: PlexMediaServer/1.43.1.10540, kodi-simkl/0.9.2, MyApp/2.4.1 (https://myapp.com).
Query Parameters
Your client_id from your Simkl developer settings. Required on every request.
Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.
Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.
Response
OK
Authenticated user's profile and account settings.
Hide child attributes
Hide child attributes
Type 4 null — data not on file in that field's slot. See Null and missing values.
Age in years, pre-formatted as a string like "30 years". Empty string if the user has not set their birthday or has disabled age display. Pre-formatted by the server — clients should display verbatim rather than parsing.
"30 years"
Hide child attributes
Hide child attributes
Was this page helpful?