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

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

<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 typical public call looks like:

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