### Node.js openid-client v6 Example

Source: https://api.simkl.org/api-reference/oauth-libraries

Example of how to fetch an OAuth token using the Node.js openid-client library.

```APIDOC
## Node.js openid-client v6

### Description
This code snippet demonstrates how to use the `openid-client` Node.js library (v6) to fetch an OAuth 2.0 access token.

### Usage
1. Install the library: `npm install openid-client`
2. Replace placeholders with your actual credentials, authorization code, and state.

### Code Example
```javascript
import * as client from "openid-client";

// {algorithm: 'oauth2'} → use /.well-known/oauth-authorization-server (RFC 8414).
// Default would call /.well-known/openid-configuration which Simkl is not.
const config = await client.discovery(
  new URL("https://simkl.com"),
  "YOUR_CLIENT_ID",
  "YOUR_CLIENT_SECRET",
  undefined,
  { algorithm: "oauth2" },
);

const callback = new URL("YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=YOUR_STATE");
const token = await client.authorizationCodeGrant(config, callback);
console.log(token.access_token);
```
```

--------------------------------

### Get Changes: Full 14-Day Delta Example

Source: https://api.simkl.org/api-reference/simkl/get-changes

This example shows a full 14-day delta across all three buckets (shows, movies, anime). It is intended for first-time backfills rather than routine polling.

```json
{
  "shows": [
    1,
    2,
    40,
    43,
    "... ~5,200 more"
  ],
  "movies": [
    2152693,
    1875405,
    2559003,
    "... ~42,000 more"
  ],
  "anime": [
    41314,
    36602,
    38636,
    "... ~115 more"
  ]
}
```

--------------------------------

### Python httpx-oauth Example

Source: https://api.simkl.org/api-reference/oauth-libraries

Example of how to fetch an OAuth token using the Python httpx-oauth library.

```APIDOC
## Python httpx-oauth

### Description
This code snippet demonstrates how to use the `httpx-oauth` Python library to fetch an OAuth 2.0 access token.

### Usage
1. Install the library: `pip install httpx-oauth`
2. Replace placeholders with your actual credentials and authorization code.

### Code Example
```python
import asyncio
from httpx_oauth.oauth2 import BaseOAuth2

client = BaseOAuth2(
    "YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET",
    authorize_endpoint="https://simkl.com/oauth/authorize",
    access_token_endpoint="https://api.simkl.com/oauth/token",
)
token = asyncio.run(client.get_access_token(
    code="AUTHORIZATION_CODE_FROM_REDIRECT",
    redirect_uri="YOUR_REDIRECT_URI",
))
print(token["access_token"])
```
```

--------------------------------

### Python authlib Example

Source: https://api.simkl.org/api-reference/oauth-libraries

Example of how to fetch an OAuth token using the Python authlib library.

```APIDOC
## Python authlib

### Description
This code snippet demonstrates how to use the `authlib` Python library to fetch an OAuth 2.0 access token.

### Usage
1. Install the library: `pip install authlib httpx`
2. Replace placeholders with your actual credentials and authorization code.

### Code Example
```python
from authlib.integrations.httpx_client import OAuth2Client

client = OAuth2Client("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET",
                      token_endpoint="https://api.simkl.com/oauth/token")
token = client.fetch_token(
    "https://api.simkl.com/oauth/token",
    code="AUTHORIZATION_CODE_FROM_REDIRECT",
    redirect_uri="YOUR_REDIRECT_URI",
)
print(token["access_token"])
```
```

--------------------------------

### Node.js oauth4webapi Example

Source: https://api.simkl.org/api-reference/oauth-libraries

Example of how to fetch an OAuth token using the Node.js oauth4webapi library.

```APIDOC
## Node.js oauth4webapi

### Description
This code snippet demonstrates how to use the `oauth4webapi` Node.js library to fetch an OAuth 2.0 access token.

### Usage
1. Install the library: `npm install oauth4webapi`
2. Replace placeholders with your actual credentials, authorization code, and state.

### Code Example
```javascript
import * as oauth from "oauth4webapi";

const issuer = new URL("https://simkl.com");
// {algorithm: 'oauth2'} → use RFC 8414 metadata, not OIDC.
const discoveryResp = await oauth.discoveryRequest(issuer, { algorithm: "oauth2" });
const as = await oauth.processDiscoveryResponse(issuer, discoveryResp);

