# Introduction

> What the kinodata API does, the base URL and the response format.

> Documentation index for agents: https://kinodata.space/en/llms.txt — the whole documentation in one file: https://kinodata.space/en/llms-full.txt

kinodata links movie and series IDs across IMDb, Kinopoisk, TMDB and Kinorium. On top of those links the API serves title data: Russian and English titles, ratings from every source, cast and crew, stills and trailers, related titles, filmographies and collections.

## One movie, five IDs

*Inception* has a different ID in every catalog, and nothing in the numbers says they are the same movie:

| catalog | type in the path | ID |
|---|---|---|
| IMDb | `imdb` | `tt1375666` |
| Kinopoisk | `kp` | `447301` |
| TMDB, movies | `tmdb` | `27205` |
| TMDB, series | `tmdb_tv` | — |
| Kinorium | `kinorium` | `472809` |

Any of them opens the same title: `/titles/imdb/tt1375666`, `/titles/kp/447301` and `/titles/tmdb/27205` return the same card. Use whichever ID your database already has.

## Base URL

```text
https://api.kinodata.space/v1.3
```

Paths in the reference are relative to it: `/ids/kp/447301` means `https://api.kinodata.space/v1.3/ids/kp/447301`. Every request is a `GET` over HTTPS, with your API key in the `X-API-Key` header.

## Response format

JSON in UTF-8. A successful response is the data itself, with no wrapper. An error is an `error` object with a 4xx or 5xx status:

```json
{ "error": { "code": "not_found", "message": "title not found: kp 999999999" } }
```

Tell success from failure by the HTTP status, not by the shape of the body. The details are on the [Errors](https://kinodata.space/en/docs/errors.md) page.

## Languages

Text fields come in pairs: `title_ru` and `title_en`, `name_ru` and `name_en`. The language is always in the field name.

Add `lang=ru` or `lang=en` to keep one language in the response; the field names stay the same. When there is no translation the field is `null`, and falling back to another language or the original title is up to you.

## Keep the key on the server

Your API key acts on your behalf. Keep it on a server or in an environment variable. In website or mobile app code, anyone who opens the developer tools can see it.

## Next

- [Quickstart](https://kinodata.space/en/docs/quickstart.md): your first request in five minutes.
- [Response languages](https://kinodata.space/en/docs/languages.md): how the `_ru` and `_en` fields work.
- [IDs in every catalog](https://kinodata.space/en/docs/ids.md): the simplest endpoint.