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

# Introduction

> Everything you need to know before you make your first call to the Simkl API.

The **Simkl API** is a JSON-over-HTTPS REST API for Movies, TV Shows, and Anime. Every endpoint listed in this reference returns JSON, accepts JSON for `POST` bodies, and follows the conventions described below.

If you've never made a Simkl API call before, start with the [Quickstart](/quickstart) — you'll have an `access_token` and a working request in under five minutes.

## Base URL

All endpoints live under a single host:

```
https://api.simkl.com
```

Pre-built JSON files (Trending, Calendar) are served from a separate CDN host:

```
https://data.simkl.in
```

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

See [Headers and required parameters](/conventions/headers) for the full reference, including the `User-Agent` and `Authorization` headers.

## Authentication

Endpoints that read or write user data require an `Authorization: Bearer ACCESS_TOKEN` header. You obtain a token via one of two flows:

<CardGroup cols={2}>
  <Card title="OAuth 2.0" icon="lock" href="/api-reference/oauth">
    For iOS, Android, web, and desktop apps that can open a browser.
  </Card>

  <Card title="PIN" icon="key" href="/api-reference/pin">
    For TVs, consoles, watches, CLIs, and media-server plugins.
  </Card>
</CardGroup>

Endpoints that don't need a user token are marked **No auth** in the API Reference.

## Conventions you'll see throughout

<CardGroup cols={2}>
  <Card title="Pagination" icon="list-ol" href="/conventions/pagination">
    `page` and `limit` URL parameters; `X-Pagination-*` response headers.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/resources/rate-limits">
    What signals Simkl returns when traffic is throttled and how to back off.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/conventions/errors">
    Every HTTP status code, with a stable anchor for each.
  </Card>

  <Card title="Standard media objects" icon="film" href="/conventions/standard-media-objects">
    The Movie / Show / Anime / Episode shapes every endpoint speaks.
  </Card>

  <Card title="Extended info" icon="expand" href="/conventions/extended-info">
    The `extended` URL parameter for richer fields.
  </Card>

  <Card title="Images" icon="image" href="/conventions/images">
    How to compose poster and fanart URLs from the path fragments returned in responses.
  </Card>
</CardGroup>

## Try it in the playground

Every endpoint in the API Reference has an interactive playground. Paste your `client_id`, `app-name`, `app-version`, and `access_token` once at the top of any reference page and they're reused across the rest.

<Tip>
  Need a `client_id`? [Create an app](https://simkl.com/settings/developer/) — free, no approval required.
</Tip>

## Tooling & codegen

This entire API reference is generated from a hand-curated **OpenAPI 3.1** specification. The same file is served at a stable URL so you can plug it into your own tooling — Postman / Insomnia for ad-hoc requests, an OpenAPI codegen tool (openapi-generator, oapi-codegen, kiota, etc.) for a typed client in your language, or an LLM tool that ingests OpenAPI for tool-use mapping.

<CardGroup cols={2}>
  <Card title="OpenAPI 3.1 spec (JSON)" icon="file-code" href="/openapi.json">
    `https://api.simkl.org/openapi.json` — the full machine-readable spec for every endpoint on this site. Import into Postman, Insomnia, or your codegen of choice.
  </Card>

  <Card title="LLM-friendly docs" icon="robot" href="/llms-full.txt">
    The whole doc site flattened into a single text file for ingestion by Claude / ChatGPT / Perplexity-style agents. See also the shorter [`llms.txt`](/llms.txt) index.
  </Card>
</CardGroup>