const clientObj = { client_id: "YOUR_CLIENT_ID" };
const clientAuth = oauth.ClientSecretBasic("YOUR_CLIENT_SECRET");

const callbackUrl = new URL("YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=YOUR_STATE");
const params = oauth.validateAuthResponse(as, clientObj, callbackUrl, "YOUR_STATE");
const response = await oauth.authorizationCodeGrantRequest(
  as, clientObj, clientAuth, params, "YOUR_REDIRECT_URI", oauth.nopkce,
);
const token = await response.json();
console.log(token.access_token);
```
```

--------------------------------

### Simkl API: Get All Items - Phase 1 Initial Full Pull

Source: https://api.simkl.org/api-reference/simkl/get-all-items

Example of an initial full pull for the Simkl API's /sync/all-items endpoint. This is recommended to run once per user for synchronization.

```json
{
  "shows": [
    {
      "added_to_watchlist_at": "2018-02-24T23:55:13Z",
      "last_watched_at": null,
      "user_rated_at": null,
      "user_rating": null,
      "status": "plantowatch",
      "last_watched": null,
      "next_to_watch": "S01E01",
      "watched_episodes_count": 0,
      "total_episodes_count": 178,
      "not_aired_episodes_count": 0,
      "show": {
        "title": "Charmed",
        "poster": "24/24273cee77f9d9f",
        "year": 1998,
        "ids": {
          "simkl": 297,
          "slug": "charmed",
          "imdb": "tt0158552"
        }
      }
    }
  ]
}
```

--------------------------------

### Start and Stop the Client

Source: https://api.simkl.org/api-reference/trending

Start the client to begin fetching data and restore persisted cache. Stop the client to signal termination.

```python
client.start()
# ... later ...
client.stop()
```

--------------------------------

### Get Changes: Movies Only Example

Source: https://api.simkl.org/api-reference/simkl/get-changes

This example demonstrates filtering the changes to include only movies using the `type=movies` parameter. This is useful for skipping catalogs where the user has no items.

```json
{
  "movies": [
    53078,
    53080,
    53082,
    "... ~8,200 more"
  ]
}
```

--------------------------------

### SimklTrendingClient Initialization and Lifecycle

Source: https://api.simkl.org/api-reference/trending

Demonstrates how to initialize and manage the SimklTrendingClient. Load trending data, start the client to begin fetching, and stop it to release resources.

```kotlin
// 2. Load it into a global `SIMKL_TRENDING_URLS: JSONObject` once at app startup
//    (e.g. in your Application.onCreate or DI module):
//      val SIMKL_TRENDING_URLS = JSONObject(
//          context.assets.open("simkl-trending-urls.json").bufferedReader().use { it.readText() }
//      )
// You can also skip the global and pass it directly: `SimklTrendingClient(cfg, trending = urls)`.
// The constructor throws if neither the global nor the `trending` arg is provided.

// ... inside your application logic ...

// val client = SimklTrendingClient(cfg = myConfig)
// client.start() // Call this once at app startup
// ...
// client.stop() // Call this when the app is shutting down

```

--------------------------------

### Python requests-oauthlib for Token Exchange

Source: https://api.simkl.org/api-reference/oauth-libraries

Leverage the requests-oauthlib library in Python for OAuth2 flows. Install with `pip install requests-oauthlib`. This example demonstrates fetching an access token.

```python
# pip install requests-oauthlib
from requests_oauthlib import OAuth2Session

session = OAuth2Session("YOUR_CLIENT_ID", redirect_uri="YOUR_REDIRECT_URI")
token = session.fetch_token(
    "https://api.simkl.com/oauth/token",
    code="AUTHORIZATION_CODE_FROM_REDIRECT",
    client_secret="YOUR_CLIENT_SECRET",
)
print(token["access_token"])
```

--------------------------------

### Kotlin Android Theme and Client Setup

Source: https://api.simkl.org/api-reference/trending

This Kotlin code sets up the OkHttpClient for network requests and demonstrates how to load a URL catalog from assets. It includes basic JSON parsing for trending data.

```kotlin
import kotlinx.coroutines.*
import kotlinx.coroutines.sync.Mutex
import kotlinx.coroutines.sync.withLock
import okhttp3.OkHttpClient
import okhttp3.Request
import org.json.JSONArray
import org.json.JSONObject
import java.io.File
import java.net.URLEncoder
import java.util.concurrent.TimeUnit
import kotlin.random.Random
import kotlin.math.pow

// === Load the URL catalog ===
// 1. Save the "Copy-paste JSON" block above as `simkl-trending-urls.json` in `app/src/main/assets/`.
```

