apiary.apib

FORMAT: 1A
HOST: https://api.simkl.com

# Simkl API

# THESE DOCS HAVE MOVED

# New home: [api.simkl.org](https://api.simkl.org)

---

> **The Simkl developer documentation has moved to [api.simkl.org](https://api.simkl.org).**
>
> Apiary (where these docs have lived for years) is being sunset by Oracle in October 2026. All new endpoints, breaking changes, and improvements are published on the new site. The pages below are frozen as of 2026-05-22 and will be retired when Oracle pulls Apiary down.

---

## What is at the new site

The new documentation at **[api.simkl.org](https://api.simkl.org)** is a top-to-bottom rewrite, not a content port. What you will find there:

+ **Detailed workflow guides** for [Sync](https://api.simkl.org/guides/sync), [Scrobble](https://api.simkl.org/guides/scrobble), [Search](https://api.simkl.org/guides/search), [Anime](https://api.simkl.org/guides/anime), [Deep linking](https://api.simkl.org/guides/deep-linking), [Mark as watched](https://api.simkl.org/guides/mark-as-watched), and the new [Rewatches](https://api.simkl.org/guides/rewatches) guide.
+ **All three authentication flows** properly walked through at [api.simkl.org/authentication](https://api.simkl.org/authentication): OAuth 2.0 for server-side web apps, Public PKCE for mobile, SPAs, browser extensions, and desktop binaries, and the PIN flow for TVs, consoles, CLIs, and media-server plugins.
+ **Conventions pages** for the cross-cutting topics this Apiary spec never covered: [Headers](https://api.simkl.org/conventions/headers), [Pagination](https://api.simkl.org/conventions/pagination), [Dates](https://api.simkl.org/conventions/dates), [Watchlist statuses](https://api.simkl.org/conventions/list-statuses), [Null values](https://api.simkl.org/conventions/null-values), [Images](https://api.simkl.org/conventions/images), and [CORS](https://api.simkl.org/conventions/cors).
+ **A flat [Errors page](https://api.simkl.org/conventions/errors)** covering every HTTP status code, with cause, fix, and example for each.
+ **Interactive try-it-now playground** on all 48 endpoints across 14 categories. Drop in your token, hit Send, get a real response back.
+ **Copy-paste examples in 16 languages**: curl, Python, JS/TS, Kotlin, Swift, Java, Go, C#, Ruby, PowerShell, C/C++, and more.
+ **LLM-friendly**: every page can be copied as raw markdown or opened straight in Claude, ChatGPT, Cursor, or VSCode. Full-site [llms.txt](https://api.simkl.org/llms.txt) is published too.
+ **Full [OpenAPI 3.1 spec](https://api.simkl.org/openapi.json)** with every endpoint and every response shape verified against the live API. Point your SDK generator at it.

## New features shipping alongside the docs

+ **[Rewatches](https://api.simkl.org/guides/rewatches)**: `POST /sync/history?allow_rewatch=yes` now tracks separate viewing sessions on items the user already finished, the same data that powers the Rewatches panel on simkl.com. Up to 50 sessions per movie, show, or anime, with proper session IDs you can resume. Available for Simkl Pro and VIP members.
+ **[API Analytics](https://api.simkl.org/debug/api-analytics)**: every registered Simkl app now has a built-in live request log. 24 hours of individual requests, with edge and origin status codes, latency, burst detection for retry loops, and CSV export. Useful for diagnosing OAuth wrappers, sync loops missing `date_from`, and silent 4xx errors your HTTP client never surfaces. Open it from your app row in your [developer dashboard](https://simkl.com/settings/developer/).

## Where to ask questions

The Simkl team is on [Discord](https://discord.gg/MJsWNE4) and reads everything posted there. The [changelog](https://api.simkl.org/changelog) tracks every new endpoint, breaking change, and improvement.

---

# The frozen Apiary documentation continues below


<table>
    <tr>
        <td width="85" align="center" valign="top"><a href="https://simkl.com" target="_blank"><img src="https://i.simkl.com/img_tv/apiary_logo_api.png" alt="Simkl" width="68" height="67"/></a></td>
      <td>We’ve worked very hard to make <a href="https://simkl.com/" target="_blank">Simkl</a>  the dream "TV, Anime and Movie Tracker". However, chances are it doesn’t do 100% of what you need it to do. Luckily for you, we added an API so you can extend Simkl’s functionality.<br><br>If you need some API method which we do not have, do not hesitate to <a href="mailto:support@simkl.com" target="_blank">contact us</a> and we'll add it as soon as possible. </td>
  </tr>
    <tr>
      <td colspan="2"><br><b>Useful Links:</b><br>
      <a href="https://simkl.com/">Simkl.com</a> &nbsp; ∙ &nbsp;
      <a href="https://simkl.com/settings/developer/new/">Get an API key</a> &nbsp; ∙ &nbsp;
      <a href="https://discord.gg/MJsWNE4">Feature Requests</a> &nbsp; ∙ &nbsp;
      <a href="https://discord.gg/MJsWNE4">Discord Server</a> &nbsp; ∙ &nbsp;
      <a href="https://github.com/SIMKL/API/issues">Report Issues</a> &nbsp; ∙ &nbsp;
      <a href="https://twitter.com/Simkl">Twitter</a>
      
</table>

# Getting Started
***

This guide will walk you through how to use Simkl API on your website, media server app, browser extension or in your mobile app. 


## Before You Start
To successfully start using Simkl API, you need to:

1. **[Sign up for a Simkl account](https://passport.simkl.com/register/)**.
2. **[Create a new app in your account](https://simkl.com/settings/developer/new/)** to get your API key (`client_id`).
3. **[Join the Discord Server to chat](https://discord.gg/MJsWNE4)**
<br><br>Join the [community](https://discord.gg/MJsWNE4) to talk, learn about and discuss the Simkl APIs. Or DM directly on Discord.

## Requirements
### 1. When using the API, a link is required back to https://simkl.com/ or directly to an item related to the API request. If not sure how to implement, let us know at support@simkl.com or DM directly on Discord.
### 2. The Simkl API is not authorized for use in conjunction with other competing services of the same nature if your service or app does not provide Simkl login and Sync functionality with Simkl, including but not limited to TV, Movie, Anime, Manga list/tracker services. If you are interested in using this service within your own application or website, please contact us at though our Discord and we will be happy to discuss it further!
What this means is that you cannot use parts of the API that don't involve tracking unless you integrate the option to sync with Simkl, especially if your app already has sync functionality with other trackers.
### 3. Please use TVDB, TMDB API from their original sources if your need metadata API.
### 4. If you're using Github, it is important to hide your Client-ID and secrets in [Github Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) to avoid any API request limit issues.
### 5. Free for non-commercial use. (See commercial usage below).

The Simkl API can be used within commercial applications or services that generate less than $150 per month in revenue free of charge, without explicitly requesting permission.
Any application or service that generates more than $150 in revenue per month must obtain a commercial license. Those who wish to acquire a commercial license or more information regarding commercial API usage may reach us through the Discord server. 

Running the API inside your app with large amount of requests costs us fees in DNS, Routing, Health checks, CDN, Server Hosting, Failover backups and Server management so if you have large amount of requests you need to be able to cover them financially.

## How to use the API
1. Get user's `token` using [OAuth](/#reference/authentication-oauth-2.0) or [PIN Authentication](/#reference/authentication-pin) and save it on user's device.
2. Post API requests with the user's `token` and your API Key (`client_id`)

<br><br><br><br>

# About Simkl API
***

All API access is over HTTPS. All responses are returned as JSON. The API is (mostly) RESTful.<br>
Please [contact us](http://support.simkl.com) if you're interested in an API we don't yet support.


Here's what you need to know to get started quickly:

## Use Cases
The Simkl API lets you build a variety of applications and scripts to integrate Simkl with your apps, show Simkl data in other contexts, and update your watch history from various locations.

Here are some examples of the things you can build with the Simkl API:

- A browser extension to quickly mark as watched or add to your watchlist from any web page.
- A Movie, TV or Anime app for iOS or Android.
- Plugin for your favorite media center app to sync your watch history with Simkl.

## Api URL
`https://api.simkl.com/`
## Verbs
HTTP Verb|Description
---|----
`GET`| Retrieve the item.  Success returns `200` status code.
`POST`| Create a new item.  Success returns `201` status code.
`DELETE`| Delete the item. Success returns `200` or `204` status code.

## HTTP Status Codes
The Simkl API attempts to return appropriate HTTP status codes for every request.

Code|Text|Description
---|---|----
`200`| OK | Success!
`201`| OK | Success - *new resource created (POST)*
`204`| OK | Success - *no content to return (DELETE)*
`302`| Found | Redirected to correct URL
`400`| Bad Request | The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
`401`| Unauthorized | [Authentication credentials](#reference/authentication-oauth-2.0) were missing or incorrect.
`403`| Forbidden | The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain why. This code is used whe using invalid API key or unapproved app or requests are being denied due to API limits.
`404`| Not Found | The URI requested is invalid or the resource requested. Also returned when the requested format is not supported by the requested method.
`405`| Not Found | *[IN_DEV]*
`409`| Unauthorized | *[IN_DEV]* Conflict - resource already created
`412`| client_id_failed | incorrect cliend_id or Total Requests Limit Exceeded
`422`| *[IN_DEV]* | *[IN_DEV]*
`429`| *[IN_DEV]* | Rate Limit Exceeded
`500`| Internal Server Error | Something is broken. Please post to the [developer discord](https://discord.gg/MJsWNE4) so the Simkl team can investigate.
`502`| Bad Gateway | Simkl is down or being upgraded.
`503`| Service Unavailable | The Simkl servers are up, but overloaded with requests. Try again later.

## Required Headers
When making API calls you'lll need to send some headers to identify your app.

Header|Value
---|----
`Content-Type` * | `application/json`
`simkl-api-key` * | Your `client_id` listed under [your Simkl applications](https://simkl.com/settings/developer/).

## Full Info

By default methods are not returnig additional data for movies, anime, show etc. They return minimal info you need to match in the local database. But, if you need more information just add `extended={fields}` to the URL.

*Fields*|*Description*
---|---|----
`full`| Complete info, except `discover` endpoints
`title`,`slug`,`overview`,`metadata`,`theater`,`genres`,`tmdb`| Possible comma separated values for the <b>Discover</b> endpoints. <br> `theater` value requires `&user-country=us` variable, otherwise US country will be taken.

## Dates
[In Development] Currently dates are returned as (GMT - 05:00 New York time zone)

All dates will be GMT and returned in the ISO 8601 format like `2015-03-15T15:30:11Z`. Adjust 
accordingly in your app for the user's local timezone.

## Pagination
Some of our endpoints are paginated. Endpoints which have 📄 Pagination will load 1 page of 10 items by default. If you want to change this, append query string `?page={page}&limit={limit}` to the URL

Parameter|Type|Default|Value
---|---|---|---
`page`|integer|1|Number of page
`limit`|integer|10|Results per page

additionally, all paginated endpoints will return these HTTP headers as well
Header|Value
-|-
X-Pagination-Page|Current page
X-Pagination-Limit|Items per page
X-Pagination-Page-Count|Total number of pages
X-Pagination-Item-Count|Total number of items

## Images
Use `https://wsrv.nl/?url=https://simkl.in` domain for images.

It is preffered to use https://wsrv.nl/ service to minimise traffic to our servers. As an extra bonus WSRV provides options to resize and cut images as you need them.

We have different types of images, choose the one that best suits your needs.
JSON DATA|Prefix URL
---|---
poster|`/posters/`
fanart|`/fanart/`
episode|`/episodes/`
avatars|`/avatars/`
[IN DEV]|`/comments/`

Url structure: <b>{domain}{prefix}{image_url}{suffix}{extension}</b>

prefix|suffix|Size|extension|Example
---|---|---|---|---
`posters`|`_w` (landscape, cropped}|600x338|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_w.webp)
`posters`|`_m`|340x *|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_m.webp)
`posters`|`_ca`|190x279(285)|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_ca.webp)
`posters`|`_c`|170x250(256)|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_c.webp)
`posters`|`_cm`|84x124|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_cm.webp)
`posters`|`_s`|40x57|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_s.webp)
||||
`fanart`|`_d` (darker, small KB)|* x * (original size)|`.jpg`|[Example](https://wsrv.nl/?url=https://simkl.in/fanart/71/710408ec0a1bd207_d.jpg)
`fanart`|`_medium`|1920x1080|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/fanart/71/710408ec0a1bd207_medium.webp)
`fanart`|`_mobile`|960x540|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/fanart/71/710408ec0a1bd207_mobile.webp)
`fanart`|`_w`|600x338|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/fanart/71/710408ec0a1bd207_w.webp)
`fanart`|`_s48`|48x27|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/fanart/71/710408ec0a1bd207_s48.webp)
||||
`episodes`|`_w`|600x338|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/episodes/26/265319260301d2ee2_w.webp)
`episodes`|`_c`|210x118|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/episodes/26/265319260301d2ee2_c.webp)
`episodes`|`_m`|112x63|`.jpg` or `.webp`|[Example](https://wsrv.nl/?url=https://simkl.in/episodes/26/265319260301d2ee2_m.webp)
||||
`avatars`|`_24`|24x24|`.jpg`|[Example](https://wsrv.nl/?url=https://simkl.in/avatars/1/1_24.jpg)
`avatars`|`_100`|100x100|`.jpg`|[Example](https://wsrv.nl/?url=https://simkl.in/avatars/1/1_100.jpg)
`avatars`|` `|200x200|`.jpg`|[Example](https://wsrv.nl/?url=https://simkl.in/avatars/1/1.jpg)
`avatars`|`_256`|256x256|`.jpg`|[Example](https://wsrv.nl/?url=https://simkl.in/avatars/1/1_256.jpg)
`avatars`|`_512`|512x512|`.jpg`|[Example](https://wsrv.nl/?url=https://simkl.in/avatars/1/1_512.jpg)

### Caching images
It is required that you cache images in your app or server by `image_url` forever. The images with the same URL never change. Do not redownload the same image multiple times.

## Standard Media Objects

All methods will accept or return standard media objects for `movie`, `show`, `episode` items. 

Anime can has `anime_type` with possible values `tv|movie|special|ova|ona|music video`.

Here are examples for all objects:

<table>
    <tr>
        <td align="center" valign="top"><strong>movie</strong></td>
      <td>
<pre>Movie example:<code>{
    "title":"Terminator 3: Rise of the Machines",
    "year":2003,
    "ids":{
        "simkl":53536,
        "imdb":"tt0181852",
        "tmdb":296
    }
}</code></pre>
<pre>Example when only id is known:<code>{
    "ids":{
        "simkl":53536
    }
}</code></pre></td>
    </tr>
    <tr>
      <td align="center" valign="top"><strong>show</strong></td>
      <td><pre>TV Show example:<code>"title":"The Walking Dead",
    "year":2010,
    "ids":{
        "simkl":2090,
        "tvdb":153021,
        "imdb":"tt1520211"
    },
    "seasons": [
            {
                "number": 1,
                "episodes": [
                    {
                        "number": 1
                    },
                    {
                        "number": 2
                    }
                ]
            }
        ]
    ]
}</code></pre>
      <pre>Anime example:<code>{
    "title": "Attack on Titan",
    "year": 2013,
    "ids": {
        "simkl": 39687,
        "mal": 16498,
        "tvdb": 267440,
        "imdb": "tt2560140",
        "anidb": 9541
    },
    "episodes": [
        {
            "number": 1
        },
        {
            "number": 2
        }
    ]
}</code></pre></td>
    </tr>
    <tr>
      <td align="center" valign="top"><strong>episode</strong></td>
      <td>
<pre>Episode example:<code>{
    {
        "watched_at": "2014-09-01T09:10:11Z",
        "ids": {
            "simkl": 231223,
            "hulu": 681868,
            "crunchyroll": 656647
        }
    }
}</code></pre>

</table>


## API Terms of Use
Thank you for using the Simkl application programming interfaces (the "Simkl APIs"). By using the Simkl APIs, you UNCONDITIONALLY CONSENT AND AGREE TO BE BOUND BY AND A PARTY TO THE TERMS AND CONDITIONS LISTED AT [https://simkl.com/about/policies/terms/api/](https://simkl.com/about/policies/terms/api/) and also agree to display information about Simkl in all parts of your application or website where Simkl API or content from Simkl API is used as deemed necessary by request of Simkl Team. If you disagree with any of these terms, Simkl does not grant you a license to use the Simkl APIs. 

## Help us improve!
If you find any error or omission on the documentation, or you’d like us to cover or clarify something, just [let us know](https://support.simkl.com/forums/264009-top-ideas-from-the-community/category/86437-api) and we’ll try to make you happy. You are also welcome to [join our development community](https://discord.gg/MJsWNE4).

<br><br>

# Group Authentication - OAuth 2.0
There's no reinventing the wheel here so the API uses OAuth2. 

Requesting user associated information requires `token` that needs to be included in all request headers made to the API.


To obtain the `client_id` and `client_secret` please [create an app first](https://simkl.com/settings/developer/new/). 


To make calls on behalf of a user you have to obtain an `access_token`. To do this, first use **https://simkl.com/oauth/authorize** method to get `code` and then post it in JSON format to **https://api.simkl.com/oauth/token** url. In response you'll get the `access_token`.
For more details see Authorize and Token sections below.

  **So STEP  1 for OAuth - Open the URL that looks like this in your Browser or in a Custom Tab (do not use WebView) on mobile device from your app:**
  
+ Request https://simkl.com/oauth/authorize?response_type=code&client_id=c7be48f1559a6d794w1925237c626326c7bsdfsa559a6d794w1925137c626316&redirect_uri=http://yourdomain.com/oauth.html
        
        
+ Response 200

It will redirect back to your website or app URL with `?code` at the end of your Redirect URL.


## Authorize [/oauth/authorize{?response_type,client_id,redirect_uri,state}]

### Authorize Application [GET]
Redirect a user to this URL. There the user will grant permissions for you app and if everything is fine you'll get a `code` which you can exchange for `access_token`. 
Once you have an access token you can use it to make calls on behalf of a user.

**Note:** You should use the https://simkl.com domain when creating this URL and not the API URL.

+ Parameters
    + response_type (string, `code`) ... must be "code"
    + client_id (string) ... Get this from your app settings
    + redirect_uri (string, `http://yourdomain.com/oauth.html`) ...  [URI in your app settings](https://simkl.com/settings/developer/)
    + state (optional, string, `state`) ... your custom variable

+ Request https://simkl.com/oauth/authorize?response_type=code&client_id=c7be48f1559a6d794w1925237c626326c7bsdfsa559a6d794w1925137c626316&redirect_uri=http://yourdomain.com/oauth.html

    + Body

+ Response 200

    + Body

## Token [/oauth/token]
### Exchange code for access_token [POST]
**STEP 2:** The redirect to your application in the step above will include a `code` parameter which you can exchange for an `access_token` using this method. 

Save the `access_token` somewhere safe. From that moment your app can authenticate the user by sending the `Authorization` header.

<h4>JSON POST DATA</h4>
Key|Type|Value
---|----|-----
code|string|code you've get from authorize method
client_id|string|Get this in your app settings
client_secret|string|Get this in your app settings
redirect_uri|string|Your URI in your app settings 
grant_type|string|`authorization_code`

`access_token` do not have expiration date (Never expire).

`access_token` can be deleted by user when revoking app access rights in [Connected Apps settings](https://simkl.com/settings/connected-apps/).

+ Request (application/json)

        {
            "code"          : "d7be48f1559a6d794w1925237c626326c7dddfsa559a6d794w1925137c626313",
            "client_id"     : "c7be48f1559a6d794w1925237c626326c7bsdfsa559a6d794w1925137c626352",
            "client_secret" : "a9be48f1529a2d794w1925237c626326c7dddfsa559a6d794w1925137c626321",
            "redirect_uri"  : "http://yourdomain.com/oauth.html",
            "grant_type"    : "authorization_code"
        }
+ Response 200 (application/json)
Valid `code` will generate you the `access_token`
    + Body

            { 
                "access_token"  : "b5be48f1529a2d794f1925237c626326c7dddfsa559a6d794w1925137c622329",
                "token_type"    : "bearer", 
                "scope"         : "public"
            }
+ Response 401 (application/json)
Invalid code will give you a 401 error
    + Body

            { 
                "error"  : "grant_error"
            }
        

# Group Authentication - PIN
This flow is designed for devices that have limited input capabilities, such as media center plugins, game consoles, smart watches, smart TVs, command line scripts, and system services, etc.
Your app displays an alphanumeric code (typically 5 characters) to the user. They are then instructed to visit the verification URL on their computer or mobile device. After entering the code, the user will be prompted to grant permission for your app. After your app gets permissions, the device receives an access_token and works like standard OAuth from that point on.

You should do the following step to authorize user's device:

1. [Request a device code](#reference/authentication-pin/request-a-device-code/get-code).

2. Display `user_code` and instruct the user to visit the [`verification_url`](https://simkl.com/pin/).
<img src="https://us.simkl.in/img_tv/api_demo_pin.png" alt="Simkl PIN" width="779" height="479"/>

3. [Begin polling Simkl's authorization server](#reference/authentication-pin/get-code-status/check-user_code).

4. User enters `user_code` at  the [`verification_url`](https://simkl.com/pin/) on their computer or mobile device.

5. Simkl returns `access_token` to the device where the polling is in progress. Your app will be polling to see if the user successfully authorizes your app. Use `expires_in` to stop polling after that many seconds, and gracefully instruct the user to restart the process. **It is important to poll at the correct interval and also stop polling when expired**.

6. Once they have, refresh your UI to indicate a successful connection has been made. 

## Request a device code [/oauth/pin{?client_id,redirect}]

### Get CODE [GET]
 
In response you'll get `user_code` and `verification_url` (in most cases [https://simkl.com/pin/](https://simkl.com/pin/)) which should be displayed to the user. Store `expires_in` and `interval` values for step 3.

<h4>JSON POST DATA</h4>
Key|Type|Value
---|----|-----
client_id|string|Get this in your app settings

+ Parameters
    + client_id (string, `***`) ... Get this from your app settings
    + redirect (string,optional,`http://yourdomain.com/welcome`) ... URL where you want to redirect user when he approved you application
            
+ Response 200 (application/json)

    + Body
    
            { 
                'result': 'OK', 
                'device_code': DEVICE_CODE, 
                'user_code': USER_CODE, 
                'verification_url': https://simkl.com/pin/, 
                'expires_in': 900, 
                'interval': 5 
            }

## Get CODE status [/oauth/pin/{USER_CODE}{?client_id}]

### Check USER_CODE [GET]

Application can poll this url to get `USER_CODE` status or `ACCESS_TOKEN`. Returned interval in step 1 response specifies the minimum amount of time(seconds), that your app should wait between polling requests.

+ Parameters
    + client_id (string, `***`) ... Get this from your app settings
    + USER_CODE (string) ... Get this from previous step
            
+ Response 200 (application/json)

    + Body
    
            { 
                'result': 'KO', 
                'message': 'Authorization pending'
            }

+ Response 200 (application/json)

    + Body
    
            { 
                'result': 'KO', 
                'message': 'Slow down'
            }

+ Response 200 (application/json)

    + Body
    
            { 
                'result': 'OK', 
                'access_token': ACCESS_TOKEN
            }


# Group Calendar
Simkl provides separate JSON data calendar files that can be used to display the "Upcoming", "Next", "Schedule" or "Calendar" sections in your app or within show details cards.    

The calendar files are generated every 6 hours and are cached on a CDN for 5 hours *(you can check the last-modified HTTP Headers for the file generation date)*.     

The files URLs ignore all query strings, so **do not add** any additional parameters (such as **``?random=***``**).

<h3>How to use calendar data</h3>
You can use the calendar data to create lists of upcoming episodes, premieres (e.g. S01E01), or movies by combining it with your existing lists or using the user lists obtained from the [Sync](/#reference/sync) endpoints.  

**Example:** When a user opens their watchlist, you can add the calendar data to show that the next episode will air in 3 days, without the need to re-sync the user's list. **Simply get fresh calendar files and cache them for 3-6 hours on the user's device.**

<h2>List of Calendar Data Files</h2>
<h3>Airing Next</h3>
Find out when the next episodes or movie releases are happening:

https://data.simkl.in/calendar/tv.json    
https://data.simkl.in/calendar/anime.json    
https://data.simkl.in/calendar/movie_release.json    

**The calendar files contain episode airing dates (for TV, Anime) and theater release dates (for Movies) for the previous day as well as the next 33 days.**

<h3>Monthly Calendar Data Files</h3>
We update calendars for the past 12 months every 24 hours, and for the current month every 6 hours.

**Examples for January 2024:**

https://data.simkl.in/calendar/2024/1/tv.json    
https://data.simkl.in/calendar/2024/1/anime.json    
https://data.simkl.in/calendar/2024/1/movie_release.json    

All calendar items have Simkl rank and ratings, [poster images](/#introduction/about-simkl-api/images), as well as SIMKL, TVDB, TMDB, IMDB, and MAL IDs where available.



# Group Ratings

The **Simkl Ratings API** allows you to retrieve Simkl average rating information (0–10), ranks, external ratings (e.g. IMDB, MAL), drop rates, and trailer availability for movies, TV shows, and anime on Simkl.

## Ratings by ID [/ratings{?simkl,fields,client_id}]

### Get movie, TV show, or anime rating [GET]

<h4>&#128275; Token Not Required</h4>

> You only need to supply a valid `client_id` obtained from your [App Settings](https://simkl.com/settings/developer/).

Use this endpoint to retrieve rating information by providing a **Simkl ID**. You can request additional fields, such as external ratings (IMDB, MAL), trailer availability, etc.


+ Parameters

    + simkl (optional, integer, `10280`) ... 
       - The unique Simkl ID of the item (movie, TV show, or anime).  
       - Example: `simkl=10280`  
       - If omitted, the API might not return any data unless another valid ID parameter is provided.
       
    + fields (optional, string, `rank,droprate,simkl,ext,has_trailer,reactions,year`) ... 
        - A comma-separated list of additional fields to include in the response.  
            - `simkl` – returns the Simkl rating and votes.
            - `ext` – includes external ratings such as IMDB or MAL if available.  
            - `rank` – returns the rank within the Simkl service for that media type (movie, tv, anime).  
            - `status` – includes the release status of the item.  
            - `year` – includes the year of release.  
            - `reactions` – includes reaction data if available.
            - `has_trailer` – indicates if the movie/TV show/anime has a trailer.  
            - Example: `fields=rank,droprate,simkl,ext,has_trailer,reactions,year`
        + Values
            + `simkl`
            + `ext`
            + `rank`
            + `status`
            + `year`
            + `reactions`
            + `has_trailer`
    + hulu (optional, integer, `752375`) ... Hulu ID. All other parameters can be empty if this one specified.
    + netflix (optional, integer, `70210890`) ... Netflix `movieid`, this parameter is in beta and may not work.
    + mal (optional, integer, `4246`) ... MyAnimeList `id`.
    + tvdb (optional, integer, `153021, the-walking-dead`) ... TVDB ID. All other parameters can be empty if this one specified.
    + type (optional, integer, `show`) ... Required for better search by tmdb title field. Use 'show' to search both anime and tv. Use 'anime' to limit the search by title in anime. 'movie' is theatrical movie, not anime movie.
        + Values
            + `show`
            + `movie`
            + `tv`
            + `anime`
    + tmdb (optional, integer, `76757`) ... The Movie Database (TMDb) ID. To search TV Shows specify `type` parameter. All other parameters can be empty if this one specified.
    + imdb (optional, string, `tt1520211`) ... can be IMDB ID or full IMDB URL. All other parameters can be empty if this one specified.
        + Values
            + `tt1520211`
            + `http://www.imdb.com/title/tt1520211/`
    + anidb (optional, integer, `10846`) ... AniDB ID. All other parameters can be empty if this one specified.
    + crunchyroll (optional, integer, `656641`) ... Crunchyroll ID. You can pass episode ID or url ID(sword-art-online)
    + anilist (optional, integer, `21`) ... AniList ID
    + kitsu (optional, integer, `12`) ... Kitsu ID
    + livechart (optional, integer, `321`) ... LiveChart ID
    + anisearch (optional, integer, `2227`) ... aniSearch ID
    + animeplanet (optional, string, `one-piece`) ... Anime-Planet ID
    + traktslug (optional, string, `john-wick-chapter-4-2023`) ... Trakt slug
    + letterboxd (optional, string, `the-truman-show`) ... Letterboxd slug
    + client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).


Returns ratings (0-10), rank (movie, tv, anime have their own rank), external ratings (IMDB, MAL), drop rate and if we have trailers for the movie or not(add /trailer parameter to the link and the best trailer will be opened).


> possible IDs: [see Redirect method](/#reference/redirect/redirect-to-simkl-trailer-or-twitter/redirect).

+ Parameters

    + client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).
            
+ Request
`https://api.simkl.com/ratings?simkl=10280&fields=rank,droprate,simkl,ext,has_trailer,reactions,year&client_id=***`

    + Header

+ Response 200 (application/json)

    + Body
    
            {
                "id": 10280,
                "link": "https://simkl.com/tv/10280/the-big-bang-theory",
                "simkl": {
                    "rating": 7.9,
                    "votes": 3378
                },
                "release_year": "2007",
                "reactions": {
                    "total": 89,
                    "reviews": 5,
                    "comments": 18,
                    "positive": 4,
                    "negative": 0,
                    "neutral": 1
                },
                "rank": {
                    "type": "show",
                    "value": "1071"
                },
                    "droprate": "3.2%",
                    "IMDB": {
                    "rating": 8.1,
                    "votes": 895026
                },
                "has_trailer": true
                }
            
## Ratings by Watchlist [/ratings{/type}{?user_watchlist,fields,client_id}]

### Get ratings for the watchlist's items [GET]

<h4>&#128275; Token Required</h4>

#### When to use it:
Use this endpoint when you need updated ratings or release status for **items in a user’s watchlist**. For example, cached data from `/sync/` can change over time if show airing statuses or movie release information are updated.


#### What you can fetch:
- Ratings and statuses for movies, TV shows, and anime in a user’s watchlist.  
- Filter by list type (`all`,`watching`, `plantowatch`, `completed`, `dropped`, `hold`).  
- Current release status for each item (e.g., ongoing, released, ended).

It is highly recommended to  cache data for ended TV/anime shows and released movies (or items in the Completed list) for longer periods, as their average ratings and statuses rarely change.
> possible `fields` values: `simkl,link,ext,rank,release_status,year`

###### `release_status` Response:

Below is a table of possible `release_status` values by media type:

| Type | Release Status | Meaning |
|:-----------:|:-----------------------------------------|:-----------------------------------------------------------|
| **`movie`** | **`upcoming`, `rumored`, `planned`, `in production`, `post production`,`cancelled`**                         | Various states indicating the movie is not yet fully released or has been cancelled. |
|             | **`released`**                             | The movie is already out.                                  |
|
| **`tv`**    | **`upcoming`, `planned`, `in production`, `cancelled`**                             | The series is not yet released.                            |
|             | **`returning series`**                     | The series is ongoing, with more episodes/seasons planned. |
|             | **`ended`**                         | The series has finished; no new episodes will be released. |
|
| **`anime`** | **`upcoming`, `rumored` `planned`, `in production`, `post production`,`cancelled`**                             | The anime is not yet released.   
|             | **`ongoing`**                              | The anime is actively airing or has new episodes planned.  |
|             | **`ended`**                                | The anime has concluded; no new episodes are planned.      |

+ Parameters
    + type (optional, string, `anime`) 
        + Values
            + `tv`
            + `anime`
            + `movies`
    + user_watchlist = `all` (string,`watching,plantowatch`) 
        + Values
            + `all`
            + `watching`
            + `plantowatch`
            + `completed`
            + `dropped`
            + `hold`
       
    + fields (optional, string, `link,simkl,ext,rank,release_status,year`) ... 
        - A comma-separated list of additional fields to include in the response.  
            - `simkl` – returns the Simkl rating and votes.
            - `ext` – includes external ratings such as IMDB or MAL if available.  
            - `rank` – returns the rank within the Simkl service for that media type (movie, tv, anime).  
            - `release_status` – includes the release status of the item.  
            - `year` – includes the year of release.  
            - Example: `fields=rank,droprate,simkl,ext,year`
        + Values
            + `simkl`
            + `ext`
            + `rank`
            + `release_status`
            + `year`
            + `reactions`
            + `has_trailer`
            
    + client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).
            
+ Request
`https://api.simkl.com/ratings/anime/?user_watchlist=watching,plantowatch&fields=link,ext,simkl,rank,release_status,year&client_id=***`

    + Header

+ Response 200 (application/json)

    + Body
    
            [
                {
                    "id": 268470,
                    "type": "movie",
                    "link": "https:\/\/simkl.com\/movies\/268470\/tinker-bell-and-the-pirate-fairy",
                    "release_status": "released",
                    "release_year": 2014,
                    "rank": 10628,
                    "simkl": {
                        "rating": 7.1,
                        "votes": 151,
                        "droprate": "1%"
                    },
                    "imdb": {
                        "rating": 6.6,
                        "votes": 15119
                    }
                },
                {
                    "id": 2331788,
                    "type": "anime",
                    "link": "https:\/\/simkl.com\/anime\/2331788\/kamonohashi-ron-no-kindan-suiri-2nd-season",
                    "release_status": "ongoing",
                    "release_year": 2024,
                    "rank": 1561,
                    "simkl": {
                        "rating": 7,
                        "votes": 19,
                        "droprate": "3.9%"
                    },
                    "mal": {
                        "rating": 7.6,
                        "votes": 4132,
                        "rank": 1693
                    }
                }
            ]            
# Group Redirect

## Redirect to Simkl, trailer or Twitter [/redirect{?to,title,year,season,episode,client_id}]
In situations when you want to link directly to the Movie or TV show episode on Simkl from your Website or APP but don't know Simkl URL, you can use the  Redirect API.
Redirect users directly to **Simkl** page,  **Trailer** or to **Twitter** (to Share a Simkl link on Twitter with prefilled data).

### Use Cases

Here are some examples of the things you can build with the Redirect API:

- A browser extension to quickly link to Simkl based on page content.
- A website page linking directly to Simkl based on IMDB ID or TV Show name.
- Link to a trailer knowing only Movie name and year.
- Share an episode on Twitter from your browser extension.
- Get all Simkl IDs for your own API.

### Redirect [GET]
<h4>&#128275; Token Not Required</h4>
<h4>&#128274; client_id Not Required</h4>
Use this if you want to make a redirect to Simkl or (fast post) to Twitter using show's title or id. It will return "location" header.

The more parameters you'll pass, the more accurate redirect will be. Type `show` combine `tv` and `anime` types.

**Usage examples:**

https://api.simkl.com/redirect?to=Simkl&imdb=tt1520211


https://api.simkl.com/redirect?to=Simkl&imdb=https://www.imdb.com/title/tt1520211/

+ Parameters

    + to =`Simkl` (optional, string, `Simkl`) ... can be "Simkl" "trailer" or "twitter". 
        + Values
            + `Simkl`
            + `trailer`
            + `twitter`
    + title (optional, string, `The Walking Dead`) ... TV show, anime, or movie title.
    + year (optional, integer, `2010`) ... release year.
    + season = `1` (optional, integer, `1`) ... if set, movies will be ignored. Anime do not have seasons.
    + episode (optional, integer, `4`) ... if set, movies will be ignored.
    + hulu (optional, integer, `752375`) ... hulu_id. All other parameters can be empty if this one specified.
    + netflix (optional, integer, `70210890`) ... Netflix `movieid`, this parameter is in beta and may not work.
    + mal (optional, integer, `4246`) ... MyAnimeList `id`.
    + tvdb (optional, integer, `153021, the-walking-dead`) ... TVDB ID. All other parameters can be empty if this one specified.
    + type (optional, integer, `show`) ... Required for better search by tmdb title field. Use 'show' to search both anime and tv. Use 'anime' to limit the search by title in anime. 'movie' is theatrical movie, not anime movie.
        + Values
            + `show`
            + `movie`
            + `tv`
            + `anime`
    + tmdb (optional, integer, `76757`) ... The Movie Database (TMDb) ID. To search TV Shows specify `type` parameter. All other parameters can be empty if this one specified.
    + imdb (optional, string, `tt1520211`) ... can be IMDB ID or full IMDB URL. All other parameters can be empty if this one specified.
        + Values
            + `tt1520211`
            + `http://www.imdb.com/title/tt1520211/`
    + anidb (optional, integer, `10846`) ... AniDB ID. All other parameters can be empty if this one specified.
    + crunchyroll (optional, integer, `656641`) ... Crunchyroll ID. You can pass episode ID or url ID(sword-art-online)
    + anilist (optional, integer, `21`) ... AniList ID
    + kitsu (optional, integer, `12`) ... Kitsu ID
    + livechart (optional, integer, `321`) ... LiveChart ID
    + anisearch (optional, integer, `2227`) ... aniSearch ID
    + animeplanet (optional, string, `one-piece`) ... Anime-Planet ID
    + traktslug (optional, string, `john-wick-chapter-4-2023`) ... Trakt slug
    + letterboxd (optional, string, `the-truman-show`) ... Letterboxd slug
    + client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).


+ Request
    
    **Redirect to Simkl**, episode page example:
    
    https://api.simkl.com/redirect?to=Simkl&title=The%20walking%20dead&year=2010&season=1&episode=4&type=show&tmdb=1402&client_id=***

    PS: Please use your `client_id`.
    
    + Body
    
+ Response 302

    You will get "location" header (browser redirect) where the user should be redirected.
    
    In this example user will be redirected to [Simkl: The Walking Dead S01E4](https://simkl.com/tv/2090/the-walking-dead/season-1/episode-4/)

    + Headers
    
            location: //simkl.com/tv/2090/the-walking-dead/season-1/episode-4/

    + Body

+ Request
    
    **Redirect to Simkl**, based on Hulu ID example:
    
    https://api.simkl.com/redirect?to=Simkl&hulu=740489&client_id=***

    PS: Please use your `client_id`.
    
    + Body
    
+ Response 302

    You will get "location" header (browser redirect) where the user should be redirected.
    
    In this example user will be redirected to [Simkl: The Vampire Diaries S06E11](https://simkl.com/tv/15578/the-vampire-diaries/season-6/episode-11/)

    + Headers
    
            location: //simkl.com/tv/15578/the-vampire-diaries/season-6/episode-11/
    
    + Body

+ Request
    
    **Redirect to Simkl**, based on IMDB link example:
    
    https://api.simkl.com/redirect?to=Simkl&imdb=http://www.imdb.com/title/tt1520211/&client_id=***

    PS: Please use your `client_id`. You can specify IMDB ID `tt1520211` or full IMDB URL.
    
    + Body
    
+ Response 302

    You will get "location" header (browser redirect) where the user should be redirected.
    
    In this example user will be redirected to [Simkl: The Walking Dead](https://simkl.com/tv/2090/the-walking-dead)

    + Headers
    
            location: //simkl.com/tv/2090/the-walking-dead
    
    + Body

+ Request
    
    **Redirect to trailer** page example:
    
    https://api.simkl.com/redirect?to=trailer&title=Guardians%20of%20the%20Galaxy&year=2014&client_id=***

    PS: Please use your `client_id`.
    
    + Body
    
+ Response 302

    You will get "location" header (browser redirect) where the user should be redirected.
    
    In this example user will be redirected to [Simkl: Guardians of the Galaxy (2014)](https://simkl.com/movies/212566/guardians-of-the-galaxy)

    + Headers
    
            location: //simkl.com/movies/212566/guardians-of-the-galaxy

    + Body


+ Request
    
    **Post to twitter** example:
    
    https://api.simkl.com/redirect?to=twitter&title=The%20walking%20dead&year=2010&season=1&episode=4&client_id=***

    PS: Please use your `client_id`.

    + Body
    
+ Response 302

    You will get "location" header (browser redirect) where the user should be redirected.
    
    In this example user will be redirected to [twitter: Share a link with your followers](https://twitter.com/intent/tweet?text=The%20Walking%20Dead+1x04+%22Vatos%22&url=https%3A%2F%2Fsimkl.com%2Ftv%2F2090%2Fthe-walking-dead%2Fseason-1%2Fepisode-4%2F)

    + Headers
    
            location: //twitter.com/intent/tweet?text=The Walking Dead+1x04+%22Vatos%22&url=https%3A%2F%2Fsimkl.com%2Ftv%2F2090%2Fthe-walking-dead%2Fseason-1%2Fepisode-4%2F

    + Body

## Mark as watched from your website [/redirect{?to,title,year,season,episode,client_id}]
Simple href link to mark something as watched from your website or app.
### Mark as watched [GET]
<h4>&#128275; Token Not Required</h4>
<h4>&#128274; client_id Required</h4>
You can use the same parameters as in Redirect with `to=watched`.

On first use, the user will be shown the Allow dialog to allow your app mark as watched in his profile and then redirected to the episode or movie with "**Marked as watched** notification".

Currently supports marking episodes in TV Shows and Anime. If you would like mark movies or add to plan to watch list, please let us know, we'll add the functionality.

HTML example of a button: https://codepen.io/masyk/pen/BaGLmNr

+ Parameters

    + to =`watched`
    + title (optional, string, `The Walking Dead`) ... TV show, anime, or movie title.
    + year (optional, integer, `2010`) ... release year.
    + season = `1` (optional, integer, `1`) ... if set, movies will be ignored. Anime do not have seasons.
    + episode (optional, integer, `4`) ... if set, movies will be ignored.
    + hulu (optional, integer, `752375`) ... hulu_id. All other parameters can be empty if this one specified.
    + netflix (optional, integer, `70210890`) ... Netflix `movieid`, this parameter is in beta and may not work.
    + mal (optional, integer, `4246`) ... MyAnimeList `id`.
    + tvdb (optional, integer, `153021, the-walking-dead`) ... TVDB ID. All other parameters can be empty if this one specified.
    + type (optional, integer, `show`) ... Required for tmdb, if is searching for a TV Show
        + Values
            + `show`
            + `movie`
    + tmdb (optional, integer, `76757`) ... The Movie Database (TMDb) ID. To search TV Shows specify `type` parameter. All other parameters can be empty if this one specified.
    + imdb (optional, string, `tt1520211`) ... can be IMDB ID or full IMDB URL. All other parameters can be empty if this one specified.
        + Values
            + `tt1520211`
            + `http://www.imdb.com/title/tt1520211/`
    + anidb (optional, integer, `10846`) ... AniDB ID. All other parameters can be empty if this one specified.
    + crunchyroll (optional, integer, `656641`) ... Crunchyroll ID. You can pass episode ID or url ID(sword-art-online)
    + anilist (optional, integer, `21`) ... AniList ID
    + kitsu (optional, integer, `12`) ... Kitsu ID
    + livechart (optional, integer, `321`) ... LiveChart ID
    + anisearch (optional, integer, `2227`) ... aniSearch ID
    + animeplanet (optional, integer, `one-piece`) ... Anime-Planet ID
    + client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).


+ Request
    
    **Mark** The Walking Dead season 1 episode 4 **as watched** example:
    
    https://api.simkl.com/redirect?to=watched&title=The%20walking%20dead&year=2010&season=1&episode=4&type=show&tmdb=1402&client_id=***

    PS: Please use your `client_id`.
    
    + Body
    
+ Response 302

    User will be redirected to the episode page plus ?mark=watched&client_id=***.
    
    In this example user will be redirected to [Simkl: The Walking Dead S01E4](https://simkl.com/tv/2090/the-walking-dead/season-1/episode-4/?mark=watched&client_id=***)

    + Headers
    
            location: //simkl.com/tv/2090/the-walking-dead/season-1/episode-4/?marked=watched&client_id=***

    + Body
# Group Search

## ID Lookup [/search/id{?imdb,client_id}]
### Get items by ID[GET]
<h4>&#128275; Token Not Required</h4>
You can lookup items by their ID using this endpoint. Supports IMDB, TVDB, TMDB, AniDB, Hulu, Netflix, MAL, Crunchyroll ID. This method will respond with [`Standard Media Object`](/introduction/about-simkl-api/standard-media-objects).

`status` field values in response are:
    `ended`,`tba`,`airing` for anime\tv and
    `released`,`upcoming` for movies.

+ Parameters

    + simkl (optional, integer, `2090`) ... Simkl `id`. 
    + hulu (optional, integer, `752375`) ... hulu_id. All other parameters can be empty if this one specified.
    + netflix (optional, integer, `70210890`) ... Netflix `movieid`, this parameter is in beta and may not work.
    + mal (optional, integer, `4246`) ... MyAnimeList `id`.
    + tvdb (optional, integer, `153021, the-walking-dead`) ... TVDB ID. All other parameters can be empty if this one specified.
    + type (optional, integer, `show`) ... Required for tmdb, if is searching for a TV Show
        + Values
            + `show`
            + `movie`
    + tmdb (optional, integer, `76757`) ... The Movie Database (TMDb) ID. All other parameters can be empty if this one specified. `type` parameter is required if you want to search for TV Shows
    + imdb (optional, string, `tt1972591`) ... can be IMDB ID or full IMDB URL. All other parameters can be empty if this one specified.
        + Values
            + `tt1972591`
            + `http://www.imdb.com/title/tt1972591/`
    + anidb (optional, integer, `10846`) ... AniDB ID. All other parameters can be empty if this one specified.
    + crunchyroll (optional, integer, `656641`) ... Crunchyroll ID. You can pass episode ID or url ID(sword-art-online)
    + anilist (optional, integer, `21`) ... AniList ID
    + kitsu (optional, integer, `12`) ... Kitsu ID
    + livechart (optional, integer, `321`) ... LiveChart ID
    + anisearch (optional, integer, `2227`) ... aniSearch ID
    + animeplanet (optional, integer, `one-piece`) ... Anime-Planet ID
    + type  (optional, string) ... Only used when sending tmdb. 
        + Values
            + `show`
            + `movie`
    + title (optional, string, `The Walking Dead`) ... TV show, anime, or movie title. If this title has more then 1 item then null will be returned, add more fields to narrow down the search to 1 item(such as type,year etc.)
    + year (optional, integer, `2010`) ... release year.
    + client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).


+ Request 

    **Search by ID**, IMDB example:
    
    https://api.simkl.com/search/id?imdb=tt1972591&client_id=***

    PS: Please use your `client_id`.
    
    + Body
    
+ Response 200 (application/json)
        
    + Body

            [
                {
                    "type": "movie",
                    "title": "King Arthur: Legend of the Sword",
                    "poster": "28/2893788382afb90ce",
                    "year": 2017,
                    "status": "released",
                    "ids": {
                        "simkl": 388306,
                        "slug": "king-arthur-legend-of-the-sword"
                    }
                },{
                    "type": "tv",
                    "title": "The Walking Dead",
                    "poster": "16\/16913426086fc13",
                    "year": 2010,
                    "status": "ended",
                    "ids": {
                        "simkl": 2090,
                        "slug": "the-walking-dead"
                    },
                    "total_episodes": 177
                }
            ]
            
## Text [/search/{type}{?q,client_id}]
### Get items based on text query[GET]
<h4>📄 Pagination &#128275; Token Not Required &#10024; Full Info</h4>
Search items by title, sorted by relevance (what people search most). This method will respond with [`Standard Media Object`](/introduction/about-simkl-api/standard-media-objects) + additional fields if `extended` parameter passed.

For `movies` or `anime` with movie type, tmdb id points to the movies section on TMDB site, otherwise to the TV section 

Items with  `endpoint_type = anime` has additional anime `type` key, see possible values for the `anime_type` key in [`Standard Media Object`](/introduction/about-simkl-api/standard-media-objects),

Page limit is 20, max items per page is 50.

+ Parameters

    + type (required, string, `movie`) ... Search type.
        + Values
            + `tv`
            + `anime`
            + `movie`
    + q (required, string, `john wick`) ... A search term or a URL pointing to media. <br><br>When using URLs, **`type`** can be any, not required to be correct one. <br><br>Type is required for text keywords.
        + Example: `john wick`
        + Example: `john wick 2014`
        + Example: `https://www.imdb.com/title/tt2911666/` 
        + Example: `https://letterboxd.com/film/john-wick/`
    + client_id (optional, string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).


+ Request 
    **Search for text**, movie title, john wick example:
    
    https://api.simkl.com/search/movie?q=john%20wick&page=1&limit=10&client_id=***
    
    PS: Please use your `client_id`.

 + Body
    
+ Response 200 (application/json)

    + Headers
    
            Content-Type:application/json
            X-Pagination-Page:1
            X-Pagination-Limit:10
            X-Pagination-Page-Count:20
            X-Pagination-Item-Count:50
        
    + Body

        [  
           {  
              "title":"John Wick: Chapter 2",
              "year":2017,
              "poster": "54\/5465988836c0aaa33",
              "endpoint_type": "movies",
              "ids":{  
                 "simkl_id":471618,
                 "slug":"john-wick-chapter-2",
                 "tmdb":"324552"
              }
           },
           {  
              "title":"John Wick",
              "endpoint_type": "movies",
              "year":2014,
              "poster": "28\/2893788382afb90ce",
              "ids":{  
                 "simkl_id":342994,
                 "slug":"john-wick",
                 "tmdb":"245891"
              }
           },
           {  
              "title":"John Wick: Chapter 3",
              "endpoint_type": "movies",
              "year":2019,
              "poster": "57\/5747702654de3d19d",
              "ids":{  
                 "simkl_id":687232,
                 "slug":"john-wick-chapter-3"
              }
           }
        ]




+ Request 
    **Search for text with full info**, movie title, john wick example:
    
    https://api.simkl.com/search/movie?q=john%20wick&page=1&limit=10&extended=full&client_id=***
    
    PS: Please use your `client_id`.

 + Body
    
+ Response 200 (application/json)

    + Headers
    
            Content-Type:application/json
            X-Pagination-Page:1
            X-Pagination-Limit:10
            X-Pagination-Page-Count:20
            X-Pagination-Item-Count:50
        
    + Body

        [{
            "title": "John Wick: Chapter 2",
            "endpoint_type": "movies",
            "year": 2017,
            "poster": "50\/501682403c298b56c",
            "url": "\/movies\/471618\/john-wick-chapter-2",
            "rank": 2326,
            "ids": {
                "simkl_id": 471618,
                "slug": "john-wick-chapter-2",
                "tmdb":"324552"
            },
            "ratings": {
                "simkl": {
                    "rating": 7.7,
                    "votes": 360
                },
                "imdb": {
                    "rating": 7.5,
                    "votes": 249581
                }
            }
        }, {
            "title": "John Wick",
            "endpoint_type": "movies",
            "year": 2014,
            "poster": "28\/2893788382afb90ce",
            "url": "\/movies\/342994\/john-wick",
            "rank": 3998,
            "ids": {
                "simkl_id": 342994,
                "slug": "john-wick",
                "tmdb":"245891"
            },
            "ratings": {
                "simkl": {
                    "rating": 7.7,
                    "votes": 503
                },
                "imdb": {
                    "rating": 7.3,
                    "votes": 405845
                }
            }
        }, {
            "title": "John Wick: Chapter 3",
            "endpoint_type": "movies",
            "year": 2019,
            "poster": "57\/5747702654de3d19d",
            "url": "\/movies\/687232\/john-wick-chapter-3",
            "rank": null,
            "ids": {
                "simkl_id": 687232,
                "slug": "john-wick-chapter-3"
            },
            "ratings": {
                "simkl": {
                    "rating": 8.5,
                    "votes": 2
                }
            }
        }]

+ Request 
    **Search by url**, imdb anime Attack on Titan example in "movie" endpoint:
    
    https://api.simkl.com/search/movie?q=https://www.imdb.com/title/tt2560140/&page=1&limit=10&extended=full&client_id=***
    
    PS: Please use your `client_id`.

 + Body
    
+ Response 200 (application/json)

    + Headers
    
            Content-Type:application/json
            X-Pagination-Page:1
            X-Pagination-Limit:10
            X-Pagination-Page-Count:20
            X-Pagination-Item-Count:50
        
    + Body

        [
            {
                "title": "Shingeki no Kyojin",
                "title_en": "Attack on Titan (S1)",
                "title_romaji": "Shingeki no Kyojin",
                "year": 2013,
                "endpoint_type": "anime",
                "type": "tv",
                "poster": "23\/23563e7856a42e5",
                "all_titles": [
                    "Shingeki no Kyojin",
                    "Attack on Titan",
                    "\u8fdb\u51fb\u7684\u5de8\u4eba",
                    "Advancing Giants",
                    "Shingeki no Kyojin TV",
                    "Shingeki no Kyojin S1",
                    "AoT",
                    "SnK",
                    "shingeki",
                    "AoT TV"
                ],
                "url": "\/anime\/39687\/shingeki-no-kyojin",
                "ep_count": 25,
                "rank": 109,
                "status": "ended",
                "ratings": {
                    "simkl": {
                        "rating": 8.7,
                        "votes": 7715
                    },
                    "mal": {
                        "rating": 8.6,
                        "votes": 2877607,
                        "rank": 117
                    }
                },
                "ids": {
                    "simkl_id": 39687,
                    "slug": "shingeki-no-kyojin"
                }
            }
        ]
            
## File [/search/file]
### Find show, anime or movie by file[POST]
<h4>&#128275; Token Not Required</h4>
Use it if you have a filename and want to get simkl_id based on it. Right now TV Shows and Anime files can be recognized the best. Movies are harder to recognize without using the hash.

You can search by filename or by full folder+filename (see request examples).

This method will respond with [`Standard Media Object`](/introduction/about-simkl-api/standard-media-objects) + some new fields.

`multipart` = we have 2+ episodes in one filename, use `part` parameter to get necessary episode.

<h4>POSSIBLE JSON RESPONSE DATA</h4>
Key|Value|Description
---|----|-----
type|`episode`| this is an episode of a TV Show or Anime
type|`movie`| this is movie
episode: multipart |`false`| not multipart
episode: multipart |`0`| no more episodes left
episode: multipart |`1`| you can get info on one more episode after this one in this filename


+ Request (application/json)
This is an example with a file that has 2 episodes at the same time, and we're trying to get information about the first episode (part 1 of 2).
    + Headers
            simkl-api-key: [client_id]
    + Attributes
        + file: `Were.The.Fugawis.S01E01E02.WS.DSR.x264-NY2.mkv` (required, string) - Trying to find this file in our DB
        + part: `1` (optional, number) - Some filenames consist of 2 or more parts. If you want to get info about second part for example you can pass `2` to this parameter
        + hash (optional, string) - [IN_DEV]

+ Response 200 (application/json)
        
    + Body

            {
                "type": "episode",
                "show": {
                    "title": "We're the Fugawis",
                    "year": 2013,
                    "ids": {
                        "simkl": 43283,
                        "zap2it": "EP01767728",
                        "tvdb": 272581
                    }
                },
                "episode": {
                    "title": "The Fug Life",
                    "season": 1,
                    "episode": 1,
                    "multipart": 1,
                    "ids": {
                        "simkl": 967216
                    }
                }
            }
            
+ Request (application/json)
This is an example with a full file location including folders.

    + Header
            simkl-api-key: [client_id]
    + Attributes
        + file: `/series/The Office/Season 4/The Office [401] Fun Run.avi` (required, string) - You can use folders in the file request as well

+ Response 200 (application/json)
        
    + Body

            {
                "type": "episode",
                "show": {
                    "title": "The Office (US)",
                    "year": 2005,
                    "ids": {
                        "simkl": 2753,
                        "imdb": "tt0386676",
                        "zap2it": "SH00726133",
                        "netflix": "70136120",
                        "tvdb": "73244"
                    }
                },
                "episode": {
                    "title": "Fun Run (1)",
                    "season": 4,
                    "episode": 1,
                    "multipart": false,
                    "ids": {
                        "simkl": 343712
                    }
                }
            }


## Random [/search/random{?service,type,genre,rating_from,rating_to,rank_limi,year_from,year_to,limit,client_id}]
### Find random show, anime or movie [POST]
<h4>&#128275; Token Optional</h4>
Use it if you want to find random item based on your filters. If Token is passed, wacthed items will be excluded.

### Use Cases

Here are some examples of the things you can build with the Random Search API:

- Find random Netflix TV Show, Anime or Movie to watch
- Find random TV Show, Anime or Movie in Simkl database

### Requirements

"Powered by SIMKL" with a link to https://simkl.com is required on the web page or inside your app where this functionality is used.

+ Parameters
    + service = `simkl` (optional, string) ... Finds random TV Show, Anime or Movie.
        + Values
            + `netflix`
            + `simkl`
    + type (optional, integer, `tv`) ... 
        + Values
            + `tv`
            + `anime`
            + `movie`
    + genre = (optional, string, `comedy`) ... TV Shows, Anime and Movies have their own genres. <br><br><b>Movies</b>: <br>action, adventure, animation, comedy, crime, documentary, drama, erotica, family, fantasy, foreign, history, horror, music, mystery, romance, science-fiction, thriller, tv-movie, war, western<br><b>TV:</b><br>action, adventure, animation, awards-show, children, comedy, crime, documentary, drama, erotica, family, fantasy, food, game-show, history, home-and-garden, horror, indie, korean-drama, martial-arts, mini-series, musical, mystery, news, podcast, reality, romance, science-fiction, soap, special-interest, sport, suspense, talk-show, thriller, travel, war, western<br><b>Anime:</b><br>action, adventure, cars, comedy, dementia, demons, drama, ecchi, fantasy, game, harem, historical, horror, josei, kids, magic, martial-arts, mecha, military, music, mystery, parody, police, psychological, romance, samurai, school, sci-fi, seinen, shoujo, shoujo-ai, shounen, shounen-ai, slice-of-life, space, sports, super-power, supernatural, thriller, vampire, yaoi, yuri 
    + rating_from = `1` (optional, integer, `5`) ... max value is 10. Random search for TV Shows and Movies will be performed using IMDB ratings. Anime are based on MAL ratings.
    + rating_to (optional, integer, `10`)
    + rank_limit (optional, integer, `2000`) ... maximum rank allowed
    + year_from (optional, integer, `2004`) ...  First released movie starts from 1920.
    + year_to (optional, integer, `2010`)
    + limit (optional, integer, `10`) ... if >0 specified it returns 2 dimensional array with multiple results 
    + client_id (required, integer, `***`) ... If using [POST] with OAuth, it can be set in headers. If using without OAuth it's required. 
   
            
+ Request
    
    **Netflix** random example:
    
    https://api.simkl.com/search/random/netflix/?rating_from=5&rating_to=10&year_from=2008&year_to=2015&genre=science-fiction&client_id=***

    PS: Please use your `client_id`
    
       + Body
    
+ Response 302

    EDIT HERE


    + Body
    
+ Request (application/json)
    
    **Simkl** random example:

    https://api.simkl.com/search/random/?rating_from=5&rating_to=10&year_from=2008&year_to=2015&genre=science-fiction&client_id=***

    + Header
            
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
            
+ Response 200 (application/json)

    + Body
    
            {
                "id": 179868
                "url": "https://simkl.com/movies/179868/terminator-genisys"
            }

# Group Trending
Simkl provides pre-built JSON files with trending data ranked by the number of watchers. These are the same rankings displayed on [Simkl Most Watched](https://simkl.com/movies/best-movies/most-watched/) pages for [Movies](https://simkl.com/movies/best-movies/most-watched/), [TV Shows](https://simkl.com/tv/best-shows/most-watched/), and [Anime](https://simkl.com/anime/best-anime/most-watched/).

Each file is available in two sizes: **top 100** (`_100`) or **top 500** (`_500`) items. Titles with the most watchers are returned first.

The files URLs ignore all query strings, so **do not add** any additional parameters (such as **``?random=***``**).


<h3>Update Frequency</h3>

| Data | Description | Update Frequency |
|------|-------------|------------------|
| **Today** | Most watched titles over the last 24 hours | Every hour |
| **Week** | Most watched titles over the last 7 days | Once a day |
| **Month** | Most watched titles over the last 30 days | Once a day |
| **DVD Releases** | Latest popular DVD releases (Movies only) | Once a day |

**All data is cached for 1 hour on Cloudflare *(you can check the last-modified HTTP Headers for the file generation date)*.**

No API key are requred. Please set a `User-Agent` header with your app name and version (e.g. `myapp/1.0`) to avoid accidental blocking.

><h3>⚠️ Attribution Required</h3>
>
>When displaying trending data in your app or website, you **must** include attribution to Simkl in the section title.
><br><br>**Examples of accepted title formats:**
>+ `Simkl Trending Movies`
>+ `Simkl Trending Today`
>+ `Simkl Trending Movies Today`
>+ `Simkl Trending TV Shows`
>+ `Simkl Trending Anime`
>+ `Trending Movies on Simkl`
>+ `Trending on Simkl Today`
>+ `Trending on Simkl This Week`
>
>**Attribution links (for websites and sources):**
>+ https://simkl.com/movies/best-movies/most-watched/
>+ https://simkl.com/tv/best-shows/most-watched/
>+ https://simkl.com/anime/best-anime/most-watched/
>
**For commercial use without attribution, please [contact us](/#reference/need-some-help).**

<h2>List of Trending Data Files</h2>

<h3>Combined data files (Movies, TV, Anime)</h3>
These files contain Movies, TV Shows, and Anime in a single response — use them to minimize the number of requests when you need all categories at once.

| Timeframe | Top 100 | Top 500 |
|-----------|---------|---------|
| Trending Today `tv+movies+anime` | [today_100.json](https://data.simkl.in/discover/trending/today_100.json) | [today_500.json](https://data.simkl.in/discover/trending/today_500.json) |
| Trending This Week `tv+movies+anime` | [week_100.json](https://data.simkl.in/discover/trending/week_100.json) | [week_500.json](https://data.simkl.in/discover/trending/week_500.json) |
| Trending This Month `tv+movies+anime` | [month_100.json](https://data.simkl.in/discover/trending/month_100.json) | [month_500.json](https://data.simkl.in/discover/trending/month_500.json) |

<h3>Simkl Trending Movies</h3>

| Timeframe | Top 100 | Top 500 |
|-----------|---------|---------|
| Today | [movies/today_100.json](https://data.simkl.in/discover/trending/movies/today_100.json) | [movies/today_500.json](https://data.simkl.in/discover/trending/movies/today_500.json) |
| Week | [movies/week_100.json](https://data.simkl.in/discover/trending/movies/week_100.json) | [movies/week_500.json](https://data.simkl.in/discover/trending/movies/week_500.json) |
| Month | [movies/month_100.json](https://data.simkl.in/discover/trending/movies/month_100.json) | [movies/month_500.json](https://data.simkl.in/discover/trending/movies/month_500.json) |

**DVD Releases** — Latest popular DVD releases, updated once a day. Same data as shown on [Simkl DVD Releases](https://simkl.com/movies/dvd-releases/).

| Top 100 | Top 500 |
|---------|---------|
| [dvd/releases_100.json](https://data.simkl.in/discover/dvd/releases_100.json) | [dvd/releases_500.json](https://data.simkl.in/discover/dvd/releases_500.json) |

<h3>Simkl Trending TV Shows</h3>

| Timeframe | Top 100 | Top 500 |
|-----------|---------|---------|
| Today | [tv/today_100.json](https://data.simkl.in/discover/trending/tv/today_100.json) | [tv/today_500.json](https://data.simkl.in/discover/trending/tv/today_500.json) |
| Week | [tv/week_100.json](https://data.simkl.in/discover/trending/tv/week_100.json) | [tv/week_500.json](https://data.simkl.in/discover/trending/tv/week_500.json) |
| Month | [tv/month_100.json](https://data.simkl.in/discover/trending/tv/month_100.json) | [tv/month_500.json](https://data.simkl.in/discover/trending/tv/month_500.json) |

<h3>Simkl Trending Anime</h3>

| Timeframe | Top 100 | Top 500 |
|-----------|---------|---------|
| Today | [anime/today_100.json](https://data.simkl.in/discover/trending/anime/today_100.json) | [anime/today_500.json](https://data.simkl.in/discover/trending/anime/today_500.json) |
| Week | [anime/week_100.json](https://data.simkl.in/discover/trending/anime/week_100.json) | [anime/week_500.json](https://data.simkl.in/discover/trending/anime/week_500.json) |
| Month | [anime/month_100.json](https://data.simkl.in/discover/trending/anime/month_100.json) | [anime/month_500.json](https://data.simkl.in/discover/trending/anime/month_500.json) |

All trending items include Simkl rank and ratings, [poster images](/#introduction/about-simkl-api/images), as well as SIMKL, TVDB, TMDB, IMDB, and MAL IDs where available. Each item also contains additional metadata such as year, genres, country, and more that you can use to filter and sort locally in your app.

# Group TV

## Summary [/tv/{id}{?client_id}]
### Get detail info about the TV Show [GET]
<h4>&#128275; Token Not Required &#10024; Full Info</h4>
Returns a single detail info of the tv show. 

The `status` field can have these values `ended`,`tba`,`airing`

+ Parameters

    + id (required, string, `tt0944947`) ... Simkl ID or IMDB ID.
    + client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Request

    **Short info**, IMDB example:
    
   https://api.simkl.com/tv/tt0944947?client_id=***

    PS: Please use your `client_id`.
    
    + Body

+ Response 200 (application/json)
        
    + Body

        {
            "title": "Game of Thrones",
            "year": 2011,
            "type": "show",
            "ids": {
                "simkl": 17465,
                "slug": "game-of-thrones"
            }
        }

+ Request  

    **Full info**, IMDB example:
    
   https://api.simkl.com/tv/tt0944947?extended=full&client_id=***

    PS: Please use your `client_id`.
    
    + Body

+ Response 200 (application/json)
        
    + Body

        {
            "title": "Game of Thrones",
            "year": 2011,
            "type": "show",
            "ids": {
                "simkl": 17465,
                "slug": "game-of-thrones",
                "tvdb": "121361",
                "imdb": "tt0944947",
                "zap2it": "EP01389809"
            },
            "rank": 6,
            "poster": "57\/5742576cd8f59fcb0",
            "fanart": "65\/651708e80d87bb93",
            "first_aired": "2011-04-18T01:00:00Z",
            "airs": {
                "day": "Sunday",
                "time": "09:00 PM",
                "timezone": "America\/New_York"
            },
            "runtime": 55,
            "certification": "TV-MA",
            "overview": "Seven noble families fight for control of the mythical land of Westeros. Friction between the houses leads to full-scale war. All while a very ancient evil awakens in the farthest north. Amidst the war, a neglected military order of misfits, the Night's Watch, is all that stands between the realms of men and the icy horrors beyond.",
            "genres": ["Drama", "Fantasy", "Adventure"],
            "country": "US",
            "total_episodes": 67,
            "status": "airing",
            "network": "HBO",
            "ratings": {
                "simkl": {
                    "rating": 9.1,
                    "votes": 1270
                },
                "imdb": {
                    "rating": 9.5,
                    "votes": 1234933
                }
            },
            "trailers": null
        }

## Episodes [/tv/episodes/{id}{?client_id}]
### Get TV Show episodes [GET]
<h4>&#128275; Token Not Required &#10024; Full Info</h4>
Returns an array of all episodes of the TV Show

+ Parameters

    + id (required, integer) ... simkl id of the serie
    + client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Request

   https://api.simkl.com/tv/episodes/2090?client_id=***

    PS: Please use your `client_id`.
    
    + Body

+ Response 200 (application/json)
        
    + Body

        [{
            "title": "Days Gone Bye",
            "description": "Rick searches for his family after emerging from a coma into a world terrorized by the walking dead. Morgan and Duane, whom he meets along the way, help teach Rick the new rules for survival.",
            "season": 1,
            "episode": 1,
            "type": "episode",
            "img": "33\/33039065126ec2470",
            "date": "2010-10-31T00:00:00-05:00",
            "aired": true,
            "ids": {
                "simkl_id": 310766
            }
        }, {
            "title": "Guts",
            "description": "Rick unknowingly causes a group of survivors to be trapped by walkers. The group dynamic devolves from accusations to violence, as Rick must confront an enemy far more dangerous than the undead.",
            "season": 1,
            "episode": 2,
            "type": "episode",
            "img": "33\/3303806cc83f0ab83",
            "date": "2010-11-07T00:00:00-05:00",
            "aired": true,
            "ids": {
                "simkl_id": 310768
            }
        }, {
            "title": "Behind The Dead (100 Episodes Special)",
            "description": "Andrew Lincoln, Norman Reedus, and the rest of the cast and crew reflect on the history and celebrate reaching the 100th episode of The Walking Dead.",
            "type": "special",
            "img": "62\/6243336c0ad8db221",
            "date": "2017-10-19T00:00:00-05:00",
            "aired": false,
            "ids": {
                "simkl_id": 2527432
            }
        }] 
        
        
## Trending [/#reference/trending]
### Get trending TV series [GET]
Looking for trending movies, TV shows, or anime? We provide ready-to-use JSON data files with trending data ranked by the number of watchers.

**No API key or authentication required** — just fetch the JSON files directly.

The files are available in top 100 and top 500 sizes, for today, this week, and this month, across all categories (Movies, TV Shows, Anime, or combined).

👉 **See all available files and details in the [Trending data files](#reference/trending) section.**

    
## Genres [/tv/genres/{genre}/{type}/{country}/{network}/{year}/{sort}{?client_id}]
### Get items filtered by genre, years etc... [GET]
<h4>📄 Pagination &#128275; Token Not Required</h4>
Returns an array of ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))
This endpoint accepts all parameters from the https://simkl.com/tv/all/, select the necessary filters and copy parameters 
from the url. 

Genres API duplicates the urls of the Genres on the website so create a filter on the website and add it to genres API.

+ Parameters

    + genre = all (optional, string, `drama`) 
    + type = tv-shows (optional, string, `documentaries`) ... Type of the serie.
    + country = us (optional, string, `gb`) ... where the series were released
    + network = all-networks (optional, string, `netflix`) ... filter by network or production studio
    + year = 2010s (optional, string, `this-week`)
    + sort = rank (optional, string, `popular-this-month`) 
    + client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Request

   Simple query<br>
   https://api.simkl.com/tv/genres/drama/2016?client_id=***
   
   Query with all parameters<br>
   https://api.simkl.com/tv/genres/all/all-types/all-countries/hbo/all-years/popular-today?client_id=***

    PS: Please use your `client_id`.
    
    + Body

+ Response 200 (application/json)
        
    + Body

        [{
            "title": "Dirty John",
            "year": 2018,
            "date":"2018-11-09T00:00:00-05:00",
            "url": "\/tv\/877196\/dirty-john",
            "poster": "73\/73773541253a438ce",
            "ids": {
                "simkl_id": 877196,
                "slug": "dirty-john"
            },
            "rank": null,
            "ratings": {
                "simkl": {
                    "rating": 8,
                    "votes": 1
                },
                "imdb": {
                    "rating": 7.2,
                    "votes": 33
                }
            }
        }, {
            "title": "Holiday Gingerbread Showdown",
            "year": 2018,
            "date":"2018-11-07T00:00:00-05:00",
            "url": "\/tv\/962792\/holiday-gingerbread-showdown",
            "poster": "74\/74691884f61c810cd",
            "ids": {
                "simkl_id": 962792,
                "slug": "holiday-gingerbread-showdown"
            },
            "rank": null,
            "ratings": {
                "simkl": {
                    "rating": 0,
                    "votes": 0
                },
                "imdb": {
                    "rating": 0,
                    "votes": 0
                }
            }
        }]
        
             
        
## Premieres [/tv/premieres/{param}{?type}{?client_id}]
### Get latest premieres [GET]
<h4>📄 Pagination &#128275; Token Not Required</h4>
Returns an array of ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))

+ Parameters

    + param (required, string) ... 
        + Values
            + `new`
            + `soon`
    + type (optional, string, `all`) ... show only results with this type
        + Values
            + `all`
            + `entertainment`
            + `documentaries`
            + `animation-filter`
    + client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Request

   https://api.simkl.com/tv/premieres/new?client_id=***

    PS: Please use your `client_id`.
    
    + Body

+ Response 200 (application/json)
        
    + Body

        [{
            "title": "Dirty John",
            "year": 2018,
            "date":"2018-11-09T00:00:00-05:00",
            "url": "\/tv\/877196\/dirty-john",
            "poster": "73\/73773541253a438ce",
            "ids": {
                "simkl_id": 877196,
                "slug": "dirty-john"
            },
            "rank": null,
            "ratings": {
                "simkl": {
                    "rating": 8,
                    "votes": 1
                },
                "imdb": {
                    "rating": 7.2,
                    "votes": 33
                }
            }
        }, {
            "title": "Holiday Gingerbread Showdown",
            "year": 2018,
            "date":"2018-11-07T00:00:00-05:00",
            "url": "\/tv\/962792\/holiday-gingerbread-showdown",
            "poster": "74\/74691884f61c810cd",
            "ids": {
                "simkl_id": 962792,
                "slug": "holiday-gingerbread-showdown"
            },
            "rank": null,
            "ratings": {
                "simkl": {
                    "rating": 0,
                    "votes": 0
                },
                "imdb": {
                    "rating": 0,
                    "votes": 0
                }
            }
        }]
        
        
        
## Airing [/tv/airing?{date}{?sort}{?client_id}]
### Get Airing TV Shows [GET]
<h4>&#128275; Token Not Required</h4>
Returns airing TV Shows ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))

+ Parameters

    + date (optional, string, `today`) ... only data within this date
        + Values
            + `today`
            + `tomorrow`
            + `22-08-2022`
    + sort (optional, string, `time`) ... sort the results by the specified option
         + Values
            + `time`
            + `rank`
            + `popularity`
    + client_id (required, string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Request

   https://api.simkl.com/tv/airing?client_id=***

    PS: Please use your `client_id`.
    
    + Body

+ Response 200 (application/json)
        
    + Body

        [{
            "title": "High School Musical: The Musical: The Series",
            "year": 2022,
            "date": "2022-09-14T02:00:00-05:00",
            "poster": "89\/8992886023a82f72e",
            "rank": 5869,
            "url": "\/tv\/1044024\/high-school-musical-the-musical-the-series",
            "ids": {
                "simkl_id": 1044024,
                "slug": "high-school-musical-the-musical-the-series"
            },
            "episode": {
                "season": 3,
                "episode": 8,
                "url": "\/tv\/1044024\/high-school-musical-the-musical-the-series\/season-3\/episode-8"
            }
        }, {
            "title": "She-Hulk: Attorney at Law",
            "year": 2022,
            "date": "2022-09-14T03:00:00-05:00",
            "poster": "95\/95314368aad7d4e2e",
            "rank": null,
            "url": "\/tv\/1155406\/she-hulk-attorney-at-law",
            "ids": {
                "simkl_id": 1155406,
                "slug": "she-hulk-attorney-at-law"
            },
            "episode": {
                "season": 1,
                "episode": 5,
                "url": "\/tv\/1155406\/she-hulk-attorney-at-law\/season-1\/episode-5"
            }
        }]

        
        
## Best [/tv/best/{filter}{?type}{?client_id}]
### Get best of all TV Shows [GET]
<h4>&#128275; Token Not Required</h4>
Returns an array of customized ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))

+ Parameters

    + filter (required, string) ... <b>watched</b> and <b>voted</b> adds additional key in response with the same name 
        + Values
            + `year`
            + `month`
            + `all`
            + `voted`
            + `watched`
    + type (optional, string, `series`) ... secondary filter
         + Values
            + `series`
            + `documentary`
            + `entertainment`
            + `animation`
    + client_id (required, string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Request

   https://api.simkl.com/anime/best/watched?client_id=***

    PS: Please use your `client_id`.
    
    + Body

+ Response 200 (application/json)
        
    + Body

        [{
            "title": "Chilling Adventures of Sabrina",
            "year": 2018,
            "poster": "72\/7241248bcd26cf4ed",
            "url": "\/tv\/751254\/chilling-adventures-of-sabrina",
            "watched": 1656,
            "ids": {
                "simkl_id": 751254,
                "slug": "chilling-adventures-of-sabrina"
            },
            "ratings": {
                "simkl": {
                    "rating": 7.4,
                    "votes": 72
                },
                "imdb": {
                    "rating": 7.9,
                    "votes": 25391
                }
            }
        }, {
            "title": "Marvel's Daredevil",
            "year": 2015,
            "poster": "27\/2769324e0ed6160e0",
            "url": "\/tv\/51884\/marvels-daredevil",
            "watched": 1653,
            "ids": {
                "simkl_id": 51884,
                "slug": "marvels-daredevil"
            },
            "ratings": {
                "simkl": {
                    "rating": 8.3,
                    "votes": 815
                },
                "imdb": {
                    "rating": 8.7,
                    "votes": 311910
                }
            }
        }]



# Group Anime

## Summary [/anime/{id}{?client_id}]
### Get detail info about the Anime [GET]
<h4>&#128275; Token Not Required &#10024; Full Info</h4>
Returns a single detail info of the anime. Same as `/tv/summary` endpoint + added `anime_type`,`en_title` fields, possible values are `tv`,`special`,`ova`, `movie`,`music video`,`ona`.

You can use `extended=full_anime_seasons` - same as `full` + added TVDB seasons as `mapped_tvdb_seasons: [1,2]`. IMDB\TVDB\TMDB ids will also be added for 2+ seasons.

+ Parameters

    + id (required, string, `40398`) ... Simkl ID or IMDB ID. 
    + client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Request
   
    **Short info**, SIMKL ID example:
    
   https://api.simkl.com/anime/40398?client_id=***

    PS: Please use your `client_id`.
    
    + Body
    
+ Response 200 (application/json)
        
    + Body

        {
            "title": "Hunter x Hunter",
            "year": 2011,
            "type": "anime",
            "ids": {
                "simkl": 40398,
                "slug": "hunter-x-hunter"
            }
        }

+ Request
    **Full info**, SIMKL ID example:
    
   https://api.simkl.com/anime/40398?extended=full&client_id=***

    PS: Please use your `client_id`.
    
    + Body
    
+ Response 200 (application/json)
        
    + Body

        {
            "title": "Hunter x Hunter",
            "year": 2011,
            "type": "anime",
            "ids": {
                "simkl": 40398,
                "slug": "hunter-x-hunter",
                "anidb": "8550",
                "ann": "13262",
                "mal": "11061",
                "anfo": "4947",
                "wikien": "Hunter_x_hunter",
                "allcin": "340525",
                "imdb": "tt2098220",
                "offjp": "https:\/\/twitter.com\/hunter_anime",
                "crunchyroll": "hunter-x-hunter",
                "anilist": "11061",
                "kitsu": "6448",
                "livechart": "317",
                "anisearch": "7223",
                "animeplanet": "hunter-x-hunter-2011"
            },
            "en_title": null,
            "rank": 7,
            "poster": "83\/83975f751784587",
            "fanart": "83\/839789583130112",
            "first_aired": "2011-10-02T02:00:00Z",
            "airs": {
                "day": "Sunday",
                "time": "11:00 AM",
                "timezone": "Asia\/Tokyo"
            },
            "runtime": 25,
            "certification": null,
            "overview": "A remake of the original series with different staff and cast.<br><br>Gon is a youth who lives on Kujira Isle. His dream is to become a Hunter like his father, to search out lost treasures, artefacts, and mythical creatures.<br><br>Determined to become a professional Hunter willing to stake his life in challenging the unknown, he sets off on a journey and meets fellow Hunter wannabes Killua, Kurapika, and Leorio.",
            "genres": ["Action", "Adventure", "Comedy"],
            "country": "JP",
            "total_episodes": 148,
            "status": "ended",
            "network": "NTV",
            "anime_type": "tv",
            "ratings": {
                "simkl": {
                    "rating": 8.9,
                    "votes": 248
                },
                "imdb": {
                    "rating": 7.6,
                    "votes": 1077
                },
                "mal": {
                    "rating": 9.1,
                    "votes": 324100,
                    "rank": 7
                }
            },
            "trailers": [{
                "name":null,
                "youtube":"t0xuqi2qvxY",
                "size":720
            }],
            "users_recommendations":[{
                "title": "Overlord",
                "en_title": null,
                "year": 2015,
                "poster": "69\/69770748206def778",
                "anime_type": "tv",
                "users_percent": "34%",
                "users_count": 23,
                "ids": {
                    "simkl": 415932,
                    "slug": "overlord"
                }
            }, {
                "title": "Tate no Yuusha no Nariagari",
                "en_title": "The Rising of the Shield Hero",
                "year": 2018,
                "poster": "74\/74755663f6cfe2818",
                "anime_type": "tv",
                "users_percent": "7%",
                "users_percent": 5,
                "ids": {
                    "simkl": 695799,
                    "slug": "tate-no-yuusha-no-nariagari"
                }
            }, {
                "title": "Isekai wa Smartphone to Tomo ni.",
                "en_title": "In Another World with My Smartphone",
                "year": 2017,
                "poster": "56\/56612089b2d99025c",
                "anime_type": "tv",
                "users_percent": "7%",
                "users_percent": 4,
                "ids": {
                    "simkl": 670707,
                    "slug": "isekai-wa-smartphone-to-tomo-ni"
                }
            }]
        }
        
        
## Episodes [/anime/episodes/{id}{?client_id}]
### Get Anime episodes [GET]
<h4>&#128275; Token Not Required &#10024; Full Info</h4>
Returns an array of all episodes of the Anime

You can use `extended=full_anime_seasons` - same as `full`  + TVDB season and episode numbers for every episode.

+ Parameters

    + id (required, integer) ... simkl id of the anime
    + client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Request

   https://api.simkl.com/anime/episodes/39687?client_id=***

    PS: Please use your `client_id`.
    
    + Body

+ Response 200 (application/json)
        
    + Body

        [{
            "title": "To You, 2000 Years in the Future: The Fall of Zhiganshina (1)",
            "description": null,
            "episode": 1,
            "type": "episode",
            "aired": true,
            "img": "26\/26148581d640c58b8",
            "date": "2013-04-07T00:00:00+09:00",
            "ids": {
                "simkl_id": 958466
            }
        }, {
            "title": "That Day: The Fall of Zhiganshina (2)",
            "description": null,
            "episode": 2,
            "type": "episode",
            "aired": true,
            "img": "26\/2614860d56b63e7b6",
            "date": "2013-04-14T00:00:00+09:00",
            "ids": {
                "simkl_id": 958465
            }
        }, {
            "title": "Picture Drama 3",
            "description": null,
            "type": "special",
            "aired": true,
            "img": "68\/689124d248604d0d",
            "date": "2013-09-18T00:00:00+09:00",
            "ids": {
                "simkl_id": 979612
            }
        }] 
        
+ Request

   https://api.simkl.com/anime/episodes/39687?extended=full_anime_seasons&client_id=***

    PS: Please use your `client_id`.
    
    + Body

+ Response 200 (application/json)
        
    + Body
        [
          {
            "episode": 1,
            "type": "episode",
            "aired": true,
            "img": null,
            "date": "2021-04-09T01:28:00+09:00",
            "ids": {
              "simkl_id": 7938475
            },
            "tvdb": {
              "season": 2,
              "episode": 1
            }
          },
          {
            "episode": 2,
            "type": "episode",
            "aired": true,
            "img": null,
            "date": "2021-04-16T01:28:00+09:00",
            "ids": {
              "simkl_id": 7938477
            },
            "tvdb": {
              "season": 2,
              "episode": 2
            }
          },
          {
            "episode": 3,
            "type": "episode",
            "aired": true,
            "img": null,
            "date": "2021-04-23T01:28:00+09:00",
            "ids": {
              "simkl_id": 7938479
            },
            "tvdb": {
              "season": 2,
              "episode": 3
            }
          }
        ]

     
     
        
## Trending [/#reference/trending]
### Get trending TV series [GET]
Looking for trending movies, TV shows, or anime? We provide ready-to-use JSON data files with trending data ranked by the number of watchers.

**No API key or authentication required** — just fetch the JSON files directly.

The files are available in top 100 and top 500 sizes, for today, this week, and this month, across all categories (Movies, TV Shows, Anime, or combined).

👉 **See all available files and details in the [Trending data files](#reference/trending) section.**
    

## Genres [/anime/genres/{genre}/{type}/{network}/{year}/{sort}{?client_id}]
### Get items filtered by genre, years etc... [GET]
<h4>📄 Pagination &#128275; Token Not Required</h4>
Returns an array of ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))
This endpoint accepts all parameters from https://simkl.com/anime/all/, select necessary filters and copy parameters 
from the url.

Genres API duplicates the urls of the Genres on the website so create a filter on the website and add it to genres API.

+ Parameters

    + genre = all (optional, string, `drama`) 
    + type = all-types (optional, string, `series`) ... Type of the serie.
    + network = all-networks (optional, string, `tvtokyo`) ... filter by network or production studio
    + year = 2010s (optional, string, `this-week`)
    + sort = rank (optional, string, `popular-this-month`) 
    + client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Request

   Simple query<br>
   https://api.simkl.com/anime/genres/drama/2016?client_id=***
   
   Query with all parameters<br>
   https://api.simkl.com/anime/genres/all/all-types/all-countries/tvtokyo/all-years/popular-today?client_id=***

   PS: Please use your `client_id`.
    
    + Body

+ Response 200 (application/json)
        
    + Body

        [{
            "title": "Kaijuu Girls (Kuro): Ultra Kaijuu Gijinka Keikaku",
            "year": 2018,
            "date": "2018-11-23T00:00:00+09:00",
            "url": "\/anime\/786725\/kaijuu-girls-kuro-ultra-kaijuu-gijinka-keikaku",
            "poster": "70\/708168593fa555f00",
            "ids": {
                "simkl_id": 786725,
                "slug": "kaijuu-girls-kuro-ultra-kaijuu-gijinka-keikaku"
            },
            "rank": null,
            "anime_type": "movie",
            "ratings": {
                "simkl": {
                    "rating": 10,
                    "votes": 1
                },
                "mal": {
                    "rating": 0,
                    "votes": 0
                }
            }
         }, {
                "title": "Koi to Uso",
                "year": 2018,
                "date": "2018-11-22T00:00:00+09:00",
                "url": "\/anime\/801411\/koi-to-uso",
                "poster": "67\/671515560e5acee15",
                "ids": {
                    "simkl_id": 801411,
                    "slug": "koi-to-uso"
                },
                "rank": 4126,
                "anime_type": "tv",
                "ratings": {
                    "simkl": {
                        "rating": 5,
                        "votes": 1
                    },
                    "mal": {
                        "rating": 6.67,
                        "votes": 65
                    }
                }
            }
        ]
        
        
## Premieres [/anime/premieres/{param}{?type}{?client_id}]
### Get latest premieres [GET]
<h4>📄 Pagination &#128275; Token Not Required</h4>
Returns an array of ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects)). Added `anime_type` field, possible values are `tv`,`special`,`ova`,`movie`,`music video`,`ona`.

+ Parameters

    + param (required, string) ... 
        + Values
            + `new`
            + `soon`
    + type (optional, string,`all`) ... show only results with this type
        + Values
            + `all`
            + `series`
            + `movies`
            + `ovas`        
    + client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Request

   https://api.simkl.com/anime/premieres/new?client_id=***

    PS: Please use your `client_id`.
    
    + Body

+ Response 200 (application/json)
        
    + Body

        [{
            "title": "Kaijuu Girls (Kuro): Ultra Kaijuu Gijinka Keikaku",
            "year": 2018,
            "date": "2018-11-23T00:00:00+09:00",
            "url": "\/anime\/786725\/kaijuu-girls-kuro-ultra-kaijuu-gijinka-keikaku",
            "poster": "70\/708168593fa555f00",
            "ids": {
                "simkl_id": 786725,
                "slug": "kaijuu-girls-kuro-ultra-kaijuu-gijinka-keikaku"
            },
            "rank": null,
            "anime_type": "movie",
            "ratings": {
                "simkl": {
                    "rating": 10,
                    "votes": 1
                },
                "mal": {
                    "rating": 0,
                    "votes": 0
                }
            }
         }, {
                "title": "Koi to Uso",
                "year": 2018,
                "date": "2018-11-22T00:00:00+09:00",
                "url": "\/anime\/801411\/koi-to-uso",
                "poster": "67\/671515560e5acee15",
                "ids": {
                    "simkl_id": 801411,
                    "slug": "koi-to-uso"
                },
                "rank": 4126,
                "anime_type": "tv",
                "ratings": {
                    "simkl": {
                        "rating": 5,
                        "votes": 1
                    },
                    "mal": {
                        "rating": 6.67,
                        "votes": 65
                    }
                }
            }
        ]



## Airing [/anime/airing?{date}{?sort}{?client_id}]
### Get Airing Anime [GET]
<h4>&#128275; Token Not Required</h4>
Returns ongoing Anime ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))

+ Parameters

    + date (optional, string, `today`) ... only data within this date
        + Values
            + `today`
            + `tomorrow`
            + `22-08-2022`
    + sort (optional, string, `time`) ... sort the results by the specified option
         + Values
            + `time`
            + `rank`
            + `popularity`
    + client_id (required, string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Request

   https://api.simkl.com/anime/airing?client_id=***

    PS: Please use your `client_id`.
    
    + Body

+ Response 200 (application/json)
        
    + Body

        [
            {
                "title": "Nights with a Cat",
                "year": 2022,
                "date": "2022-09-14T12:00:00-05:00",
                "poster": "12\/125209937fa1674c4b",
                "rank": null,
                "url": "\/anime\/1897462\/yoru-wa-neko-to-issho",
                "ids": {
                    "simkl_id": 1897462,
                    "slug": "yoru-wa-neko-to-issho"
                },
                "episode": {
                    "episode": 14,
                    "url": "\/anime\/1897462\/yoru-wa-neko-to-issho\/episode-14"
                },
                "anime_type": "tv"
            }, {
                "title": "Throne of Seal",
                "year": 2022,
                "date": null,
                "poster": "12\/12540566cc860eeeb0",
                "rank": 4469,
                "url": "\/anime\/1902682\/shen-yin-wangzuo",
                "ids": {
                    "simkl_id": 1902682,
                    "slug": "shen-yin-wangzuo"
                },
                "episode": {
                    "episode": 23,
                    "url": "\/anime\/1902682\/shen-yin-wangzuo\/episode-23"
                },
                "anime_type": "ona"
            }
        ]



## Best [/anime/best/{filter}{?type}{?client_id}]
### Get best of all Anime [GET]
<h4>&#128275; Token Not Required</h4>
Returns an array of customized ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))

+ Parameters

    + filter (required, string) ... <b>watched</b> and <b>voted</b> adds additional key in response with the same name 
        + Values
            + `year`
            + `month`
            + `all`
            + `voted`
            + `watched`
    + type (optional, string, `all`) ... secondary filter
         + Values
            + `all`
            + `tv`
            + `movies`
            + `ovas`
            + `music`
            + `onas`
    + client_id (required, string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Request

   https://api.simkl.com/anime/best/watched?client_id=***

    PS: Please use your `client_id`.
    
    + Body

+ Response 200 (application/json)
        
    + Body

        [{
            "title": "One Piece",
            "year": 1999,
            "poster": "72\/7248108487b1ea37",
            "url": "\/anime\/38636\/one-piece",
            "watched": 765,
            "ids": {
                "simkl_id": 38636,
                "slug": "one-piece"
            },
            "ratings": {
                "simkl": {
                    "rating": 8.7,
                    "votes": 774
                },
                "mal": {
                    "rating": 8.5,
                    "votes": 453616
                }
            }
        }, {
            "title": "Boruto: Naruto Next Generations",
            "year": 2017,
            "poster": "68\/6816448e6eb41797e",
            "url": "\/anime\/643731\/boruto-naruto-next-generations",
            "watched": 577,
            "ids": {
                "simkl_id": 643731,
                "slug": "boruto-naruto-next-generations"
            },
            "ratings": {
                "simkl": {
                    "rating": 7.7,
                    "votes": 183
                },
                "mal": {
                    "rating": 6.9,
                    "votes": 94697
                }
            }
        }]

    
        
# Group Movies

## Summary [/movies/{id}{?client_id}]
### Get detail info about the movie [GET]
<h4>&#128275; Token Not Required &#10024; Full Info</h4>
Returns a single detail info about the movie.


+ Parameters

    + id (required, string, `tt1201607`) ... Simkl ID or IMDB ID.
    + client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Request

    **Short info**, IMDB example:
    
   https://api.simkl.com/movies/tt1201607?client_id=***

    PS: Please use your `client_id`.
    
    + Body
    
+ Response 200 (application/json)
        
    + Body

        {
            
            "title": "Harry Potter and the Deathly Hallows: Part 2",
            "year": 2011,
            "type": "movie",
            "ids": {
                "simkl": 67144,
                "slug": "harry-potter-and-the-deathly-hallows-part-2"
            }
        }
        
+ Request

    **Full info**, IMDB example:
    
   https://api.simkl.com/movies/tt1201607?extended=full&client_id=***

    PS: Please use your `client_id`.
    
    + Body
    
+ Response 200 (application/json)
        
    + Body

        {
            "title": "Harry Potter and the Deathly Hallows: Part 2",
            "year": 2011,
            "type": "movie",
            "ids": {
                "simkl": 67144,
                "slug": "harry-potter-and-the-deathly-hallows-part-2",
                "tmdb": "12445",
                "imdb": "tt1201607",
                "offen": "http:\/\/www.harrypotter.com"
            },
            "rank": 641,
            "poster": "96\/967506e32f7921d4",
            "fanart": "96\/967624d7a281067c",
            "released": "2011-07-15",
            "runtime": 130,
            "director": "David Yates",
            "certification": "PG",
            "budget": 125000000,
            "revenue": 1342000000,
            "overview": "Harry, Ron and Hermione continue their quest to vanquish the evil Voldemort once and for all. Just as things begin to look hopeless for the young wizards, Harry discovers a trio of magical objects that endow him with powers to rival Voldemort's formidable skills.",
            "genres": ["Adventure", "Family", "Fantasy"],
            "country": "US",
            "ratings": {
                "simkl": {
                    "rating": 8.1,
                    "votes": 427
                },
                "imdb": {
                    "rating": 8.1,
                    "votes": 607002
                }
            },
            "trailers": [{
                "name": "Official Trailer 1",
                "youtube": "mObK5XD8udk",
                "size": 1080
            }, {
                "name": "Official Trailer 2",
                "youtube": "5NYt1qirBWg",
                "size": 1080
            }, {
                "name": "The Story of Snape",
                "youtube": "2nPyasEm3g0",
                "size": 720
            }],
            "release_dates": [{
                "iso_3166_1": "BR",
                "results": [{
                    "type": 3,
                    "release_date": "2011-07-15"
                }]
            }, {
                "iso_3166_1": "CZ",
                "results": [{
                    "type": 3,
                    "release_date": "2011-07-14"
                }]
            }, {
                "iso_3166_1": "DE",
                "results": [{
                    "type": 5,
                    "release_date": "2013-08-30"
                }]
            }, {
                "iso_3166_1": "DK",
                "results": [{
                    "type": 3,
                    "release_date": "2011-07-13"
                }]
            }, {
                "iso_3166_1": "EG",
                "results": [{
                    "type": 3,
                    "release_date": "2011-07-13"
                }]
            }, {
                "iso_3166_1": "FI",
                "results": [{
                    "type": 3,
                    "release_date": "2011-07-13"
                }]
            }, {
                "iso_3166_1": "FR",
                "results": [{
                    "type": 3,
                    "release_date": "2011-07-12"
                }]
            }, {
                "iso_3166_1": "GB",
                "results": [{
                    "type": 3,
                    "release_date": "2011-07-07"
                }]
            }, {
                "iso_3166_1": "US",
                "results": [{
                    "type": 5,
                    "release_date": "2011-11-11"
                }, {
                    "type": 3,
                    "release_date": "2011-07-15"
                }]
            }]
        }
        

## Trending [/#reference/trending]
### Get trending TV series [GET]
Looking for trending movies, TV shows, or anime? We provide ready-to-use JSON data files with trending data ranked by the number of watchers.

**No API key or authentication required** — just fetch the JSON files directly.

The files are available in top 100 and top 500 sizes, for today, this week, and this month, across all categories (Movies, TV Shows, Anime, or combined).

👉 **See all available files and details in the [Trending data files](#reference/trending) section.**


## Genres [/movies/genres/{genre}/{type}/{country}/{year}/{sort}{?client_id}]
### Get items filtered by genre, years, etc... [GET]

<h4>📄 Pagination &#128275; Token Not Required</h4>
Returns an array of ([Standard Media Object](#introduction/about-simkl-api/standard-media-objects))
This endpoint accepts all parameters from the [https://simkl.com/movies/all/](https://simkl.com/movies/all/), select the necessary filters and copy parameters from the URL.

Genres API duplicates the URLs of the Genres on the website, so create a filter on the website and add it to the genres API.

+ Parameters

    + genre = all (optional, string, `action`)
    + country = us (optional, string, `gb`) ... Where the movie was released.
    + year = 2010s (optional, string, `this-week`)
    + sort = rank (optional, string, `popular-this-month`)
    + client_id (string, `***`) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Request

   Simple query
   `https://api.simkl.com/movies/genres/action/2016?client_id=***`

   Query with all parameters
   `https://api.simkl.com/movies/genres/all/all-types/all-countries/all-years/popular-today?client_id=***`

    PS: Please use your `client_id`.
    
+ Response 200 (application/json)
        
    + Body

        ```json
        [
            {
                "title": "Toy Story 3",
                "year": 2010,
                "date": "2010-06-16T00:00:00-05:00",
                "url": "/movies/63604/toy-story-3",
                "poster": "92/9239026bcfa0c731",
                "fanart": "92/9240427e874c8c23",
                "ids": {
                    "simkl_id": 63604,
                    "slug": "toy-story-3",
                    "tmdb": 10193
                },
                "rank": 186,
                "ratings": {
                    "simkl": {
                        "rating": 7.8,
                        "votes": 2742
                    },
                    "imdb": {
                        "rating": 8.3,
                        "votes": 907118
                    }
                }
            },
            {
                "title": "Dangal",
                "year": 2016,
                "date": "2016-12-21T00:00:00-05:00",
                "url": "/movies/524600/dangal",
                "poster": "53/5327482ea7bd7c77b",
                "fanart": "16/161418093805d34562",
                "ids": {
                    "simkl_id": 524600,
                    "slug": "dangal",
                    "tmdb": 360814
                },
                "rank": 203,
                "ratings": {
                    "simkl": {
                        "rating": 7.9,
                        "votes": 377
                    },
                    "imdb": {
                        "rating": 8.3,
                        "votes": 216570
                    }
                }
            },
            {
                "title": "Dave Chappelle: Sticks & Stones",
                "year": 2019,
                "date": "2019-08-26T00:00:00-05:00",
                "url": "/movies/1153930/dave-chappelle-sticks-and-stones",
                "poster": "84/84381468a25ffcf5d",
                "fanart": "11/11782778acd57d3e71",
                "ids": {
                    "simkl_id": 1153930,
                    "slug": "dave-chappelle-sticks-and-stones",
                    "tmdb": 624932
                },
                "rank": 244,
                "ratings": {
                    "simkl": {
                        "rating": 7.7,
                        "votes": 196
                    },
                    "imdb": {
                        "rating": 8.3,
                        "votes": 28318
                    }
                }
            }
        ]
        ```

# Group Scrobble
Scrobbling lets apps report real-time playback progress. Use it when a user starts, pauses, or stops watching. If you want to instantly mark an item as watched without scrobbling, use [Sync - add to history](#reference/sync/add-items-to-the-history).

Pass as much data as possible (title, year, ids) so Simkl can detect the item reliably.

Progress is a percentage from 0.00 to 100.00 (input format: flexible, max 2 decimal places, e.g., `75`, `75.0`, `75.12`; response format: standardized, e.g., `75`, `75.12`, `45.5`).
Scrobble id is a 64bit integer


### Supported ID keys (inside `ids`)

| ID key       | Description                |
|-------------|-----------------------------|
| **simkl**   | Simkl internal ID (e.g. `49108`, `1265720`, `437940`) |
| **anidb**   | AniDB ID. All other parameters can be empty if this one specified. Example: `10846`. Integer. |
| **anilist** | AniList ID. Example: `21`. Integer. |
| **animeplanet** | Anime-Planet ID. Example: `one-piece`. String. |
| **anisearch** | aniSearch ID. Example: `2227`. Integer. |
| **imdb**    | IMDb ID or full URL. Example: `tt1520211`. String. |
| **kitsu**   | Kitsu ID. Example: `12`. Integer. |
| **letterboxd** | Letterboxd slug. Example: `the-truman-show`. String. |
| **livechart** | LiveChart ID. Example: `321`. Integer. |
| **mal**     | MyAnimeList ID. Example: `4246`. Integer. |
| **netflix** | Netflix movieid. Example: `70210890`. Integer. |
| **tmdb**    | The Movie Database (TMDb) ID. For TV shows specify `type`. Example: `76757`. Integer. |
| **tvdb**    | TVDB ID. Example: `153021`, `the-walking-dead`. Integer or string. |
| **traktslug** | Trakt slug. Example: `john-wick-chapter-4-2023`. String. |

## Overview
Simkl stores only **one active scrobble session per show/movie/anime**. Starting a new session replaces any existing one for that item and clears previous pauses. Paused sessions (created by `/scrobble/pause` or `/scrobble/stop` with <80% progress) can be retrieved via [Get Playbacks](#reference/sync/playback/get-playback-sessions) and resumed by calling `/scrobble/start` with the same item. To delete a paused session, use [Delete Playback](#reference/sync/playback/delete-playback).

**Typical Flow:**
1. Call `/scrobble/start` when playback begins.
2. Call `/scrobble/pause` to save progress if paused.
3. Call `/scrobble/stop` when finished (marks as watched if ≥80% complete).
4. If activity endpoint has `playback` updated, retrieve paused sessions with `/sync/playback/{type}`.
5. Delete unwanted paused sessions with `DELETE /sync/playback/{id}`.

> Members can view and manage their saved playbacks at [https://simkl.com/my/history/playback-progress-manager/](https://simkl.com/my/history/playback-progress-manager/).


**Action Types in Responses:**
- `"start"` - Returned by `/scrobble/start` when beginning or resuming playback
- `"pause"` - Returned by `/scrobble/pause` or `/scrobble/stop` when progress < 80%
- `"scrobble"` - Returned by `/scrobble/stop` when progress ≥ 80% (marks as watched)

**Session Management:**
- **Expiry timestamps**: Start sessions get expiry = current time + remaining runtime; stop sessions get expiry = current time + 1 hour; pause sessions get expiry = current time
- **Persistence**: All sessions persist in the playback until manually removed (no automatic cleanup) or until replaced by next scrobble update for that title, and are retained based on the user&#39;s subscription plan: Free (7 days), PRO (30 days), VIP (90 days)
- **Rate limiting**: One scrobble operation per user at a time (20-second lock timeout)
- **Duplicate prevention**: 409 response if trying to stop an already completed session within 1 hour

Note: in Sync playback responses, `progress` is returned as a percentage (float number from 0 to 100, e.g., `0`, `45.5`, `75`, `100`). While you can POST `75.00`, the response will always be `75`.

**Anime Episode Numbering:** Simkl uses AniDB as the primary source for anime data, which has different season/episode numbering than TMDB/TVDB. When you send anime scrobbles using TMDB season/episode numbers, Simkl maps them to the corresponding AniDB episode numbers. The response includes both the Simkl\AniDB episode numbers (`season`, `number`) and the original TVDB numbers (`tvdb_season`, `tvdb_number`) for reference. For example, TMDB Season 2 Episode 4 might map to Simkl\AniDB Season 1 Episode 4, as shown in the anime examples below.

#### JSON POST DATA
| Key         | Type                | Value                                                                                                                                     |
| ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| progress*   | float               | Playback progress percent `0–100` (e.g., `75`, `75.0`, `75.5`, `75.00`).                                                     |
| movie       | object              | [movie object](/introduction/about-simkl-api/standard-media-objects)                                                                |
| show        | object              | [show object](/introduction/about-simkl-api/standard-media-objects)|
| anime       | object              | [anime object](/introduction/about-simkl-api/standard-media-objects)|
| episode     | object              | Include an `episode` with `show` or `anime` object |

Either `movie`, `show` + `episode`, or `anime` + `episode` objects are required.

## Start [/scrobble/start]
### Start watching [POST]
<h4>&#128274; Token Required</h4>
Creates or replaces the current scrobble session for the user and item. Sets the user's internal "watching now" status. Call this when playback begins or to resume a paused session. The response includes the `progress` sent in the request, returned as a float.

**When to use:** On video start, or to resume from a paused session (retrieved via [Get Playbacks](#reference/sync/playback/get-playback-sessions)). The session auto-ends after the item's runtime elapses if no pause/stop is called.

**Behavior:** Replaces any existing session for this item and clears previous pauses. Does not mark the item as watched. Session auto-expires after calculated runtime based on item length and current progress.

+ Request (application/json)
    Start watching a movie using IMDB and TMDB IDs
    
   
    + Headers
    
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
    + Body

          {
            "progress": 12.5,
            "movie": {
              "title": "Inception",
              "year": 2010,
              "ids": {
                "imdb": "tt1375666",
                "tmdb": 27205
              }
            }
          }

+ Response 201 (application/json)
    **Note**: Only `/scrobble/start` returns `id: 0`. `/scrobble/pause` and `/scrobble/stop` return a 64bit `id`.<br><br>On a 409 conflict (already completed within an hour), the response includes `watched_at` and `expires_at` instead of `id`.<br><br> Calling `/scrobble/start` also sets the user's internal "watching now" status start session for this item (clearing previous pauses).


    + Body
    
          {
            "id": 0,
            "action": "start",
            "progress": 70,
            "movie": {
              "title": "Inception",
              "year": 2010,
              "anime_type": null,
              "ids": {
                "simkl": 472214,
                "slug": "inception",
                "imdb": "tt1375666",
                "letterslug": "inception",
                "tmdb": "27205",
                "tvdbslug": "inception"
              }
            }
          }
            

+ Request (application/json)
    Start watching a TV show episode using IMDB ID
    + Headers
    
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
    + Body
    
          {
            "progress": 42.0,
            "show": {
              "title": "Stranger Things",
              "year": 2016,
              "ids": {
                "imdb": "tt4574334"
              }
            },
            "episode": {
              "season": 1,
              "number": 3
            }
          }

    
+ Response 201 (application/json)

     + Body
    
          {
            "id": 0,
            "action": "start",
            "progress": 42,
            "show": {
              "title": "Stranger Things",
              "year": 2016,
              "ids": {
                "simkl": 548312,
                "imdb": "tt4574334" 
              }
            },
            "episode": { 
              "season": 1, 
              "number": 3,
              "title": "Chapter Three: Holly, Jolly"
            }
          }

+ Request (application/json)
    Start watching an anime TV episode using TMDB ID (maps to AniDB episode numbering)
    + Headers
    
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
    + Body
    
          {
            "progress": 42.2,
            "anime": {
              "ids": {
                 "tmdb": 1429
              }
            },
            "episode": {
              "season": 2,
              "number": 4
            }
          }

+ Response 201 (application/json)

     + Body
        {
            "id": 0,
            "action": "start",
            "progress": 42.2,
            "episode": {
                "season": 1,
                "number": 4,
                "title": "Soldier",
                "tvdb_season": 2,
                "tvdb_number": 4
            },
            "anime": {
                "title": "Shingeki no Kyojin Season 2",
                "year": 2017,
                "anime_type": "tv",
                "ids": {
                    "simkl": 439744,
                    "slug": "shingeki-no-kyojin-season-2",
                    "mal": "25777",
                    "anilist": "20958",
                    "kitsu": "8671",
                    "anidb": "10944"
                }
            }
        }

+ Request (application/json)
    Start watching an anime movie using MAL ID
    + Headers

            Authorization: Bearer [token]
            simkl-api-key: [client_id]
    + Body

          {
            "progress": 25.5,
            "anime": {
              "ids": {
                 "mal": 37987
              }
            }
          }

+ Response 201 (application/json)

     + Body
        {
            "id": 0,
            "action": "start",
            "progress": 25.5,
            "anime": {
                "title": "Violet Evergarden the Movie",
                "year": 2020,
                "anime_type": "movie",
                "ids": {
                    "simkl": 799363,
                    "slug": "gekijouban-violet-evergarden",
                    "mal": "37987",
                    "anilist": "103047",
                    "kitsu": "41450",
                    "anidb": "14013"
                }
            }
        }


## Pause [/scrobble/pause]
### Pause watching [POST]
<h4>&#128274; Token Required</h4>
Pauses an active scrobble session and saves the current progress to the database for later resumption. The response includes the `progress` sent in the request, returned as a float.

**When to use:** Call when the user pauses playback to save progress without marking as watched. This creates a paused session that can be retrieved later via [Get Playbacks](#reference/sync/playback/get-playback-sessions).

**Behavior:** Adds a pause event to the DB. Does not mark the item as watched. The paused session can be resumed by calling `/scrobble/start` with the same item.

+ Request (application/json)
    Pause watching a TV show episode using Simkl and TMDB IDs
    + Headers
    
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
    
    + Body
    
            {
                "show": {
                    "ids": {
                        "simkl": 12345,
                        "tmdb": 1429
                    }
                },
                "episode": {
                    "season": 1,
                    "number": 1
                },
                "progress": 45.5
            }

+ Response 201 (application/json)
    + Body
    
            {
                "id": 312312312123,
                "action": "pause",
                "progress": 45.5,
                "episode": {
                    "season": 1,
                    "number": 1,
                    "title": "Episode 1"
                },
                "show": {
                    "title": "Breaking Bad",
                    "year": 2008,
                    "ids": {
                        "simkl": 12345,
                        "slug": "breaking-bad",
                        "tmdb": 1429
                    }
                }
            }
            
+ Request (application/json)
    + Headers
    
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
    + Body
    
          {
            "progress": 42.2,
            "anime": {
              "ids": {
                 "tmdb": 1429
              }
            },
            "episode": {
              "season": 2,
              "number": 4
            }
          }

+ Response 201 (application/json)

     + Body
        {
            "id": 1123123124120,
            "action": "pause",
            "progress": 42.2,
            "episode": {
                "season": 1,
                "number": 4,
                "title": "Soldier",
                "tvdb_season": 2,
                "tvdb_number": 4
            },
            "anime": {
                "title": "Shingeki no Kyojin Season 2",
                "year": 2017,
                "anime_type": "tv",
                "ids": {
                    "simkl": 439744,
                    "slug": "shingeki-no-kyojin-season-2",
                    "mal": "25777",
                    "anilist": "20958",
                    "kitsu": "8671",
                    "anidb": "10944"
                }
            }
        }
        

## Stop [/scrobble/stop]
### Stop watching [POST]
<h4>&#128274; Token Required</h4>

Stops the current scrobble session and marks the item as watched if progress is ≥80%, otherwise saves it as a paused session. The response includes the `progress` sent in the request, returned as a float.

**When to use:** Call when playback ends. If progress `>= 80%`, the item is marked as watched. If `progress < 80%`, it behaves like a pause (saves progress for later resumption).

**Behavior:** If `>= 80%` complete, adds to watch history and marks as watched. If `< 80%`, creates a paused session (like `/scrobble/pause`). 

There’s duplicate protection for stop/pause events at `>= 80%` progress. Any additional stop/pause events for the same movie or episode will be ignored, and a 409 response code will be returned. Duplicate protection lasts for 1 hour.

+ Request (application/json)
    Stop watching a TV show episode with 85% progress (marks as watched)
    + Headers
    
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
    
    + Body
    
            {
                "show": {
                    "ids": {
                        "simkl": 12345,
                        "tmdb": 1429
                    }
                },
                "episode": {
                    "season": 1,
                    "number": 1
                },
                "progress": 85.0
            }

+ Response 201 (application/json)
    + Body
    
            {
                "id": 124,
                "action": "scrobble",
                "progress": 85,
                "episode": {
                    "season": 1,
                    "number": 1,
                    "title": "Episode 1"
                },
                "show": {
                    "title": "Breaking Bad",
                    "year": 2008,
                    "ids": {
                        "simkl": 12345,
                        "slug": "breaking-bad",
                        "tmdb": 1429
                    }
                }
            }

+ Request (application/json)
    Pause watching an anime TV episode using TMDB ID (maps to AniDB episode numbering)
    + Headers
    
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
    + Body
    
          {
            "progress": 42.2,
            "anime": {
              "ids": {
                 "tmdb": 1429
              }
            },
            "episode": {
              "season": 2,
              "number": 4
            }
          }

+ Response 201 (application/json)

     + Body
        {
            "id": 1123123124120,
            "action": "pause",
            "progress": 42.2,
            "episode": {
                "season": 1,
                "number": 4,
                "title": "Soldier",
                "tvdb_season": 2,
                "tvdb_number": 4
            },
            "anime": {
                "title": "Shingeki no Kyojin Season 2",
                "year": 2017,
                "anime_type": "tv",
                "ids": {
                    "simkl": 439744,
                    "slug": "shingeki-no-kyojin-season-2",
                    "mal": "25777",
                    "anilist": "20958",
                    "kitsu": "8671",
                    "anidb": "10944"
                }
            }
        }
   

+ Response 409 (application/json)
    if you are trying to stop an already completed scrobble session within an hour.
    + Body
    
            {
                "watched_at": "2024-01-15T10:30:00.000Z",
                "expires_at": "2024-01-15T11:30:00.000Z"
            }


## Check-in [/scrobble/checkin]
### Check in to an item [POST]
<h4>&#128274; Token Required</h4>

**What is Check-in?**

Check-in is a simple way for users to tell their friends "I'm watching this right now" without requiring a media player or real-time progress tracking. Unlike scrobbling (which requires integration with a media player and only marks as watched after receiving /pause or /stop requests with ≥80% progress), check-in is a manual one time request the user sends to indicate that they're watching something right now and want the Simkl server to auto mark it as watched after the check-in expires (based on runtime).

Think of it like pressing "I'm watching this" on your remote—one tap and you're done. Simkl takes care of the rest: it shows what you're watching on your profile, and when the movie or episode ends (based on runtime), it automatically marks it as watched. No app running in the background, no progress updates needed.

**Perfect for:**
- 🎬 **At the movies** – Check in when the film starts, put your phone away, and it's marked watched when you leave
- 📺 **Watching live TV** – Cable, satellite, or a friend's streaming account with no Simkl integration
- 🛋️ **Couch mode** – Just want to track without installing plugins or using scrobble-compatible apps

**Typical Use Cases:**
- User is watching on a device/service without Simkl integration (cable TV, theater, friend's account)
- User wants to show on his Simkl profile "Watching Now" bar
- User prefers manual tracking over automatic scrobbling
- Social viewing parties or watch-alongs

**How Check-in Works on the Simkl Website:**

Users can manually check in via the **"Check in / Watching Now"** button found on:
- **Movie pages** ([example](https://simkl.com/movies/81500/the-avengers)) - Button appears `Checkin\Watching Now ` 
- **Episode pages** ([example](https://simkl.com/tv/548312/stranger-things/season-1/episode-1/)) - Button `Watching Now` on each episode

When clicked, a popover appears allowing users to:
1. Optionally set their current progress (via slider or minute input)
2. Click "Started Watching Now" to check in

After check-in:
- The content appears in the user's Dashboard [https://simkl.com/my/dashboard/](https://simkl.com/my/dashboard/) **"Watching Now" bar** (visible to friends based on privacy settings)
- The check-in automatically expires after the item's runtime
- When expired, Simkl **automatically marks the item as watched**

**Behavior:**
- Creates a check-in event visible in the user's "Watching Now" bar on the dashboard
- Session auto-expires based on item runtime (calculated as: `now + remaining runtime * (1 - progress/100)`)
- The `progress` parameter is **optional** (defaults to 0% if not provided). Use it to indicate how far into the content you are when checking in
- Can be canceled or converted via another `/scrobble/stop`, `/scrobble/pause`, or `/scrobble/start`
- Calling again with the same item **extends/resets** the check-in duration
- When expired, Simkl automatically marks the item as watched (in about 10-120 seconds after 100% progress) and posts to connected social accounts if the user has enabled this option in the sharing settings for example to X.

**Action Types in Responses:**
- `"checkin"` - Returned when check-in is created or updated

**Comparison: Check-in vs Start vs Pause vs Stop**

| Feature | `/scrobble/checkin` | `/scrobble/start` | `/scrobble/pause` | `/scrobble/stop` |
|---------|---------------------|-------------------|-------------------|------------------|
| **Purpose** | Manual "watching now" | Real-time playback tracking | Save progress mid-watch | End playback session |
| **Progress tracking** | ✅ Optional (affects expiry) | ✅ Required | ✅ Required | ✅ Required |
| **Requires media player** | ❌ No | ✅ Yes | ✅ Yes | ✅ Yes |
| **Auto-marks watched** | ✅ On expiry | ❌ No | ❌ No | ✅ If ≥80% |
| **Shows in Watching bar** | ✅ Yes | ✅ Yes | ❌ No | ❌ No |
| **Shows in Progress Manager** | ❌ No | ❌ No | ✅ Yes | ✅ If < 80% |


**Managing Check-ins:**

>Users can view their active checkin on Simkl website Dashboard [https://simkl.com/my/dashboard/](https://simkl.com/my/dashboard/) and manage their paused/stopped check-ins and playback sessions at:
> [https://simkl.com/my/history/playback-progress-manager/](https://simkl.com/my/history/playback-progress-manager/)

+ Request (application/json)
    Check in to a movie using Simkl ID (fastest lookup), IMDB, and TMDB IDs
    
    + Headers
    
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
    + Body

          {
            "movie": {
              "title": "Inception",
              "year": 2010,
              "ids": {
                "simkl": 472214,
                "imdb": "tt1375666",
                "tmdb": 27205
              }
            }
          }

+ Response 201 (application/json)

    + Body
    
          {
            "id": 9876543210123,
            "action": "checkin",
            "progress": 0,
            "movie": {
              "title": "Inception",
              "year": 2010,
              "anime_type": null,
              "ids": {
                "simkl": 472214,
                "slug": "inception",
                "imdb": "tt1375666",
                "letterslug": "inception",
                "tmdb": "27205",
                "tvdbslug": "inception"
              }
            }
          }
            

+ Request (application/json)
    Check in to a TV show episode using IMDB ID (with 25% progress - already 25% into the episode)
    + Headers
    
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
    + Body
    
          {
            "progress": 25.5,
            "show": {
              "title": "Stranger Things",
              "year": 2016,
              "ids": {
                "imdb": "tt4574334"
              }
            },
            "episode": {
              "season": 1,
              "number": 3
            }
          }

    
+ Response 201 (application/json)

     + Body
    
          {
            "id": 9876543210124,
            "action": "checkin",
            "progress": 25.5,
            "show": {
              "title": "Stranger Things",
              "year": 2016,
              "ids": {
                "simkl": 548312,
                "slug": "stranger-things",
                "tmdb": "66732",
                "tvdb": "305288",
                "imdb": "tt4574334"
              }
            },
            "episode": { 
              "season": 1, 
              "number": 3,
              "title": "Chapter Three: Holly, Jolly"
            }
          }

+ Request (application/json)
    Check in to an anime using show type with TVDB ID or TMDB ID (useful for media players that use TVDB\TMDB for anime)
    + Headers

            Authorization: Bearer [token]
            simkl-api-key: [client_id]
    + Body

          {
            "show": {
              "ids": {
                 "tvdb": 267440,
                 "tmdb": 1429
              }
            },
            "episode": {
              "season": 1,
              "number": 5
            }
          }

+ Response 201 (application/json)

     + Body
        {
            "id": 9876543210127,
            "action": "checkin",
            "progress": 0,
            "episode": {
                "season": 1,
                "number": 5,
                "title": "The Lord of a Coastland",
                "tvdb_season": 1,
                "tvdb_number": 5
            },
            "anime": {
                "title": "Shingeki no Kyojin",
                "year": 2013,
                "anime_type": "tv",
                "ids": {
                    "simkl": 39687,
                    "slug": "shingeki-no-kyojin",
                    "tvdb": "267440",
                    "tmdb": "1429",
                    "imdb": "tt2560140",
                    "mal": "16498",
                    "anilist": "16498",
                    "kitsu": "7442",
                    "anidb": "9541"
                }
            }
        }


+ Request (application/json)
    Check in to an anime episode using TMDB ID with 50% progress (maps to AniDB episode numbering)
    + Headers
    
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
    + Body
    
          {
            "progress": 42.2,
            "anime": {
              "ids": {
                 "tmdb": 1429
              }
            },
            "episode": {
              "season": 2,
              "number": 4
            }
          }

+ Response 201 (application/json)

     + Body
        {
            "id": 9876543210125,
            "action": "checkin",
            "progress": 42.2,
            "episode": {
                "season": 1,
                "number": 4,
                "title": "Soldier",
                "tvdb_season": 2,
                "tvdb_number": 4
            },
            "anime": {
                "title": "Shingeki no Kyojin Season 2",
                "year": 2017,
                "anime_type": "tv",
                "ids": {
                    "simkl": 439744,
                    "slug": "shingeki-no-kyojin-season-2",
                    "mal": "25777",
                    "anilist": "20958",
                    "kitsu": "8671",
                    "anidb": "10944"
                }
            }
        }

+ Request (application/json)
    Check in to an anime movie using MAL ID
    + Headers

            Authorization: Bearer [token]
            simkl-api-key: [client_id]
    + Body

          {
            "anime": {
              "ids": {
                 "mal": 37987
              }
            }
          }

+ Response 201 (application/json)

     + Body
        {
            "id": 9876543210126,
            "action": "checkin",
            "progress": 0,
            "anime": {
                "title": "Violet Evergarden the Movie",
                "year": 2020,
                "anime_type": "movie",
                "ids": {
                    "simkl": 799363,
                    "slug": "gekijouban-violet-evergarden",
                    "tmdb": "533514",
                    "imdb": "tt8652818",
                    "mal": "37987",
                    "anilist": "103047",
                    "kitsu": "41450",
                    "anidb": "14013"
                }
            }
        }


## Delete [/sync/playback/{id}]
### Delete a playback session [DELETE]
<h4>&#128274; Token Required</h4>

Deletes an active scrobble session, check-in, or paused playback. Use this to cancel a check-in before it auto-completes, remove a paused session, or cancel an active scrobble.

**When to use:**
- User wants to cancel an active check-in before it auto-completes
- User started scrobbling the wrong content
- User wants to remove a paused session from their playback history

**Alternative: Convert Check-in to Scrobble**

You can also use other scrobble endpoints to convert or end a check-in:

| Action | Endpoint | Effect on Check-in |
|--------|----------|-------------------|
| **Mark watched now** | `/scrobble/stop` with ≥80% | Immediately marks as watched, cancels auto-complete |
| **Save progress** | `/scrobble/pause` | Converts to paused session, cancels auto-complete |
| **Switch to scrobbling** | `/scrobble/start` | Replaces check-in with real-time scrobble session |

This is useful when a user checks in but then wants to switch to real-time tracking, or wants to mark something as watched immediately without waiting for the check-in to expire.

+ Parameters
    + id: `9876543210123` (number, required) - The playback ID returned in the scrobble/check-in response

+ Request
    + Headers

            Authorization: Bearer [token]
            simkl-api-key: [client_id]

+ Response 200 (application/json)

    + Body

            {
                "deleted": true
            }

+ Response 404 (application/json)

    + Body

            {
                "error": "not_found"
            }



# Group Sync

Simkl can be one central place where you store all your watch history as well as all member Watchlists like Watching, Plan to Watch, on Hold, Dropped, Completed. Syncing allows all your devices and apps have your watch history up to date. Use Simkl as your a cloud backup for all your Media history.


<h3>Get All Items</h3>
This is a list of all your movies, shows and episodes that you watched or have in your Watchlists like Watching, Plan to Watch, etc list.

To start a sync first check the last activities of the user and then do an update only if the date in one of them have changed scince your last check.

### Supported ID keys (inside `ids`)

| ID key       | Description                |
|-------------|-----------------------------|
| **simkl**   | Simkl internal ID (e.g. `49108`, `1265720`, `437940`) |
| **anidb**   | AniDB ID. All other parameters can be empty if this one specified. Example: `10846`. Integer. |
| **anilist** | AniList ID. Example: `21`. Integer. |
| **animeplanet** | Anime-Planet ID. Example: `one-piece`. String. |
| **anisearch** | aniSearch ID. Example: `2227`. Integer. |
| **imdb**    | IMDb ID or full URL. Example: `tt1520211`. String. |
| **kitsu**   | Kitsu ID. Example: `12`. Integer. |
| **letterboxd** | Letterboxd slug. Example: `the-truman-show`. String. |
| **livechart** | LiveChart ID. Example: `321`. Integer. |
| **mal**     | MyAnimeList ID. Example: `4246`. Integer. |
| **netflix** | Netflix movieid. Example: `70210890`. Integer. |
| **tmdb**    | The Movie Database (TMDb) ID. For TV shows specify `type`. Example: `76757`. Integer. |
| **tvdb**    | TVDB ID. Example: `153021`, `the-walking-dead`. Integer or string. |
| **traktslug** | Trakt slug. Example: `john-wick-chapter-4-2023`. String. |

## How to Use Sync [/sync/how-to-use-sync]

**How to properly use `date_from` together with the <a href="#reference/sync/last-activities">Last Activities</a> and <a href="#reference/sync/get-all-items">Get All Items</a>
 endpoints**

To efficiently synchronize a user's watch history with your application using the Simkl API, you should leverage the `date_from` parameter in conjunction with the <a href="#reference/sync/last-activities">`/sync/activities`</a> endpoint. This allows you to fetch only the data that has changed since your last sync, reducing data transfer and processing time. Below is a step-by-step guide on how to implement this:

### **1. Initial Sync (First Request)**

**a. Call the <a href="#reference/sync/last-activities">Last Activities</a> Endpoint**

Begin by making a request to the <a href="#reference/sync/last-activities">`/sync/activities`</a> endpoint to retrieve the latest activity timestamps for the user. This endpoint provides timestamps for various categories and media types, indicating the last time each was updated.

**Request:**

```http
POST https://api.simkl.com/sync/activities
Headers:
    Authorization: Bearer [token]
    simkl-api-key: [client_id]
```

**Response Example:**

```json
{
    "all": "2023-10-12T09:03:45Z",
    "settings": {
        "all": "2023-10-10T09:17:15Z"
    },
    "tv_shows": {
        "all": "2023-10-12T09:03:45Z",
        "rated_at": "2023-10-11T08:00:00Z",
        "playback": "2024-10-11T08:00:00Z",
        "plantowatch": "2023-10-12T09:03:45Z",
        "watching": "2023-10-10T07:00:00Z",
        "completed": "2023-10-09T06:00:00Z",
        "hold": null,
        "dropped": "2023-10-08T05:00:00Z",
        "removed_from_list": "2023-10-07T04:00:00Z"
    },
    "anime": {
        "all": "2023-10-12T09:03:45Z",
        "rated_at": "2023-10-10T08:00:00Z",
        "playback": "2024-10-11T08:00:00Z",
        "plantowatch": "2023-10-11T09:03:45Z",
        "watching": "2023-10-09T07:00:00Z",
        "completed": "2023-10-08T06:00:00Z",
        "hold": null,
        "dropped": "2023-10-07T05:00:00Z",
        "removed_from_list": "2023-10-06T04:00:00Z"
    },
    "movies": {
        "all": "2023-10-12T09:03:45Z",
        "rated_at": "2023-10-11T08:00:00Z",
        "playback": "2024-10-11T08:00:00Z",
        "plantowatch": "2023-10-10T09:03:45Z",
        "completed": "2023-10-09T07:00:00Z",
        "dropped": "2023-10-08T06:00:00Z",
        "removed_from_list": "2023-10-07T05:00:00Z"
    }
}
```

**b. Save the Timestamps**

Store all the datetime values from the response in your application's local or cloud storage. These timestamps will be used to determine changes in the user's data during subsequent syncs.

**c. Fetch All Data Without `date_from`**

Since this is the first sync and you have no prior data, you need to retrieve the entire watchlist.

**Request:**

```http
GET https://api.simkl.com/sync/all-items/
Headers:
    Authorization: Bearer [token]
    simkl-api-key: [client_id]
```

**Response:**

The API will return all items (movies, shows, anime) that the user has in their watchlist. Process and store this data in your application as the baseline for future syncs.

---

### **2. Subsequent Syncs (Further Requests)**

**a. Periodically Check for Updates**

After some time, check the <a href="#reference/sync/last-activities">`/sync/activities`</a> endpoint for any changes. You can compare the dates from this endpoint with your locally saved copy. You may compare any specific date you need (e.g., `movies.completed`, `tv_shows.watching`) or just the main `all` date (`"all": "2023-10-12T09:03:45Z"`).

To keep your app's data current, periodically check the <a href="#reference/sync/last-activities">`/sync/activities`</a> endpoint for changes. Here are optimal times to perform this check:

- **When the User Opens the App:** Sync immediately to ensure the latest data is displayed.
- **When the App Becomes Active:** If the app was in the background, check for updates when it becomes active again.
- **At Regular Intervals:** For apps that stay open, consider syncing every few hours to keep data fresh.

By syncing during these key moments, your app stays up-to-date without unnecessary API calls.


**Request:**

```http
POST https://api.simkl.com/sync/activities
Headers:
    Authorization: Bearer [token]
    simkl-api-key: [client_id]
```

**b. Compare Timestamps**

Compare the new timestamps received with the ones you previously saved.

- **If a Timestamp Has Changed:** This indicates that data in that category has been updated since your last sync.
- **If a Timestamp Has Not Changed:** No action is needed for that category.

**Note:** Depending on your application's requirements, you can choose to monitor specific timestamps that are relevant to your data synchronization needs, or you can rely on the main `"all"` timestamp for a broader check.

**c. Use `date_from` Parameter for Updates**

For each category where the timestamp has changed, use the `date_from` parameter in your requests to fetch only the updated data.

**Request Example for Updated Shows:**

```http
GET https://api.simkl.com/sync/all-items/shows/?date_from=2023-10-10T07:00:00Z
Headers:
    Authorization: Bearer [token]
    simkl-api-key: [client_id]
```

- **`date_from` Value:** Use the saved timestamp from your last sync for that specific category.

**d. Process Updated Data**

Update your local data store with the items received:

- **Add New Items:** Include any new shows, movies, or episodes added.
- **Update Existing Items:** Reflect changes in status, ratings, or watched episodes.
- **Remove Deleted Items:** If the `removed_from_list` timestamp has changed, identify and remove items that are no longer in the user's watchlist.

**Handling Removals:**

If items were removed, you might need to call `/sync/all-items/` without `date_from` only with `extended=simkl_ids_only` or `extended=ids_only` to get the full current list (mini watchlist with IDs only) and compare it with your local data to determine which items have been removed.

**e. Update Saved Timestamps**

After processing the updates, overwrite your saved timestamps with the new ones from the latest <a href="#reference/sync/last-activities">`/sync/activities`</a> response. This ensures your next sync will use the correct `date_from` values.

---

### **3. Detailed Steps with Examples**

#### **First Sync:**

1. **Call <a href="#reference/sync/last-activities">`/sync/activities`</a> and Save Timestamps**

   ```http
   POST https://api.simkl.com/sync/activities
   ```

   Save the entire response.

2. **Fetch All Items Without `date_from`**

   ```http
   GET https://api.simkl.com/sync/all-items/
   ```

   Process and store the data locally.



#### **Subsequent Syncs:**

###### 1. **Call <a href="#reference/sync/last-activities">`/sync/activities`</a>**

   ```http
   POST https://api.simkl.com/sync/activities
   ```
###### 2. **Compare Timestamps**

   Compare each timestamp with the saved ones.

   - **Example:** If `movies.rated_at` has changed from `2023-10-11T08:00:00Z` to `2023-10-12T09:00:00Z` (compared to your saved copy), you need to fetch updated movie ratings.

###### 3. **Fetch Updates with `date_from`**

   For updated categories, make requests like:

   ```http
   GET https://api.simkl.com/sync/all-items/movies/?date_from=2023-10-11T08:00:00Z
   ```

###### 4. **Process Updates**

   - **Add or Update Items:** Incorporate new data into your local store.
   - **Remove Items:** If `removed_from_list` has changed, fetch the full list and remove items not present.

###### 5. **Update Saved Timestamps**

   Replace old timestamps with the new ones from the latest <a href="#reference/sync/last-activities">`/sync/activities`</a> response.

---

### **4. Handling Specific Scenarios**

**Ratings Updates:**

- If `rated_at` has changed, use `/sync/ratings` with `date_from` to get the latest ratings.

  **Request:**

  ```http
  GET https://api.simkl.com/sync/ratings/?date_from=2023-10-11T08:00:00Z
  Headers:
      Authorization: Bearer [token]
      simkl-api-key: [client_id]
  ```

**Note on Automatic Moves:**

- When a user rates an item not in their list, it may automatically move to `Completed` or `Watching`. The corresponding list timestamp (e.g. `completed_at`, `watching`) will be updated, and the item will appear in `date_from` queries.

**Use of Extended Parameters:**

- When needing detailed information (e.g., watched episodes), use `extended=full` and `episode_watched_at=yes`:

  ```http
  GET https://api.simkl.com/sync/all-items/shows/?extended=full&episode_watched_at=yes&date_from=2023-10-10T07:00:00Z
  Headers:
      Authorization: Bearer [token]
      simkl-api-key: [client_id]
  ```

- **Caution:** These parameters increase response size. Always use them with `date_from` to minimize data transfer.

---

### **5. Tips and Best Practices**

- **Time Zones:** All timestamps are in UTC. Convert them appropriately if your application operates in a different time zone.
- **Error Handling:** Implement robust error handling for network issues or unexpected responses.
- **Data Integrity:** Ensure that your local data store accurately reflects the user's data on Simkl after each sync.
- **Rate Limiting:** Be mindful of API rate limits. Avoid excessive calls by scheduling syncs appropriately.

---

### **6. Summary**

By following these steps, you ensure that:

- Your application stays up-to-date with the user's Simkl watch history.
- Data transfer is minimized by only fetching changes since the last sync.
- The user experiences seamless synchronization without unnecessary delays or data usage.


### Example Workflow Recap [GET]

1. **First Sync:**
   - Save all timestamps from <a href="#reference/sync/last-activities">`/sync/activities`</a>.
   - Fetch all items without `date_from`.
   - Store data locally.

2. **Further Syncs:**
   - Call <a href="#reference/sync/last-activities">`/sync/activities`</a> to get new timestamps.
   - Compare with saved timestamps.
   - For each changed category:
     - Use the relevant saved timestamp as `date_from` in `/sync/all-items/` request.
     - Process and update local data.
   - Update saved timestamps for the next sync.
   
  
By properly using `date_from` with the activity endpoint and comparing the specific dates you need or just the main `"all"` date, you optimize your application's performance and provide a better experience for your users.


+ Response 200

## Last Activities [/sync/activities]
### Get last activity [GET]
<h4>&#128274; Token Required</h4>

When syncing it's best to check user's last activity first. Then you'll be able to sync only the watchlists that have changed since the last sync. 

This method will decrease sync time or minimize wait time to zero if nothing changed so you do not need to download user's full history every time.

<b>NOTE:</b> when user rates the movie, tv show or anime and it is not in his list, it will be automatically moved to `Completed`, `Watching` depending on it's type(movie or serie)

<h4>Fields definition and HOWTO</h4>
Name|Description
---|----
`all`| latest update time within the category, use it as first check
`settings`| any update in https://simkl.com/settings/ will trigger update time. For example when user changes his name or time zone.
`rated_at` | If updated, use the <i>Get Ratings</i> endpoint with the <i>date_from</i> parameter to retrieve the latest rating updates or deletions.<br><br><b>CAUTION!</b> When a user rates a movie, it will be automatically moved to "Completed". If a user rates a TV show and it's not in the user’s watchlist, it will be automatically moved to the "Watching" watchlist. These auto-moves will also update the corresponding list timestamps (e.g. <code>completed</code>, <code>watching</code>), so the item will appear in <code>date_from</code> queries on the <i>Get All Items</i> endpoint.
`playback`| if updated check the <i>Playback</i> endpoint with <i>date_from</i> parameter to get latest added playbacks or without the parameter to make a full sync.
`plantowatch`<br>`watching`<br>`completed`<br>`hold`<br>`dropped`| Items were added to one of the lists, status was changed, or episodes were marked/unmarked. Rating a new item (which auto-adds it to a list) or a rating that triggers a status change (e.g. movie moved to Completed) will also update these fields.<br><br>If updated check the <i>Get All Items</i> endpoint with <i>date_from</i> and <i>extended</i> parameters
`removed_from_list`| Check the <i>Get All Items</i> endpoint without <i>date_from</i> and <i>extended</i> parameters to determine which items were removed. <br>If removed items from the lists had ratings, they would be removed

Steps for **how to use it** with `date_from` field: 

1. Save all datetime values from this endpoint to your local/cloud storage of the APP
2. Fetch all data from <a href="#reference/sync/get-all-items">*/sync/get-all-items*</a> endpoint without `date_from` field
3. After some time, check this endpoint for any changes(compare the dates from this endpoint with you local saved copy, any specific date you need or just the main `"all": "2016-10-29T09:03:45Z"` date). 
4. On dates change 
    - use the date saved from your 1 step (ex. `"all": "2016-10-29T09:03:45Z"`) as `date_from` field value in <a href="#reference/sync/get-all-items">*/sync/get-all-items*</a> endpoint
    - save the new datetime values from this endpoint to your local/cloud storage
    - go to step 3

`date_from` field shows all items with the date greater(newer) than date_from field. 
    

If you have any ideas how to make sync even better for you, please [let us know](mailto:support@simkl.com).


+ Request (application/json)
`https://api.simkl.com/sync/activities` 
    + Header
        Authorization: Bearer [token]
        simkl-api-key: [client_id]

+ Response 200 (application/json)

      + Body
        {
            "all": "2016-10-29T09:03:45Z",
            "settings":{
                "all":"2015-09-26T09:17:15Z"
            },
            "tv_shows": {
                "all": "2016-10-29T09:03:45Z",
                "rated_at": "2016-10-29T09:03:45Z",
                "playback": "2017-10-29T09:03:45Z",
                "plantowatch": "2016-10-29T09:03:45Z",
                "watching": "2016-10-29T09:03:45Z",
                "completed": "2016-10-29T09:03:45Z",
                "hold": "2016-10-29T09:03:45Z",
                "dropped": "2016-10-29T09:03:45Z",
                "removed_from_list": "2016-10-29T09:03:45Z"
            },
            "anime": {
                "all": "2016-10-29T09:03:45Z",
                "rated_at": "2016-10-29T09:03:45Z",
                "playback": "2018-10-29T09:03:45Z",
                "plantowatch": "2016-10-29T09:03:45Z",
                "watching": "2016-10-29T09:03:45Z",
                "completed": "2016-10-29T09:03:45Z",
                "hold": null,
                "dropped": "2016-10-29T09:03:45Z",
                "removed_from_list": "2016-10-29T09:03:45Z"
            },
            "movies": {
                "all": "2016-10-29T09:03:45Z",
                "rated_at": "2016-10-29T09:03:45Z",
                "playback": "2018-10-29T09:03:45Z",
                "plantowatch": "2016-10-29T09:03:45Z",
                "completed": "2016-10-29T09:03:45Z",
                "dropped": "2016-10-29T09:03:45Z",
                "removed_from_list": "2016-10-29T09:03:45Z"
            }
        }


## Playback [/sync/playback/{type}]

A **playback** is a temporary session that stores viewing progress for a movie, TV show episode, or anime episode when playback is paused or stopped before completion. Playbacks are created automatically when users pause their viewing or stop watching before completing an item (less than 80% progress).

**Note:** Playbacks are **NOT** the same as Simkl's sync/watchlist endpoints. Playbacks are temporary pause/resume events and are **NOT saved to the user's watchlist**. They exist solely to track in-progress viewing sessions.

**⚠️ IMPORTANT:** Always use the [Activity API endpoint](#reference/sync/activities) first to check when you need to refresh sync or playback data. This endpoint provides timestamps for various categories including `playback` which indicates when playback sessions were last updated. By checking this endpoint first, you can optimize your application's performance and only sync playback data when changes have occurred.

### Relationship to Scrobbling

**Scrobbling** and **playbacks** work together to provide a complete viewing progress tracking system:

- **Scrobbling** (`/scrobble/start`, `/scrobble/pause`, `/scrobble/stop`, `/scrobble/checkin`) is the *action* of reporting real-time playback progress to the API
- **Playbacks** are *temporary records* created by scrobble pause/stop actions, storing pause points that can be resumed later
- **Sync/** endpoints (like `/sync/all-items`) are for *permanent* watchlist records that track what users have watched

**How they connect:**

1. When a user calls `/scrobble/pause`, it creates a **temporary playback record** with the current progress (not added to watchlist)
2. When a user calls `/scrobble/stop` with **less than 80%** progress, it creates a **temporary playback record** (not added to watchlist)
3. When a user calls `/scrobble/stop` with **80% or more** progress, the item is **marked as watched in the user's history/watchlist** (no resumable playback is created)
4. The `/sync/playback/{type}` endpoint retrieves these temporary playback records so apps can display "Continue Watching" lists
5. Users can resume a saved playback by calling `/scrobble/start` with the same item

**Key differences from sync watch history endpoints:**

- **Playbacks** (`/sync/playback`) = Temporary pause/resume events for in-progress viewing (NOT on watchlist)
- **Sync** (`/sync/all-items`) = Permanent watchlist records for completed items (≥80% progress)
- Only **one playback session per item** is stored (the most recent pause point)
- Playback sessions persist in the database until manually deleted or until `/scrobble/start` is called for the same item
- When retrieved via GET, sessions are automatically filtered out if the user has already watched the item after the playback was created (but remain in the database)

**Retention periods by subscription plan:**

Playback progress records are automatically retained based on the user's subscription level:

- **Free users**: 7 days retention
- **PRO users**: 30 days retention  
- **VIP users**: 90 days retention

These retention periods determine how long paused playback sessions remain available for the user to resume.

**Users can view and manage their saved playbacks at [https://simkl.com/my/history/playback-progress-manager/](https://simkl.com/my/history/playback-progress-manager/).**


### Error Responses
The API uses standard HTTP status codes to indicate the success or failure of a request.

| Status Code | Meaning | Description |
|---|---|---|
| `201 Created` | Success | The scrobble event was successfully created. |
| `204 No Content`| Success | The playback session was successfully deleted. |
| `400 Bad Request`| Client Error | The request was malformed. This can happen if you send a scrobble request without a `movie`, `show`, or `anime` object, or if there's a concurrency issue (see Rate Limiting). |
| `401 Unauthorized`| Client Error | The provided access token is invalid or has expired. |
| `404 Not Found` | Client Error | The requested item (movie, show, episode) could not be found on Simkl, or the URL is incorrect. |
| `409 Conflict` | Client Error | Returned by `/scrobble/stop` if you try to scrobble an item that was already marked as watched within the last hour. The response body will contain `watched_at` and `expires_at` timestamps. |

### Session Expiry & Storage
- **`start` sessions** have an `end_on` timestamp set to current time + remaining runtime, but are not automatically deleted when expired
- **`stop` sessions** have an `end_on` timestamp set to current time + 1 hour, but are not automatically deleted when expired  
- **`pause` sessions** have an `end_on` timestamp set to current time, but are not automatically deleted when expired
- All playback session types persist in the playback until manually removed via the `DELETE` endpoint, or by the user, or until they are replaced by the next scrobble update for that title

The `runtime in minutes` is determined as follows:
- **Movies**: Uses the movie's runtime from Simkl's database. Defaults to `90` minutes if not available.
- **TV Shows**: Uses the episode's specific runtime. Defaults to `45` minutes if not available.
- **Anime**: Uses the episode's specific runtime. Defaults to `25` minutes if not available.

### Concurrency & Rate Limiting
To ensure data integrity, the API processes scrobble events sequentially for each user. If you send multiple requests at once, they will be queued. A request may time out and fail with a `400 Bad Request` error if it has to wait too long for the previous one to complete. We recommend queuing scrobble events in your application and sending them one by one.


### Get Playback Sessions [GET]
<h4>&#128274; Token Required</h4>
Retrieves all paused playback sessions for the user. You can optionally filter by type by appending `/movie` or `/episode` to the path. Only one session per show/movie/anime is stored (the latest paused one).

`limit` is set to 10000 items by default, it's a maximum number of items you can retrive. 

`hide_watched` is true by default. All watched items with newer `watched date` than `paused date` will be hidden.

**When to use:** To get a list of items the user paused and can resume. Use this to display "Continue Watching" lists in your app.

**Behavior:** 
- Returns paused sessions created by `/scrobble/pause` or `/scrobble/stop` (<80% progress)
- Sessions for items the user has already watched (where their last watch time is after the session pause time) are automatically filtered out
- Sessions are ordered by pause time (newest first)
- Use the returned data to resume via `/scrobble/start`

**User Management:** Users can view and manage their paused sessions at [https://simkl.com/my/history/playback-progress-manager/](https://simkl.com/my/history/playback-progress-manager/) to manually delete unwanted sessions, mark items as watched, or use bulk selection tools for cleanup.

Note: Playback `id` field is a 64bit integer. `progress` is returned as a percentage (float number from 0 to 100, e.g., `0`, `45.5`, `75`, `100`). While you can POST in scrobble `75.00`, the response will always be `75`.

**Anime Episode Mapping:** Anime episodes return both AniDB episode numbers (`season`, `number`) and TVDB numbers (`tvdb_season`, `tvdb_number`) since Simkl maps between these different numbering systems.

+ Parameters
    + type (optional, string, `movies`) ... Filter by item type.
        + Values
            + `movies`
            + `episodes`
    + limit (optional, number) ... Slice your result to the first N items. Default: 10000
    + hide_watched (optional, boolean) ...Hide already watched episodes\movies. Default: true
        + Values
            + `true`
            + `false`
    + date_from (string, optional) ... Filter sessions from this date
    + date_to (string, optional) ... Filter sessions until this date

+ Request
    + Headers
             
            Authorization: Bearer [token]
            simkl-api-key: [client_id]

+ Response 200 (application/json)
    + Body
            
            [
                {
                    "id": 123,
                    "progress": 45.5,
                    "paused_at": "2024-01-15T10:30:00.000Z",
                    "type": "episode",
                    "episode": {
                        "season": 1,
                        "episode": 5,
                        "title": "Episode 5",
                        "tvdb_season": 1,
                        "tvdb_number": 5
                    },
                    "show": {
                        "title": "Breaking Bad",
                        "year": 2008,
                        "ids": {
                            "simkl": 12345,
                            "slug": "breaking-bad",
                            "tmdb": 1429,
                            "imdb": "tt0903747"
                        }
                    }
                },
                {
                    "id": 124,
                    "progress": 75,
                    "paused_at": "2024-01-15T11:15:00.000Z",
                    "type": "movie",
                    "movie": {
                        "title": "Inception",
                        "year": 2010,
                        "ids": {
                            "simkl": 67890,
                            "slug": "inception",
                            "tmdb": 27205,
                            "imdb": "tt1375666"
                        }
                    }
                }
            ]

### Delete Playback [DELETE /sync/playback/{id}]
Deletes a specific paused playback session by its ID.

**When to use:** When a user no longer wants to resume a paused session (e.g., they finished watching elsewhere or changed their mind).

**Behavior:** Permanently removes the paused session. Returns 204 on success, 404 if the session doesn't exist or belongs to another user.

**Alternative:** Users can also manage their paused sessions manually at [https://simkl.com/my/history/playback-progress-manager/](https://simkl.com/my/history/playback-progress-manager/) without using the API, including bulk deletion and marking items as watched.

+ Parameters
    + id (number, required, in path) - The playback session ID to delete

+ Request

    + Headers
        
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
+ Response 204 (No Content)




## Get All Items [/sync/all-items/{type}/{status}{?date_from}]
#### ⚠️ IMPORTANT ⚠️
For continuous sync, DO NOT use without fetching the **Activity** endpoint first.  
Always use `date_from` to sync only small changes. This avoids overloading the API server and helps keep it stable for all users. 

If you don't follow these rules, your client_id will be suspended.
[How to use Sync](#reference/sync/how-to-use-sync).
### Get all items in the user's watchlist [GET]
<h4>&#128274; Token Required &#10024; Full Info optional</h4>
Returns all items that user has in his watchlist (watching, plan to watch, dropped, completed), shows, anime, movies. 

Anime block has `anime_type` field, possible values are `tv`,`special`,`ova`,`movie`,`music video`,`ona`.

**Note:** If a user doesn't have anything in his watchlists, the response will be `null`

<h4>You can add to the URL:</h4>
Variable|Description
---|----
`extended=full`| adds a list of episodes user have watched
`extended=full_anime_seasons`| same as `full` + TVDB season and episode numbers for every Anime episode.  All Anime series including Completed watchlist has American style seasons map added `mapped_tvdb_seasons: [1,2]`.
`extended=simkl_ids_only`| minified response, returns only simkl IDs and slugs.
`extended=ids_only`| minified response, returns only all IDs and slugs without any additionl info.
`episode_watched_at=yes`| adds a time when user watched the episode as `watched_at` time for all episodes
`next_watch_info=yes`| adds more info about next to watch episodes
`memos=yes`| adds member's memo

**IMPORTANT:** Please keep in mind that adding more data to the request (using extended and episode_watched_at) makes the reply exponentially larger, + a few megabytes in most cases, so please use it only when needed and always with the use of `date_from` so that the server reply was very small and fast.

More details on how to use `date_from` field see <a href="#reference/sync/how-to-use-sync">here</a>

+ Request (application/json)
<h6>⚠️ IMPORTANT ⚠️</h6>
<h7>Do not use without fetching the **Activity** endpoint first.</h7>
<h7>Always use `date_from` to sync only small changes. This avoids overloading the API server and helps keep it stable for all users. If you don't follow these rules, your client_id will be suspended.</h7>
<h7>[How to use Sync](#reference/sync/how-to-use-sync).</h7>
<h6>Get list of all the shows, anime and movies in a format of <a href="https://simkl.com/51/tv/">https://simkl.com/51/tv/</a></h6>
`https://api.simkl.com/sync/all-items/` 
    + Header
        Authorization: Bearer [token]
        simkl-api-key: [client_id]

+ Parameters
    + type (optional, string, `anime`) ... 
        + Values
            + `shows`
            + `movies`
            + `anime`
    + status (optional, string, `completed`) ... 
        + Values
            + `watching`
            + `plantowatch`
            + `hold`
            + `completed`
            + `dropped`
    + date_from (optional, string, `2016-09-12T13:00:30Z`) ... returns the items updated from the passed value
        + Values
            + `2016-09-12T13:00:30Z`
    + extended (optional, string, `full`) ... `full` returns more info including a list of watched episodes
        + Values
            + `full`
            + `full_anime_seasons`
            + `simkl_ids_only`
            + `ids_only`
    + episode_watched_at (optional, string, `yes`) ... `yes` returns the date when user watched the episode
        + Values
            + `yes`
    + memos (optional, string, `yes`) ... `yes` returns memos in addition all other data
        + Values
            + `yes`
            
+ Response 200 (application/json)

      + Body
        {
            "shows": [
            {
            "added_to_watchlist_at":"2010-01-20T20:09:04Z",
            "last_watched_at": null,
            "user_rated_at": "2021-06-23T13:19:05Z",
            "status": "hold",
            "user_rating": null,
            "last_watched": null,
            "next_to_watch": "S01E01",
            "watched_episodes_count": 0,
            "total_episodes_count": 10,
            "not_aired_episodes_count": 0,
            "show": {
                "title": "Emerald City",
                "poster": "51\/5152376528f644b91",
                "year": 2017,
                "runtime": 40,
                "ids": {
                    "simkl": 583436,
                    "slug": "emerald-city",
                    "imdb": "tt3579018",
                    "zap2it": "EP02431429",
                    "tmdb": "62417",
                    "offen": "http:\/\/www.nbc.com\/emerald-city",
                    "tvdb": "295779"
                }
            }
        }
          ],
          "anime": [
            {
              "added_to_watchlist_at":"2010-01-20T20:09:04Z",
              "last_watched_at": "2014-11-06T22:05:52Z",
              "user_rated_at": "2021-06-23T13:19:05Z",
              "user_rating": 10,
              "status": "completed",
              "last_watched": "E148",
              "next_to_watch": null,
              "watched_episodes_count": 150,
              "total_episodes_count": 150,
              "not_aired_episodes_count": 0,
              "anime_type": "tv", 
              "show": {
                "title": "Hunter x Hunter",
                "poster": "83\/83975f751784587",
                "year": 2011,
                "runtime": null,
                "ids": {
                  "simkl": 40398,
                  "imdb": "tt2098220",
                  "mal": "11061",
                  "anidb": "8550"
                }
              }
            },
            {
              "added_to_watchlist_at":"2010-01-20T20:09:04Z",
              "last_watched_at": "2016-10-19T08:34:23Z",
              "user_rated_at": "2021-06-23T13:19:05Z",
              "user_rating": null,
              "status": "plantowatch",
              "last_watched": null,
              "next_to_watch": "E01",
              "anime_type": "tv", 
              "show": {
                "title": "Ajin 2",
                "year": 2016,
                "runtime": 100,
                "ids": {
                  "simkl": 581835,
                  "mal": "33253",
                  "anidb": "12111"
                }
              }
            }
          ],
          "movies": [
            {
              "added_to_watchlist_at":"2010-01-20T20:09:04Z",
              "last_watched_at": "2014-08-09T07:25:55Z",
              "user_rated_at": "2021-06-23T13:19:05Z",
              "user_rating": null,
              "status": "completed",
              "movie": {
                "title": "Captain America: The First Avenger",
                "poster": "84\/842596c6291031c0",
                "year": 2011,
                "runtime": 120,
                "ids": {
                  "simkl": 55328,
                  "imdb": "tt0458339",
                  "tmdb": "1771"
                }
              }
            },
            {
              "added_to_watchlist_at":"2010-01-20T20:09:04Z",
              "last_watched_at": "2014-08-16T18:45:20Z",
              "user_rated_at": "2021-06-23T13:19:05Z",
              "user_rating": null,
              "status": "completed",
              "movie": {
                "title": "Maleficent",
                "poster": "17\/1722048af2197c9a7",
                "year": 2014,
                "runtime": 100,
                "ids": {
                  "simkl": 195258,
                  "imdb": "tt1587310",
                  "tmdb": "102651"
                }
              }
            }
          ]
        }

+ Request (application/json)
<h6>Get Anime list and watched episodes:</h6> 
`https://api.simkl.com/sync/all-items/anime/?extended=full`

    + Header
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
            
+ Response 200 (application/json)

    + Body
            
            {
                "anime": [
                    {
                        "added_to_watchlist_at":"2010-01-20T20:09:04Z",
                        "last_watched_at": "2015-01-06T13:43:26Z",
                        "user_rated_at": "2021-06-23T13:19:05Z",
                        "user_rating": 9,
                        "status": "watching",
                        "last_watched": "S01E01",
                        "next_to_watch": "S01E02",
                        "show": {
                            "title": "Fate/Stay Night: Unlimited Blade Works",
                            "year": 2014,
                            "runtime": 100,
                            "ids": {
                                "simkl": 46116,
                                "imdb": "tt3621796",
                                "mal": "22297",
                                "anidb": "9977"
                            }
                        },
                        "seasons": [
                            {
                                "number": 1,
                                "episodes": [
                                    { "number": 1 },
                                    { "number": 2 },
                                    { "number": 3 },
                                    { "number": 4 },
                                    { "number": 5 },
                                    { "number": 6 },
                                    { "number": 7 },
                                    { "number": 8 },
                                    { "number": 9 },
                                    { "number": 10 },
                                    { "number": 11 },
                                    { "number": 12 }
                                ]
                            }
                        ]
                    }
                ]
            }

+ Request (application/json)
<h6>Get Anime list and watched episodes:</h6> 
`https://api.simkl.com/sync/all-items/anime/?extended=full_anime_seasons`

    + Header
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
            
+ Response 200 (application/json)            

    + Body
    
            {
                "anime": [
                    {
                        "added_to_watchlist_at":"2010-01-20T20:09:04Z",
                        "last_watched_at": "2015-01-06T13:43:26Z",
                        "user_rated_at": "2021-06-23T13:19:05Z",
                        "user_rating": 9,
                        "status": "watching",
                        "last_watched": "S01E01",
                        "next_to_watch": "S01E02",
                        "show": {
                            "title": "Fate/Stay Night: Unlimited Blade Works",
                            "year": 2014,
                            "runtime": 100,
                            "ids": {
                                "simkl": 46116,
                                "imdb": "tt3621796",
                                "mal": "22297",
                                "anidb": "9977",
                                "tvdb": "278626"
                            }
                        },
                        "tvdb_seasons": [2,3],
                        "seasons": [
                            {
                                "number": 1,
                                "episodes": [
                                    {
                                        "number": 1,
                                        "tvdb": {
                                            "season": 1,
                                            "episode": 1
                                        }
                                    },
                                    {
                                        "number": 2,
                                        "tvdb": {
                                            "season": 1,
                                            "episode": 2
                                        }
                                    },
                                    {
                                        "number": 3,
                                        "tvdb": {
                                            "season": 1,
                                            "episode": 3
                                        }
                                    },
                                    {
                                        "number": 4,
                                        "tvdb": {
                                            "season": 1,
                                            "episode": 4
                                        }
                                    },
                                    {
                                        "number": 5,
                                        "tvdb": {
                                            "season": 1,
                                            "episode": 5
                                        }
                                    },
                                    {
                                        "number": 6,
                                        "tvdb": {
                                            "season": 1,
                                            "episode": 6
                                        }
                                    },
                                    {
                                        "number": 7,
                                        "tvdb": {
                                            "season": 1,
                                            "episode": 7
                                        }
                                    },
                                    {
                                        "number": 8,
                                        "tvdb": {
                                            "season": 1,
                                            "episode": 8
                                        }
                                    },
                                    {
                                        "number": 9,
                                        "tvdb": {
                                            "season": 1,
                                            "episode": 9
                                        }
                                    },
                                    {
                                        "number": 10,
                                        "tvdb": {
                                            "season": 1,
                                            "episode": 10
                                        }
                                    },
                                    {
                                        "number": 11,
                                        "tvdb": {
                                            "season": 1,
                                            "episode": 11
                                        }
                                    },
                                    {
                                        "number": 12,
                                        "tvdb": {
                                            "season": 1,
                                            "episode": 12
                                        }
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }

+ Request (application/json)
<h6>Get Anime list with memos:</h6> 
`https://api.simkl.com/sync/all-items/anime/?memos=yes`

    + Header
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
            
+ Response 200 (application/json)

    + Body
            
            {
                "anime": [
                    {
                        "added_to_watchlist_at":"2010-01-20T20:09:04Z",
                        "last_watched_at": "2015-01-06T13:43:26Z",
                        "user_rated_at": "2021-06-23T13:19:05Z",
                        "user_rating": 9,
                        "status": "watching",
                        "last_watched": "S01E01",
                        "next_to_watch": "S01E02", 
                        "memo":{
                            "text": "super memo.",
                            "is_private": true
                        },
                        "show": {
                            "title": "Fate/Stay Night: Unlimited Blade Works",
                            "year": 2014,
                            "runtime": 100,
                            "ids": {
                                "simkl": 46116,
                                "imdb": "tt3621796",
                                "mal": "22297",
                                "anidb": "9977"
                            }
                        }
                    }
                ]
            }




## Add Items to the history [/sync/history]
### Add items to watched/watching history [POST]
<h4>&#128274; Token Required</h4>

This endpoint lets you add items to a user's watched history. 

You can include movies, shows, episodes, or even specific seasons. The more details you provide (like title, year, and IDs), the easier it is for Simkl to match the item correctly.

- **By default, if you don’t specify watchlist status or episodes when adding a show:**
  1. **If the show hasn’t been released yet:** It will be added to your *Watching* list.
  2. **If the show is still airing:** All aired episodes will be marked as watched.
  3. **If the show has ended:** The show will be moved to your *Completed* list.
- **Using `watched_at`:** If you include a UTC datetime in `watched_at`, the item is recorded as watched at that time.
- **Marking as completed:** You can add `status: "completed"` to mark a show as completed. However, if the show is still airing, it will be added to your "watching" watchlist instead and all aired episodes will be marked as watched. The updated watchlist status will be returned in the response.
- **Moving to watching:** You can add `status: "watching"` to keep the show in the Watching watchlist without updating any episodes.
- **List of all supported statuses**: `watching`, `plantowatch`, `completed`, `dropped`, `hold`.


#### Handling Anime Seasons with TVDB/TMDB IDs
By default, anime seasons on Simkl are treated as separate series. To mark all seasons for an anime (when using only TVDB or TMDB IDs) starting from first season, include the flag:
```json
"use_tvdb_anime_seasons": true
```
in the item object.


Each media object should include as much data as possible—especially `title`, `year`, and `ids`—to help Simkl accurately detect the item. You can also include a `watched_at` field to specify the UTC datetime when the item was watched.


if `watched_at` UTC datetime is passed then all will be marked as watched in the past. 

Possible values in response for the `anime_type` key see [Standard Media Object](/#introduction/about-simkl-api/standard-media-objects) and for the `simkl_type` are `movie,tv,anime`


<h4>JSON POST DATA</h4>
Key|Type|Value
---|----|-----
`movies`|array| Array of `movie` objects ([see examples](#introduction/about-simkl-api/standard-media-objects)) 
`shows`|array| Array of `show` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))
`episodes`|array| Array of `episode` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))

<h4>MEDIA OBJECTS POST DATA</h4>
Key|Type|Value
---|----|-----
`item*`|object|movie, show or episode objects 
`watched_at`|datetime|UTC datetime when the item was watched

#### Episode-Level External IDs
Episodes within seasons can include an optional `ids` object with `tvdb` and/or `anidb` IDs alongside the required `number` field. When provided, these IDs take priority over season/episode number for matching, which is useful when numbering differs between sources (e.g. specials, absolute ordering).

```json
"episodes": [
    {
        "number": 4,
        "watched_at": "2024-09-01T09:10:11Z",
        "ids": {
            "tvdb": 5057304
        }
    }
]
```

#### Moving between Watchlists 
Use  ['Add Item to the List'](#reference/sync/add-item-to-the-list/add-items-to-specific-list)  if you only need to move items between Watchlists.

+ Request (application/json) 
    Mark all Titan's seasons as watched. Will put the show into Completed watchlist if the show has ended. If the show is still airing will mark all aired episodes as watched and keep it in Watching watchlist.
    
    + Header
            
            Authorization: Bearer [token]
            simkl-api-key: [client_id]

    
    + Body
    
            {
                "shows": [
                    {
                        "added_at": "2010-01-20T20:09:04Z",
                        "title": "Attack on Titan",
                        "year": 2013,
                        "status": "completed",
                        "use_tvdb_anime_seasons": true,
                        "ids": {
                            "simkl": 39687,
                            "mal": 16498,
                            "tvdb": 267440,
                            "imdb": "tt2560140",
                            "anidb": 9541
                        }
                    }
                ]
            }   


+ Response 200 (application/json)
    + Body
    
    {
        "added": {
            "movies": 0,
            "shows": 7,
            "episodes": 0,
            "statuses": [
                {
                    "request": {
                        "added_at": "2010-01-20T20:09:04Z",
                        "title": "Attack on Titan",
                        "year": 2013,
                        "status": "completed",
                        "use_tvdb_anime_seasons": true,
                        "ids": {
                            "simkl": 39687,
                            "mal": 16498,
                            "tvdb": 267440,
                            "imdb": "tt2560140",
                            "anidb": 9541
                        }
                    },
                    "response": {
                        "status": "watching",
                        "simkl_type": "anime",
                        "anime_type": "tv"
                    }
                } 
            ]
        },
        "not_found": {
            "movies": [],
            "shows": [],
            "episodes": []
        }
    }

+ Request (application/json)
 Example request with multiple media types, seasons and episodes
    + Header
            
            Authorization: Bearer [token]
            simkl-api-key: [client_id]

    + Body
    
            {
                "movies": [
                    {
                        "added_at": "2009-01-20T20:09:04Z",
                        "watched_at": "2011-01-20T20:09:04Z",
                        "title": "Terminator 3: Rise of the Machines",
                        "year": "2003",
                        "rating": 9,
                        "memo": {
                            "text": "max 140 chars memo",
                            "is_private": true
                        },
                        "ids": {
                            "imdb": "tt0181852",
                            "tmdb": 296,
                            "simkl": 53536
                        }
                    },
                    {
                        "ids": {
                            "simkl": 210728
                        }
                    }
                ],
                "shows": [
                    {
                        "title": "Attack on Titan",
                        "year": 2013,
                        "rating": 0,
                        "ids": {
                            "simkl": 39687,
                            "mal": 16498,
                            "tvdb": 267440,
                            "imdb": "tt2560140",
                            "anidb": 9541
                        }
                    },
                    {
                        "title": "The Walking Dead",
                        "year": 2010,
                        "ids": {
                            "simkl": 2090,
                            "tvdb": 153021,
                            "imdb": "tt1520211"
                        },
                        "seasons": [
                            {
                                "watched_at": "2011-09-01T14:44:00Z",
                                "number": 1
                            },
                            {
                                "number": 2,
                                "episodes": [
                                    {
                                        "number": 1,
                                        "ids": {
                                            "tvdb": 4185813
                                        }
                                    },
                                    {
                                        "number": 2,
                                        "ids": {
                                            "tvdb": 4185814
                                        }
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "episodes": [
                    {
                        "watched_at": "2014-09-01T09:10:11Z",
                        "ids": {
                            "simkl": 343633,
                            "hulu": 681868,
                            "tvdb": 2493011,
                            "crunchyroll": 656647
                        }
                    }
                ]
            }   


+ Request (application/json) 
    Anime request example
    
    + Body
    
            {
                "shows": [
                    {
                        "title": "Attack on Titan",
                        "year": 2013,
                        "ids": {
                            "simkl": 39687,
                            "mal": 16498,
                            "tvdb": 267440,
                            "imdb": "tt2560140",
                            "anidb": 9541
                        },
                        "episodes": [
                            {
                                "number": 1,
                                "ids": {
                                    "anidb": 151234
                                }
                            },
                            {
                                "number": 2,
                                "ids": {
                                    "anidb": 151235
                                }
                            }
                        ]
                    }
                ]
            }   


+ Response 200 (application/json)
    + Body
    

+ Request (application/json) 
   Add the memo to the TV Shows
    
    + Header
            
            Authorization: Bearer [token]
            simkl-api-key: [client_id]

    + Body
    
            {
                "shows": [
                    {
                        "title": "The Walking Dead",
                        "year": 2010,
                        "memo": {
                            "text": "max 140 chars memo",
                            "is_private": false
                        },
                        "ids": {
                            "simkl": 2090,
                            "tvdb": 153021,
                            "imdb": "tt1520211"
                        }
                    }
                ]
            }   


+ Response 200 (application/json)
    + Body
    
    {
        "added": {
            "movies": 0,
            "shows": 0,
            "episodes": 0,
            "statuses": [
                {
                    "request": {
                        "title": "The Walking Dead",
                        "year": 2010,
                        "memo": {
                            "text": "max 140 chars memo",
                            "is_private": false
                        },
                        "ids": {
                            "simkl": 2090,
                            "tvdb": 153021,
                            "imdb": "tt1520211"
                        }
                    },
                    "response": {
                        "status": "completed",
                        "simkl_type": "tv",
                        "anime_type": null
                    }
                } 
            ]
        },
        "not_found": {
            "movies": [],
            "shows": [],
            "episodes": []
        }
    }

## Remove Items from History and from Lists [/sync/history/remove]
### Remove items from watched/watching history [POST]
<h4>&#128274; Token Required</h4>
Remove the items from the user's watched history. You can pass shows, seasons, episodes and movies. If no episodes are passed and the season is specified then all episodes within this season will be unmarked. If seasons were skipped too then the show will be removed completely.

When removing show or movie, ratings are removed automatically as well for that item.
<h4>JSON POST DATA</h4>
Key|Type|Value
---|----|-----
`movies`|array| Array of `movie` objects ([see examples](#introduction/about-simkl-api/standard-media-objects)) 
`shows`|array| Array of `show` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))

<h4>MEDIA OBJECTS POST DATA</h4>
Key|Type|Value
---|----|-----
`item*`|object|movie, show objects 

+ Request (application/json)
    + Header
            
            Authorization: Bearer [token]
            simkl-api-key: [client_id]

    + Body
    
            {
                "movies": [
                    {
                        "title": "Terminator 3: Rise of the Machines",
                        "year": "2003",
                        "ids": {
                            "imdb": "tt0181852",
                            "tmdb": 296,
                            "simkl": 53536
                        }
                    },
                    {
                        "ids": {
                            "simkl": 210728
                        }
                    }
                ],
                "shows": [
                    {
                        "title": "Attack on Titan",
                        "year": 2013,
                        "ids": {
                            "simkl": 39687,
                            "mal": 16498,
                            "tvdb": 267440,
                            "imdb": "tt2560140",
                            "anidb": 9541
                        }
                    },
                    {
                        "title": "The Walking Dead",
                        "year": 2010,
                        "ids": {
                            "simkl": 2090,
                            "tvdb": 153021,
                            "imdb": "tt1520211"
                        },
                        "seasons": [
                            {
                                "number": 2
                            },
                            {
                                "number": 1,
                                "episodes": [
                                    {
                                        "number": 1
                                    },
                                    {
                                        "number": 2
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }   

+ Response 200 (application/json)
    + Body
    

## Get Ratings [/sync/ratings/{type}/{rating}{?date_from}]
### Get all user's ratings [POST]
<h4>&#128274; Token Required &#10024; Full Info</h4>
Returns all rated items in user's lists filtered by `type`. You can also filter items by rating score. Send a comma separated string if you need a multiple rating items or want to skip items with deleted ratings.

+ Request (application/json)
    + Header
        Authorization: Bearer [token]
        simkl-api-key: [client_id]

+ Parameters
    + type (optional, string, `anime`) ... 
        + Values
            + `shows`
            + `movies`
            + `anime`
    + rating (optional, integer, `8,9,10`) ... 
        + Values
            + `1`
            + `2`
            + `3`
            + `4`
            + `5`
            + `6`
            + `7`
            + `8`
            + `9`
            + `10`
    + date_from (optional, string, `2016-09-12T13:00:30Z`) ... returns the items updated from the passed value
        + Values
            + `2016-09-12T13:00:30Z`
            
+ Response 200 (application/json)

      + Body
        {
          "shows": [
            {
            
              "last_watched_at": "2016-09-12T13:00:30Z",
              "user_rated_at": "2021-06-23T13:19:05Z",
              "user_rating": 5,
              "status": "dropped",
              "last_watched": null,
              "next_to_watch": "S01E01",
              "show": {
                "title": "The Last Ship",
                "year": 2014,
                "ids": {
                  "simkl": 42040,
                  "imdb": "tt2402207",
                  "tvdb": "269533"
                }
              }
            }
          ],
          "anime": [
            {
              "last_watched_at": "2014-11-06T22:05:52Z",
              "user_rated_at": "2021-06-23T13:19:05Z",
              "user_rating": 10,
              "status": "completed",
              "last_watched": "E148",
              "next_to_watch": null,
              "show": {
                "title": "Hunter x Hunter",
                "year": 2011,
                "ids": {
                  "simkl": 40398,
                  "imdb": "tt2098220",
                  "mal": "11061",
                  "anidb": "8550"
                }
              }
            }
          ],
          "movies": [
            {
              "last_watched_at": "2014-08-16T18:45:20Z",
              "user_rated_at": "2021-06-23T13:19:05Z",
              "user_rating": 6,
              "status": "completed",
              "movie": {
                "title": "Maleficent",
                "year": 2014,
                "ids": {
                  "simkl": 195258,
                  "imdb": "tt1587310",
                  "tmdb": "102651"
                }
              }
            }
          ]
        }


## Add Ratings [/sync/ratings]
### Add new ratings [POST]
<h4>&#128274; Token Required</h4>
Rate the movies or tv shows/anime. You cannot rate the seasons or episodes right now.

If the show/anime or movie is rated before it was in user's list, show will be automatically added to "Watching" list and the movie will be added to "I've seen this" list.

Keep in mind, when removing the show/anime or movie user's ratings will be removed as well for that item.

<h4>JSON POST DATA</h4>
Key|Type|Value
---|----|-----
`movies`|array| Array of `movie` objects ([see examples](#introduction/about-simkl-api/standard-media-objects)) 
`shows`|array| Array of `show` objects ([see examples](#introduction/about-simkl-api/standard-media-objects)). Anime are `shows` too



+ Parameters
    + rating (required, integer, `10`) ... 
        + Values
            + `1`
            + `2`
            + `3`
            + `4`
            + `5`
            + `6`
            + `7`
            + `8`
            + `9`
            + `10`
    + rated_at (optional, string, `2014-09-01T09:10:11Z`) ... UTC datetime

+ Request (application/json)
    + Header
            
            Authorization: Bearer [token]
            simkl-api-key: [client_id]

    + Body
    
            {
                "movies": [
                    {
                        "title": "Terminator 3: Rise of the Machines",
                        "rating": 8,
                        "rated_at": "2014-09-01T09:10:11Z",
                        "year": "2003",
                        "ids": {
                            "imdb": "tt0181852",
                            "tmdb": 296,
                            "simkl": 53536
                        }
                    },
                    {
                        "rating": 6,
                        "ids": {
                            "simkl": 210728
                        }
                    }
                ],
                "shows": [
                    {
                        "title": "Attack on Titan",
                        "year": 2013,
                        "rating": 10,
                        "ids": {
                            "simkl": 39687,
                            "mal": 16498,
                            "tvdb": 267440,
                            "imdb": "tt2560140",
                            "anidb": 9541
                        }
                    }
                ]
            }   
            
            
+ Response 200 (application/json)

      + Body
            {
                "added": {
                    "movies": 2,
                    "shows": 1,
                    "statuses": [
                        {
                            "request": {
                                "title": "Terminator 3: Rise of the Machines",
                                "year": "2003",
                                "rated_at": "2014-09-01T09:10:11.000Z",
                                "rating": 8,
                                "ids": {
                                    "imdb": "tt0181852",
                                    "tmdb": 296,
                                    "simkl": 53536
                                }
                            },
                            "response": {
                                "status": "completed"
                            }
                        },
                        {
                            "request": {
                                "rating": 6,
                                "ids": {
                                    "simkl": 210728
                                }
                            },
                            "response": {
                                "status": "completed"
                            }
                        },
                        {
                            "request": {
                                "title": "Attack on Titan",
                                "year": 2013,
                                "rating": 10,
                                "ids": {
                                    "simkl": 39687,
                                    "mal": 16498,
                                    "tvdb": 267440,
                                    "imdb": "tt2560140",
                                    "anidb": 9541
                                }
                            },
                            "response": {
                                "status": "watching"
                            }
                        }
                    ]
                },
                "not_found": {
                    "movies": [],
                    "shows": []
                }
            }


## Remove Ratings [/sync/ratings/remove]
### Remove ratings [POST]
<h4>&#128274; Token Required</h4>
Any movies or tv shows passed here will be unrated 

<h4>JSON POST DATA</h4>
Key|Type|Value
---|----|-----
`movies`|array| Array of `movie` objects ([see examples](#introduction/about-simkl-api/standard-media-objects)) 
`shows`|array| Array of `show` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))

<h4>MEDIA OBJECTS POST DATA</h4>
Key|Type|Value
---|----|-----
`item*`|object|movie, show objects 

+ Request (application/json)
    + Header
            
            Authorization: Bearer [token]
            simkl-api-key: [client_id]

    + Body
    
            {
                "movies": [
                    {
                        "title": "Terminator 3: Rise of the Machines",
                        "year": "2003",
                        "ids": {
                            "imdb": "tt0181852",
                            "tmdb": 296,
                            "simkl": 53536
                        }
                    },
                    {
                        "ids": {
                            "simkl": 210728
                        }
                    }
                ],
                "shows": [
                    {
                        "title": "Attack on Titan",
                        "year": 2013,
                        "ids": {
                            "simkl": 39687,
                            "mal": 16498,
                            "tvdb": 267440,
                            "imdb": "tt2560140",
                            "anidb": 9541
                        }
                    }
                ]
            }   

+ Response 200 (application/json)
    + Body



## Add Item to the List [/sync/add-to-list]
### Add items to specific list [POST]
<h4>&#128274; Token Required</h4>
Add items to a user's Simkl watchlists. For example you can add a Show directly to Plan to Watch or move existing show from Watching to Dropped. You can pass shows and movies. 

Pass as much data as possible into the item including `title`, `year` and `ids` fields so Simkl could detect the item better.

<h4>JSON POST DATA</h4>
Key|Type|Value
---|----|-----
`movies`|array| Array of `movie` objects ([see examples](#introduction/about-simkl-api/standard-media-objects)) 
`shows`|array| Array of `show` objects ([see examples](#introduction/about-simkl-api/standard-media-objects))

<h4>MEDIA OBJECTS POST DATA</h4>
Key|Type|Value
---|----|-----
item*|object|[tv show or movie object](#introduction/about-simkl-api/standard-media-objects).
`to`|string|possible values "plantowatch","completed","watching","hold","dropped"
`to`|array| custom lists **IN DEV**
`watched_at`|datetime|UTC datetime when the item was watched, available only for "completed" status


+ Request (application/json)
    + Header
            
            Authorization: Bearer [token]
            simkl-api-key: [client_id]

    + Body
    
            {
                "movies": [
                    {
                        "title": "Terminator 3: Rise of the Machines",
                        "to": "completed",
                        "year": "2003",
                        "added_at": "2014-09-01T09:10:11Z",
                        "watched_at": "2014-10-10T22:10:00Z",
                        "ids": {
                            "imdb": "tt0181852",
                            "tmdb": 296,
                            "simkl": 53536
                        }
                    },
                    {
                        "to": "plantowatch",
                        "ids": {
                            "simkl": 210728
                        }
                    }
                ],
                "shows": [
                    {
                        "to" : "watching",
                        "title": "Attack on Titan",
                        "year": 2013,
                        "ids": {
                            "simkl": 39687,
                            "mal": 16498,
                            "tvdb": 267440,
                            "imdb": "tt2560140",
                            "anidb": 9541
                        }
                    },
                    {
                        "title": "The Walking Dead",
                        "year": 2010,
                        "to": "completed",
                        "ids": {
                            "simkl": 2090,
                            "tvdb": 153021,
                            "imdb": "tt1520211"
                        }
                    }
                ]
            }   

+ Response 200 (application/json)

    + Body

            {
                "added": {
                    "movies": [
                        {
                            "title": "Terminator 3: Rise of the Machines",
                            "to": "completed",
                            "year": "2003",
                            "added_at": "2014-09-01T09:10:11Z",
                            "watched_at": "2014-10-10T22:10:00Z",
                            "ids": {
                                "imdb": "tt0181852",
                                "tmdb": 296,
                                "simkl": 53536
                            }
                        },
                        {
                            "to": "plantowatch",
                            "ids": {
                                "simkl": 210728
                            }
                        }
                    ],
                    "shows": [
                        {
                            "to" : "watching",
                            "title": "Attack on Titan",
                            "year": 2013,
                            "ids": {
                                "simkl": 39687,
                                "mal": 16498,
                                "tvdb": 267440,
                                "imdb": "tt2560140",
                                "anidb": 9541
                            }
                        },
                        {
                            "title": "The Walking Dead",
                            "year": 2010,
                            "to": "watching",
                            "ids": {
                                "simkl": 2090,
                                "tvdb": 153021,
                                "imdb": "tt1520211"
                            }
                        }
                    ]
                },
                "not_found": {
                    "movies": [
                        {
                            "ids": {
                              "imdb": "tt0000222"
                            }
                        }
                    ],
                    "shows": []
                }
            }


## Check if watched [/sync/watched{?extended}]
This endpoint retrieves one or a list of shows, seasons or episodes in a show a user has watched. 

### Get specific user's watched items [POST]
<h4>&#128274; Token Required</h4>

This endpoint retrieves the list of shows or episodes a user has watched. You can pass different IDs to get their corresponding statuses in the user's watchlist.

The JSON body may contain various IDs (e.g., Simkl, TMDB, IMDB, Netflix, etc.) to check watch status.

#####**Query Parameters**:
- **`extended`** *(optional)* – Controls the level of detail in the response. Possible values:
  - `counters` – Includes watched counts only.
  - `episodes` – Retrieves all episodes with counters.
  - `specials` – Includes special episodes as season `0`, and adjusts counters accordingly.

  These values can be combined using a comma (`,`) separator.  
  **Example:** `?extended=counters,specials`

#####**Limitations**
- When using the `extended` parameter, the request can include a **maximum of 100 items**.  
- Exceeding this limit will result in an error.
---

### 📌 JSON Response Data

| Key     | Value                                  | Description |
|---------|----------------------------------------|-------------|
| `result` | `true`                                | The item was found in the user's watchlist. |
| `result` | `false`                               | The item was found but is not in the user's watchlist. |
| `result` | `not_found`                           | No match found in the Simkl database using the provided Title, Year, or ID. |
| `list`   | `completed`, `watching`, `dropped`, `hold`, `plantowatch` | The user's watchlist category for the item. |
| `last_watched_at` | `YYYY-MM-DDTHH:MM:SSZ` | Last watched date and time of the episode or movie. (UTC format)|
| `episodes_total`               | `8`                                            | The total number of episodes in the show or season. |
| `episodes_aired`               | `7`                                            | The number of episodes that have aired so far. |
| `episodes_to_be_aired`         | `1`                                            | The number of episodes yet to be aired. |
| `episodes_watched`             | `6`                                            | The number of episodes the user has watched. |
| `seasons`                      | `[...]` (array)                                | A list of seasons for the show. |
| `seasons[].episodes`            | `[...]` (array)                                | A list of episodes in the season. |
+ Parameters
    + extended (optional, string, `counters`) ... You can use multiple values joined by comma. 
        + Values
            + `counters`
            + `episodes`
            + `specials`
            
    + client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).

+ Attributes (object)
    + Click here to see an **array** of items to check. Each item can include:
        + type (enum[string], optional) - Improves search for TMDb.
            + Members
                + `show`
                + `movie`
        + title: `The Walking Dead` (string, optional) - TV show, anime, or movie title
        + year: 2010 (number, optional) - Release year
        + season: 1 (number, optional) - If set, movies will be ignored (anime typically do not have seasons)
        + episode: 4 (number, optional) - If set, movies will be ignored
        + simkl: 2090 (optional, number, `1`) - Simkl ID
        + hulu: 752375 (number, optional) - Hulu ID (all other parameters can be empty if this is specified)
        + netflix: 70210890 (number, optional) - Netflix movie/show ID (in beta)
        + mal: 4246 (number, optional) - MyAnimeList ID
        + tvdb: 153021 (number, optional) - TVDB ID (all other parameters can be empty if this is specified)
        + tmdb: 76757 (number, optional) - TMDb ID (specify `type` for TV shows; other params can be empty if this is specified)
        + imdb (enum[string], optional) - IMDB ID or full URL (other parameters can be empty if this is specified).
            + Members
                + `tt1520211`
                + `http://www.imdb.com/title/tt1520211/`

        + anidb: 10846 (number, optional) - AniDB ID (all other parameters can be empty if this is specified)
        + crunchyroll: 656641 (number, optional) - Crunchyroll ID (episode ID or URL ID)
        + anilist: 21 (number, optional) - AniList ID
        + kitsu: 12 (number, optional) - Kitsu ID
        + livechart: 321 (number, optional) - LiveChart ID
        + anisearch: 2227 (number, optional) - aniSearch ID
        + animeplanet: `one-piece` (string, optional) - Anime-Planet ID
        + traktslug: `john-wick-chapter-4-2023` (string, optional) - Trakt slug
        + letterboxd: `the-truman-show` (string, optional) - Letterboxd slug


+ Request (application/json)
<h6>Get a list of shows or movies is user has watched them or not</h6>
`https://api.simkl.com/sync/watched/?client_id=***` 


    + Header
            
            Authorization: Bearer [token]
            simkl-api-key: [client_id]

    + Body
    
        [
          {
            "netflix": 70262639,
            "type": "movie"
          },
          {
            "netflix": 70080650
          },
          {
            "hulu": 764084
          }
        ]
            
+ Response 200 (application/json)

    + Body
    
            [{
                "netflix": 70262639,
                "list": "watching",
                "result": true,
                "last_watched_at": "2017-02-04T16:10:51Z"
            },
            {
                "netflix": 70080650,
                "result": false
            },
            {
                "hulu":764084,
                "result": "not_found"
            }]
            
            

+ Request (application/json)
<h6>Get a list of shows with episodes a user has watched including the spesicals season. <br><br>
<i>If you don't need specials, remove it from the extended</i> </h6>
`https://api.simkl.com/sync/watched/?extended=episodes,specials,counters&client_id=***` 

    
    + Header
            
            Authorization: Bearer [token]
            simkl-api-key: [client_id]

    + Body
            [{
                "simkl": 2091057
            },{
                "imdb": "tt12917170"
            }]
            

+ Response 200 (application/json)

    + Body
            [
                {
                    "simkl": 2091057,
                    "result": true,
                    "list": "watching",
                    "last_watched_at": "2025-01-29T15:01:08Z",
                    "episodes_total": 8,
                    "episodes_aired": 7,
                    "episodes_to_be_aired": 1,
                    "episodes_watched": 6,
                    "seasons": [
                        {
                            "number": 1,
                            "episodes_total": 8,
                            "episodes_aired": 7,
                            "episodes_to_be_aired": 1,
                            "episodes_watched": 6,
                            "episodes": [
                                {
                                    "number": 1,
                                    "watched": true,
                                    "aired": true,
                                    "last_watched_at": "2025-01-29T15:01:03Z"
                                },
                                {
                                    "number": 2,
                                    "watched": true,
                                    "aired": true,
                                    "last_watched_at": "2025-01-29T15:01:04Z"
                                },
                                {
                                    "number": 3,
                                    "watched": true,
                                    "aired": true,
                                    "last_watched_at": "2025-01-29T15:01:05Z"
                                },
                                {
                                    "number": 4,
                                    "watched": true,
                                    "aired": true,
                                    "last_watched_at": "2025-01-29T15:01:06Z"
                                },
                                {
                                    "number": 5,
                                    "watched": true,
                                    "aired": true,
                                    "last_watched_at": "2025-01-29T15:01:07Z"
                                },
                                {
                                    "number": 6,
                                    "watched": true,
                                    "aired": true,
                                    "last_watched_at": "2025-01-29T15:01:08Z"
                                },
                                {
                                    "number": 7,
                                    "watched": false,
                                    "aired": true,
                                    "last_watched_at": null
                                },
                                {
                                    "number": 8,
                                    "watched": false,
                                    "aired": false,
                                    "last_watched_at": null
                                }
                            ]
                        }
                    ]
                },
                {
                    "imdb": "tt12917170",
                    "result": "not_found"
                }
            ]
            

# Group Users
User's public data will return all info with GET methods without OAuth\PIN authorization.

## Last Watched Arts [/users/recently-watched-background/{user_id}{?image,client_id}]
Get images for user's last watched TV Show or Movie. Useful for example to create an app that will update user's wallpaper on computer or phone

### Get last watched images and data [GET]

Will reply with user's id, Show\Movie URL, Show\Movie title, large poster, and large fanart image.

*Please cache the image on the device, do not redownload if the same image url.*

+ Parameters
    + user_id = (required, integer, `51`) ... Simkl user id which has public privacy settings.
    + client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).
            
+ Request https://api.simkl.com/users/recently-watched-background/51?client_id=***
            
+ Response 200 (application/json)

    + Body
            {
                "id":342828,
                "url":"https://simkl.com/movies/342828/midnight-special",
                "title":"Midnight Special",
                "poster":"https://simkl.in/posters/30/3082850367420132f_0.jpg",
                "fanart":"https://simkl.in/fanart/43/4389778c118f40a6f_0.jpg"
            }


### Redirect to last watched image [GET]

Will simply redirect to the image for your app to download or display.

*Please cache the image on the device, do not redownload if the same image url.*

+ Parameters
    + user_id = (required, integer, `51`) ... Simkl user id which has public privacy settings.
    + image = (required, string, `fanart`) ... can be "poster" or "fanart".
        + Values
            + `poster`
            + `fanart`
    + client_id (string) ... Get this from [your app settings](https://simkl.com/settings/developer/).
            
+ Request https://api.simkl.com/users/recently-watched-background/51?image=fanart&client_id=***
            
+ Response 302 

    + Headers
    
            location: https://simkl.in/fanart/50/500671636445e211e_0.jpg

    + Body

## Settings [/users/settings]
### Receive settings [POST]
<h4>&#128274; Token Required</h4>
You can sync user's settings with your apps/site settings

+ Request (application/json)
    + Header
            
            Authorization: Bearer [token]
            simkl-api-key: [client_id]
            
+ Response 200 (application/json)

    + Body
    
            {
                "user": 
                {
                    "name": "Andrew Masyk",
                    "joined_at": "2007-11-04T22:04:46Z",
                    "gender": "male",
                    "avatar": "https:\/\/graph.facebook.com\/736253775\/picture?width=100&height=100",
                    "bio": "I'm a founder and developer at simkl.com - a socially powered TV show and movie tracking service",
                    "loc": "New York, NY, USA",
                    "age": "30 years"
                },
                "account": 
                {
                    "id" : 51,
                    "timezone": "America\/New_York",
                    "type": "free"
                },
                "connections": 
                {
                    "facebook": true
                }
            }

## Stats [/users/{user_id}/stats]
### Get watched statistics [POST]
<h4>&#128274; Token Optional</h4>

Get all info about user's watched movies, tv shows, anime and episodes.
Some users profiles are private so you need to pass token to see their stats

+ Request (application/json)
    + Header
            
            Authorization: Bearer [token]
            simkl-api-key: [client_id]

+ Response 201 (application/json)
        
    + Body

        {
            "total_mins": 908554,
            "movies": {
                "total_mins": 171969,
                "plantowatch": {
                    "mins": 18938,
                    "count": 173
                },
                "notinteresting": {
                    "mins": 12969,
                    "count": 123
                },
                "completed": {
                    "mins": 171852,
                    "count": 1558
                }
            },
            "tv": {
                "total_mins": 242560,
                "watching": {
                    "watched_episodes_count": 2612,
                    "count": 41,
                    "left_to_watch_episodes": 10276,
                    "left_to_watch_mins": 411040,
                    "total_episodes_count": 12888
                },
                "hold": {
                    "watched_episodes_count": 1157,
                    "count": 41,
                    "left_to_watch_episodes": 828,
                    "left_to_watch_mins": 33120,
                    "total_episodes_count": 1985
                },
                "plantowatch": {
                    "watched_episodes_count": 243,
                    "count": 118,
                    "left_to_watch_episodes": 12961,
                    "left_to_watch_mins": 518440,
                    "total_episodes_count": 13204
                },
                "notinteresting": {
                    "watched_episodes_count": 184,
                    "count": 36
                },
                "completed": {
                    "watched_episodes_count": 2111,
                    "count": 55
                }
            },
            "anime": {
                "total_mins": 494025,
                "watching": {
                    "watched_episodes_count": 1747,
                    "count": 21,
                    "left_to_watch_episodes": 410,
                    "left_to_watch_mins": 10250,
                    "total_episodes_count": 2157
                },
                "hold": {
                    "watched_episodes_count": 97,
                    "count": 23,
                    "left_to_watch_episodes": 462,
                    "left_to_watch_mins": 11550,
                    "total_episodes_count": 559
                },
                "plantowatch": {
                    "watched_episodes_count": 2324,
                    "count": 719,
                    "left_to_watch_episodes": 7829,
                    "left_to_watch_mins": 195725,
                    "total_episodes_count": 10153
                },
                "notinteresting": {
                    "watched_episodes_count": 662,
                    "count": 725
                },
                "completed": {
                    "watched_episodes_count": 17255,
                    "count": 1291
                }
            },
            "watched_last_week": {
                "total_mins": 130,
                "movies_mins": 130,
                "tv_mins": 0,
                "anime_mins": 0
            }
        }
    
# Group Need some help

<a href="http://uptime.statuscake.com/?TestID=JBfz26Wtd2" title="Website Uptime Monitoring"><img src="https://app.statuscake.com/button/index.php?Track=rVMgFtK0BZ&Days=1&Design=1" /></a>

## CORS
Currently API supports Cross Origin Resource Sharing (CORS) for AJAX requests on the **api.simkl.com** domain. You can read the [CORS W3C working draft](http://www.w3.org/TR/cors), or [this intro](http://code.google.com/p/html5security/wiki/CrossOriginRequestSecurity) from the HTML 5 Security Guide.

## Get in touch
We’re always happy to help you get set up with Simkl. If you're stuck, want to find out more or need to speak to us, [visit our API developer Discord server](https://discord.gg/MJsWNE4) or see the [support center](https://support.simkl.com).