> ## Documentation Index
> Fetch the complete documentation index at: https://api.simkl.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Headers and required parameters

> Required URL parameters and HTTP headers for every Simkl API request.

Every Simkl API request needs **three URL parameters** that identify your app, plus a **`User-Agent` header**. Endpoints that read or write user data also need an `Authorization: Bearer` token — and the cached catalog endpoints want you to *leave that header off*.

## Required URL parameters

Append these to **every** request URL — both public catalog calls and authenticated user calls:

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

| Parameter | Required | Value |
| - | - | - |
| `client_id` | always | Your `client_id` from [your developer settings](https://simkl.com/settings/developer/). |
| `app-name` | always | Short, lowercase identifier for your app (e.g. `plex-scrobbler`, `kodi-trakt-bridge`). |
| `app-version` | always | The current version of your app, e.g. `1.0`, `2.4.1`. |

<Tip>
  These three parameters help us see which apps are using the API, debug issues you report, and route around outages. They're cheap to send — please always include them.
</Tip>

## Required HTTP headers

| Header | Required | Value |
| - | - | - |
| `Content-Type` | on POST | `application/json` |
| `User-Agent` | always | A descriptive identifier for your app, ideally `name/version`. Examples: `PlexMediaServer/1.43.1.10540`, `kodi-simkl/0.9.2`, `MyAppName/2.4.1 (https://myapp.com)`. |
| `Authorization` | when token-required | `Bearer YOUR_ACCESS_TOKEN`. Required for endpoints that read or modify the user's library, scrobble session, ratings, settings, or playbacks. The scheme name is case-insensitive, so `bearer` works too — **the token itself is not**, so send it exactly as issued. **Leave the header off the cached catalog endpoints** — see below. |

<Warning>
  **Do not send `Authorization` on the Cloudflare-cached endpoints.** An `Authorization` header makes Cloudflare treat the request as private and stop serving it from the edge, so the call goes to Simkl's origin instead — slower for your user, and heavier for everyone else, for a response that is identical either way.

  Send it on nothing in this list:

  * Movie, show and anime summaries by Simkl ID — [`/movies`](/api-reference/simkl/get-movie), [`/tv`](/api-reference/simkl/get-tv-show), [`/anime`](/api-reference/simkl/get-anime)
  * Episode lists — [`/tv/episodes`](/api-reference/simkl/get-tv-episodes) and [`/anime/episodes`](/api-reference/simkl/get-anime-episodes)
  * The [Trending](/api-reference/trending) and [Calendar](/api-reference/calendar) data files on `data.simkl.in`

  These carry no per-user state, so a token changes nothing about the response. They are the same endpoints that need **no user token at all**, including on [AUTH V2](/api-reference/auth-v2), and that [do not count against your quota](/resources/rate-limits#what-does-not-count).

  The three URL parameters and the `User-Agent` header are still required on these calls. Only `Authorization` comes off.
</Warning>

<Note>
  As an alternative to the `client_id` query parameter, you may pass it as a `simkl-api-key` header. Either works; query-param form is preferred because it makes the request fully self-describing in URL form.
</Note>

## Putting it together

A typical authenticated call looks like:

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

A cached catalog call looks like — note the absence of `Authorization`, even if your app is holding a perfectly good token:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
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"
```

<Tip>
  In the [API Reference](/api-reference/simkl/get-anime-airing) playground these values are auto-filled — paste your `client_id`, `app-name`, `app-version`, and `access_token` once and they'll be reused.
</Tip>

## HTTP verbs

| Verb | Use | Success status |
| - | - | - |
| `GET` | Retrieve a resource. | `200 OK` |
| `POST` | Create or update. | `201 Created` |
| `DELETE` | Remove a resource. | `200 OK` or `204 No Content` |

The full list of status codes Simkl returns lives on the [Errors](/conventions/errors) page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.