--------------------------------

### Recommended Sync Workflow

Source: https://api.simkl.org/api-reference/simkl/get-all-items

Illustrates the correct two-phase approach for syncing user data to avoid overloading the API. Always check `/sync/activities` first and use `date_from` when calling `/sync/all-items`.

```text
> ## ⚠️ For continuous sync, do NOT call `/sync/all-items` on a timer
>
> The correct loop, every time you want to check for changes:
>
> 1. **Call [`GET
> /sync/activities`](/api-reference/simkl/get-activities) first.** It
> returns a tiny JSON of `last-modified` timestamps per category — costs
> almost nothing.
> 2. **Compare those timestamps to the ones you saved on your last
> sync.** If nothing changed, stop here. Do **not** call
> `/sync/all-items`.
> 3. **Only if a timestamp changed**, call
> `/sync/all-items?date_from=<your-last-sync-timestamp>`. The `date_from`
> makes the server return only the small delta of items that actually
> changed, not the user's entire library.
>
> Polling `/sync/all-items` directly on a timer (without checking
> `/sync/activities` and without `date_from`) downloads the user's whole
> library every call. It overloads the API server and hurts every other
> client.
>
> **Apps that do this will have their `client_id` suspended.** No
> warning, no appeal — we see the traffic pattern and turn the key off.
>
> Read the [**Sync guide**](/guides/sync)
> end-to-end before shipping anything that calls this endpoint. The full two-phase model (initial
> full sync → activities-checked delta loop) is documented there with
> reference implementations in Node and Python.
```

--------------------------------

### Get User Statistics (Example)

Source: https://api.simkl.org/api-reference/simkl/get-user-stats

This example demonstrates how to fetch watch statistics for a specific user. The `user_id` must be a positive integer. For the authenticated user, retrieve their ID from the /users/settings endpoint.

```http
POST /users/stats?user_id=51
```

--------------------------------

### Simkl API Get Changes Response Example

Source: https://api.simkl.org/api-reference/simkl/get-changes

This is an example of the response shape for the /changes endpoint. Keys are omitted if their respective buckets are empty. An empty object is returned if nothing has changed.

```json
{
  "movies": [
    56145,
    1029384
  ],
  "shows": [
    17465,
    92834
  ],
  "anime": [
    39687
  ]
}
```

--------------------------------

### Fetch TV Show Details

Source: https://api.simkl.org/conventions/extended-info

This example demonstrates fetching detailed information for a TV show. The 'extended' parameter is not needed for this endpoint as it returns a full record by default.

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

--------------------------------

### Get Changes: CSV Type Filter Example

Source: https://api.simkl.org/api-reference/simkl/get-changes

Example using a CSV string for the `type` parameter to request changes for shows and movies, excluding anime. The response will only contain the specified types.

```json
{
  "shows": [
    2,
    40,
    500,
    "... ~825 more"
  ],
  "movies": [
    53078,
    53080,
    53082,
    "... ~8,200 more"
  ]
}
```

--------------------------------

### Handle No Results

Source: https://api.simkl.org/api-reference/simkl/search-by-text

This example shows how to query the API in a way that is expected to return no results, demonstrating the API's behavior for empty result sets.

```Shell
curl -H "User-Agent: my-app-name/1.0" \
  "https://api.simkl.com/search/movie?q=zzznoresultzzz&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
```

--------------------------------

### Initialize SimklTrendingClient

Source: https://api.simkl.org/api-reference/trending

Instantiate the client with optional configuration or data. Requires SIMKL_TRENDING_URLS to be defined globally or passed as data.

```python
client = SimklTrendingClient(config={'client_id': 'YOUR_CLIENT_ID', 'app_name': 'MyApp', 'app_version': '1.0', 'size': 100, 'supported_types': ['movies', 'tv', 'anime']})

```

--------------------------------

### Get Changes: Daily Poll Example

Source: https://api.simkl.org/api-reference/simkl/get-changes

Example of a daily poll using `date_from` set to approximately 24 hours ago. This snippet shows a response with updated IDs for shows, anime, and movies.

```json
{
  "shows": [
    2,
    40,
    500,
    "... ~825 more"
  ],
  "anime": [
    44822,
    2017210,
    2254562,
    "... ~20 more"
  ],
  "movies": [
    53078,
    53080,
    53082,
    "... ~8,200 more"
  ]
}
```

--------------------------------

### Node.js openid-client v6 for Token Exchange

Source: https://api.simkl.org/api-reference/oauth-libraries

Use the openid-client library in Node.js for OAuth2 flows. Install with `npm install openid-client`. This example configures the client for Simkl's OAuth2 endpoint and fetches a token.

```javascript
// npm install openid-client
import * as client from "openid-client";

// {algorithm: 'oauth2'} → use /.well-known/oauth-authorization-server (RFC 8414).
// Default would call /.well-known/openid-configuration which Simkl is not.
const config = await client.discovery(
  new URL("https://simkl.com"),
  "YOUR_CLIENT_ID",
  "YOUR_CLIENT_SECRET",
  undefined,
  { algorithm: "oauth2" },
);

const callback = new URL("YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=YOUR_STATE");
const token = await client.authorizationCodeGrant(config, callback);
console.log(token.access_token);
```

--------------------------------

### Pull All Shows for Initial Sync

Source: https://api.simkl.org/guides/sync

Use this command to pull all show items for a user during the initial sync. Ensure you replace placeholders with your actual client ID, app name, and access token. This is part of a sequential process for different item types.

```bash
curl "https://api.simkl.com/sync/all-items/shows?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
  -H "User-Agent: my-app-name/1.0" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

--------------------------------

### Get Anime Ratings (Completed)

Source: https://api.simkl.org/api-reference/simkl/get-watchlist-ratings

Fetches anime that have been marked as completed. This example shows how to filter for a specific type and completion status.

```curl
curl
'https://api.simkl.com/ratings/anime?user_watchlist=completed&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'User-Agent: my-app-name/1.0'
```

--------------------------------

### Example API Request with App Identification

Source: https://api.simkl.org/changelog

Demonstrates the required format for API requests including client ID, app name, and app version.

```url
/endpoint?client_id=CLIENT_ID&app-name=my-app-name&app-version=1.0
```

--------------------------------

### Get Watched - Single Show in Library

Source: https://api.simkl.org/api-reference/simkl/get-watched

Example for a single show ID that is present in the user's library, marked as completed. This demonstrates how to check the status of a show.

```json
[
  {
    "ids": {
      "simkl": 2090
    }
  }
]
```

--------------------------------

### POST /scrobble/start

Source: https://api.simkl.org/api-reference/simkl/scrobble-start

Creates or replaces the user's active "watching now" session for a given item. This should be called when playback begins or to resume a paused session. The endpoint supports starting sessions for movies, shows, and anime, requiring progress information and media identifiers.

```APIDOC
## POST /scrobble/start

### Description
Creates or replaces the user's active "watching now" session for the given item. Call this when playback begins, or to resume a previously paused session.

### Method
POST

### Endpoint
/scrobble/start

### Parameters
#### Request Body
- **progress** (float) - Required - 0–100, max 2 decimals. Response normalizes to `75` not `75.00`.
- **movie** / **show** / **anime** (object) - Required - Title + year + ids. `simkl` ID alone is enough.
- **episode** (object) - Required for shows/anime - `season` + `number`, or `ids`.

### Request Example
```json
{
  "progress": 75.5,
  "movie": {
    "title": "Inception",
    "year": 2010,
    "ids": {
      "simkl": 49108,
      "imdb": "tt1375666"
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (integer) - The ID of the scrobble session.
- **action** (string) - The action performed (e.g., "start").
- **progress** (float) - The progress percentage.
- **movie** / **show** / **anime** (object) - The media object with `ids` and an `episode` block.
- **episode** (object) - For shows/anime, includes `season` and `number`.

#### Response Example
```json
{
  "id": 12345,
  "action": "start",
  "progress": 75.5,
  "movie": {
    "title": "Inception",
    "year": 2010,
    "ids": {
      "simkl": 49108,
      "imdb": "tt1375666"
    },
    "episode": {
      "season": 1,
      "number": 1
    }
  }
}
```

### Errors
- **400empty_field**: No `movie`, `show`, or `anime` in the body.
- **400RATE_LIMIT**: A 20-second per-user lock collision.
- **401user_token_failed**: Missing / invalid bearer token.
- **404id_err**: Item could not be matched.
```

--------------------------------

### Get Movie Ratings (Watching)

Source: https://api.simkl.org/api-reference/simkl/get-watchlist-ratings

Fetches movies currently being watched. This example demonstrates filtering by type and watchlist status. Note that 'watching' might return null if no movies are in that state.

```curl
curl
'https://api.simkl.com/ratings/movies?user_watchlist=watching&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'User-Agent: my-app-name/1.0'
```

--------------------------------

### Get Watched - Single Movie Not in Library

Source: https://api.simkl.org/api-reference/simkl/get-watched

Example of a single movie ID that Simkl recognizes but is not present in the user's library. The response will indicate `result: true` if watched, or `false` if not.

```json
[
  {
    "ids": {
      "simkl": 53536
    }
  }
]
```

--------------------------------

### Get Changes: Future Date Returns Empty Object

Source: https://api.simkl.org/api-reference/simkl/get-changes

Example showing the response when a future date is provided for `date_from`. The API returns an empty JSON object `{}` to indicate no changes.

```json
{}
```

--------------------------------

### Get Changes: Unknown Type Fallback Example

Source: https://api.simkl.org/api-reference/simkl/get-changes

Demonstrates the behavior when an unknown type (e.g., `type=foo`) is provided. Unknown types are silently bucketed as anime, and only anime IDs are returned.

```json
{
  "anime": [
    41314,
    36602,
    38636,
    "... ~115 more"
  ]
}
```

--------------------------------

### Configure and Subscribe to Trending Catalogs (Kotlin)

Source: https://api.simkl.org/api-reference/trending

Initialize a Simkl trending client in Kotlin, defining various catalog sources and custom transformations, then subscribe to receive and render trending content updates.

```kotlin
val cfg = SimklTrendingConfig(
    supportedTypes = listOf("movies", "tv", "anime"),
    size = 500,
    catalogs = listOf(
        SimklTrendingCatalogConfig(id = "movies_today",       source = "movies"),                                                    // trending (JSON title)
        SimklTrendingCatalogConfig(id = "tv_today",           source = "tv"),
        SimklTrendingCatalogConfig(id = "anime_today",        source = "anime"),
        SimklTrendingCatalogConfig(id = "movies_anticipated", source = "movies", title = "Most Watchlisted Movies on Simkl",
            transform = { items -> items.sortedByDescending { it.optInt("plan_to_watch") } }),
        SimklTrendingCatalogConfig(id = "hidden_gems_anime",  source = "anime",  title = "Hidden Gem Anime on Simkl",
            transform = { items -> items.filter {
                it.optJSONObject("ratings")?.optJSONObject("simkl")?.optDouble("rating", 0.0) ?: 0.0 >= 8.5
                    && it.optInt("watched", 999) < 100
            } }),
        SimklTrendingCatalogConfig(id = "best_of_hbo",        source = "tv",     title = "Best of HBO — on Simkl",
            transform = { items -> items.filter {
                it.optString("network") == "HBO" && it.optString("status") == "ended"
            } }),
    ),
)
runBlocking {
    val client = SimklTrendingClient(cfg)
    client.subscribeCatalogs { rows -> for (r in rows) renderRow(r.title, r.items) }
    client.start()
}

```

--------------------------------

### Main Execution Function (Dart)

Source: https://api.simkl.org/api-reference/trending

Entry point for the Simkl Trending client application. Initializes the client, subscribes to catalog updates, and starts the fetching process.

```dart
Future<void> main() async {
    // For Flutter, set persistFile via path_provider:
    //   final dir = await getApplicationCacheDirectory();
    //   final cfg = SimklTrendingConfig(persistFile: File('${dir.path}/simkl-trending-cache.json'));
    final client = SimklTrendingClient();
    client.subscribeCatalogs((rows) {
      for (final row in rows) print('${row.title}: ${row.items.length} items');
    });
    await client.start();
  }
```

--------------------------------

### Node.js: Configure Passport OAuth2 Strategy

Source: https://api.simkl.org/api-reference/oauth-libraries

This example shows how to configure the passport-oauth2 strategy for authentication. It requires the passport-oauth2 library to be installed. Replace placeholders with your Simkl API credentials and redirect URI.

```javascript
// npm install passport-oauth2
import OAuth2Strategy from "passport-oauth2";

passport.use(new OAuth2Strategy(
  {
    authorizationURL: "https://simkl.com/oauth/authorize",
    tokenURL:         "https://api.simkl.com/oauth/token",
    clientID:         "YOUR_CLIENT_ID",
    clientSecret:     "YOUR_CLIENT_SECRET",
    callbackURL:      "YOUR_REDIRECT_URI",
  },
  (accessToken, refreshToken, profile, done) => done(null, { accessToken }),
));
```

--------------------------------

### Load URL Catalog in Swift

Source: https://api.simkl.org/api-reference/trending

Example of loading the URL catalog in Swift for iOS applications.

```swift
import Foundation

// === Load the URL catalog ===

```

--------------------------------

### Get Activities with Node.js Fetch

Source: https://api.simkl.org/api-reference/simkl/get-activities

Fetch user activities using JavaScript's Fetch API in a Node.js environment. This example demonstrates constructing URL parameters and setting necessary headers for authentication and identification.

```javascript
const params = new URLSearchParams({
  client_id:     CLIENT_ID,
  'app-name':    'my-app-name',
  'app-version': '1.0',
});

const activities = await
fetch(`https://api.simkl.com/sync/activities?${params}`, {
  headers: {
    'User-Agent':    'my-app-name/1.0',
    'Authorization': `Bearer ${ACCESS_TOKEN}`,
  },
}).then(r => r.json());
```

--------------------------------

### SimklTrendingClient Initialization and Subscription

Source: https://api.simkl.org/api-reference/trending

Initializes the SimklTrendingClient and subscribes to catalog updates. The client is then started to begin fetching data.

```python
client = SimklTrendingClient()
client.subscribe_catalogs(lambda rows: [print(f"{r['title']}: {len(r['items'])} items") for r in rows])
client.start()
# import signal; signal.signal(signal.SIGINT, lambda *_: (client.stop(), exit(0)))
```

--------------------------------

### Example Authenticated Simkl API Call

Source: https://api.simkl.org/conventions/headers

This example demonstrates a typical authenticated API call, including required URL parameters and HTTP headers.

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

--------------------------------

### Get Watched - Mixed Results Bulk Request

Source: https://api.simkl.org/api-reference/simkl/get-watched

Example of a bulk request with three items: one known but unwatched, one unknown ID, and one in the user's library. This shows how the API handles a mix of results.

```json
[
  {
    "ids": {
      "simkl": 53536
    }
  },
  {
    "ids": {
      "simkl": 99999992
    }
  },
  {
    "ids": {
      "simkl": 17465
    }
  }
]
```

--------------------------------

### Get All Items with All Modifiers

Source: https://api.simkl.org/api-reference/simkl/get-all-items

This example demonstrates how to call the API to retrieve all items with every possible modifier enabled. This is useful for inspecting all available fields in a single response, though it is not a production default due to payload size and Pro-only fields.

```APIDOC
## GET /sync/all-items

### Description
Retrieves all items from the user's Simkl library, including shows and movies. This specific call includes all possible modifiers for comprehensive data inspection.

### Method
GET

### Endpoint
/sync/all-items?extended=full_anime_seasons&memos=yes&next_watch_info=yes&episode_watched_at=yes&episode_tvdb_id=yes&include_all_episodes=yes&allow_rewatch=yes

### Parameters
#### Query Parameters
- **extended** (string) - Optional - Specifies extended data to include, e.g., `full_anime_seasons`.
- **memos** (string) - Optional - Include memos in the response (e.g., `yes`).
- **next_watch_info** (string) - Optional - Include next watch information (e.g., `yes`).
- **episode_watched_at** (string) - Optional - Include episode watched at timestamp (e.g., `yes`).
- **episode_tvdb_id** (string) - Optional - Include episode TVDB ID (e.g., `yes`).
- **include_all_episodes** (string) - Optional - Include all episodes for shows (e.g., `yes`).
- **allow_rewatch** (string) - Optional - Include rewatch information (e.g., `yes`).

### Response
#### Success Response (200)
- **shows** (array) - List of shows in the user's library.
  - **added_to_watchlist_at** (string) - Timestamp when added to watchlist.
  - **last_watched_at** (string) - Timestamp of the last watched item.
  - **user_rated_at** (string) - Timestamp when rated by the user.
  - **user_rating** (number) - User's rating for the item.
  - **status** (string) - Watch status (e.g., `completed`).
  - **last_watched** (string) - Last watched episode identifier.
  - **total_episodes_count** (number) - Total number of episodes.
  - **not_aired_episodes_count** (number) - Number of episodes not yet aired.
  - **show** (object) - Details about the show.
    - **title** (string) - Title of the show.
    - **poster** (string) - URL or identifier for the show's poster.
    - **year** (number) - Release year of the show.
    - **runtime** (number) - Runtime of each episode in minutes.
    - **ids** (object) - Various IDs for the show (simkl, slug, mal, anidb, anilist, kitsu).
  - **anime_type** (string) - Type of anime (e.g., `tv`).
  - **is_rewatch** (boolean) - Indicates if it's a rewatch.
  - **rewatch_id** (number) - Identifier for the rewatch entry.
  - **rewatch_status** (string) - Status of the rewatch.
  - **seasons** (array) - List of seasons for the show.
    - **number** (number) - Season number.
    - **episodes** (array) - List of episodes in the season.
      - **number** (number) - Episode number.
      - **watched_at** (string) - Timestamp when the episode was watched.
- **movies** (array) - List of movies in the user's library.
  - **added_to_watchlist_at** (string) - Timestamp when added to watchlist.
  - **last_watched_at** (string) - Timestamp of the last watched item.
  - **user_rated_at** (string) - Timestamp when rated by the user.
  - **user_rating** (number) - User's rating for the item.
  - **status** (string) - Watch status (e.g., `completed`).
  - **watched_episodes_count** (number) - Count of watched episodes (0 for movies).
  - **total_episodes_count** (number) - Total number of episodes (0 for movies).
  - **not_aired_episodes_count** (number) - Not applicable for movies.
  - **movie** (object) - Details about the movie.
    - **title** (string) - Title of the movie.
    - **poster** (string) - URL or identifier for the movie's poster.
    - **year** (number) - Release year of the movie.
    - **runtime** (number) - Runtime of the movie in minutes.
    - **ids** (object) - Various IDs for the movie (simkl, slug, imdb, tmdb, tvdb).
  - **is_rewatch** (boolean) - Indicates if it's a rewatch.
  - **rewatch_id** (number) - Identifier for the rewatch entry.
  - **rewatch_status** (string) - Status of the rewatch.

### Request Example
```http
GET /sync/all-items?extended=full_anime_seasons&memos=yes&next_watch_info=yes&episode_watched_at=yes&episode_tvdb_id=yes&include_all_episodes=yes&allow_rewatch=yes HTTP/1.1
Host: simkl.com
Authorization: Bearer YOUR_API_KEY
```

### Response Example
```json
{
  "shows": [
    {
      "added_to_watchlist_at": "2026-05-15T00:13:18Z",
      "last_watched_at": "2026-05-15T00:13:18Z",
      "user_rated_at": null,
      "user_rating": null,
      "status": "completed",
      "last_watched": null,
      "total_episodes_count": 26,
      "not_aired_episodes_count": 0,
      "show": {
        "title": "Cowboy Bebop",
        "poster": "36/36842f1bceb6b39",
        "year": 1998,
        "runtime": 25,
        "ids": {
          "simkl": 37089,
          "slug": "cowboy-bebop",
          "mal": "1",
          "anidb": "23",
          "anilist": "1",
          "kitsu": "1"
        }
      },
      "anime_type": "tv",
      "is_rewatch": false
    }
  ],
  "movies": [
    {
      "added_to_watchlist_at": "2026-04-10T20:13:02Z",
      "last_watched_at": "1994-09-01T16:00:00Z",
      "user_rated_at": null,
      "user_rating": null,
      "status": "completed",
      "watched_episodes_count": 0,
      "total_episodes_count": 0,
      "not_aired_episodes_count": 0,
      "movie": {
        "title": "The Godfather",
        "poster": "10/102447562f6b49ff3a",
        "year": 1972,
        "runtime": 175,
        "ids": {
          "simkl": 53434,
          "slug": "the-godfather",
          "imdb": "tt0068646",
          "tmdb": "238",
          "tvdb": "275"
        }
      },
      "is_rewatch": false
    }
  ]
}
```
```

--------------------------------

### POST /scrobble/start

Source: https://api.simkl.org/api-reference/scrobble

Starts a scrobble session, marking a show as 'Watching now' and resuming a paused session if applicable.

```APIDOC
## POST /scrobble/start

### Description
Starts a scrobble session, marking a show as 'Watching now' and resuming a paused session if applicable.

### Method
POST

### Endpoint
/scrobble/start
```