# kinodata API

> kinodata связывает ID фильмов и сериалов в IMDb, Кинопоиске, TMDB и Кинориуме и по этой связке отдаёт данные тайтла: названия на русском и английском, оценки каждого источника, состав, медиа, связи, фильмографии, подборки и календарь релизов.

- Базовый адрес — `https://api.kinodata.space/v1.3`. Все запросы — `GET`, ключ — в заголовке `X-API-Key`.
- Успешный ответ — сами данные без обёртки. Ошибка — `{"error": {"code", "message", "field", "allowed", "hint"}}` и статус 4xx или 5xx. Ветвитесь по `error.code`.
- Текстовые поля приходят парами `_ru` и `_en`. `lang=ru` или `lang=en` оставляет одну половину. Нет перевода — `null`, без подстановки.
- Неизвестный параметр или значение — `400` со списком допустимых в `allowed` и подсказкой в `hint`. Не придумывайте параметры: берите их из справочника ниже.
- Каждая страница документации доступна в Markdown: добавьте `.md` к её адресу.

## Начало

- [Введение](https://kinodata.space/ru/docs.md): Что умеет kinodata API, базовый адрес и формат ответов.
- [Быстрый старт](https://kinodata.space/ru/docs/quickstart.md): Ключ, первый запрос, карточка тайтла и поиск — за пять минут.
- [Подключить к ИИ](https://kinodata.space/ru/docs/mcp.md): MCP-сервер kinodata: настройки для Claude, Claude Code, Cursor и VS Code, инструменты и расход квоты.

## Основы

- [Ключ и лимиты](https://kinodata.space/ru/docs/keys.md): Как передать ключ, пределы тарифов, заголовки остатка и как экономить запросы.
- [Языки ответа](https://kinodata.space/ru/docs/languages.md): Язык в имени поля, параметр lang и что пока есть только на одном языке.
- [Списки и пагинация](https://kinodata.space/ru/docs/lists.md): Форма любого списка, страницы и курсор, разделы и выбор полей.
- [Фильтры и сортировка](https://kinodata.space/ru/docs/filters.md): Операторы, все фильтры каталога, сортировка, окно оценок и пресеты.
- [Ошибки](https://kinodata.space/ru/docs/errors.md): Как выглядит ошибка, что значит каждый код и когда повторять запрос.

## Справочник

- [ID во всех каталогах](https://kinodata.space/ru/docs/ids.md): `GET /ids/{type}/{id}` — По ID тайтла в одном каталоге — его ID в остальных.
- [Каталог и поиск](https://kinodata.space/ru/docs/titles.md): `GET /titles` — Поиск тайтлов по названию и выборка по фильтрам из всей базы.

## Тайтл

- [Карточка тайтла](https://kinodata.space/ru/docs/titles/card.md): `GET /titles/{type}/{id}` — Всё о фильме или сериале одним запросом: названия, описания, оценки, даты, награды, медиа и состав.
- [Состав](https://kinodata.space/ru/docs/titles/cast.md): `GET /titles/{type}/{id}/cast` — Актёры, дубляж и съёмочная группа тайтла, сведённые из Кинопоиска, TMDB и Кинориума.
- [Медиа](https://kinodata.space/ru/docs/titles/media.md): `GET /titles/{type}/{id}/media` — Постеры, кадры, логотипы и видео тайтла одним списком.
- [Тексты](https://kinodata.space/ru/docs/titles/texts.md): `GET /titles/{type}/{id}/texts` — Факты, вопросы с ответами и цитаты о тайтле.
- [Серии](https://kinodata.space/ru/docs/titles/episodes.md): `GET /titles/{type}/{id}/episodes` — Серии сериала: названия, описания, даты выхода, длительность и оценки.
- [Связи](https://kinodata.space/ru/docs/titles/relations.md): `GET /titles/{type}/{id}/relations` — Похожие тайтлы, франшиза, отсылки к другим фильмам и упоминания в них.

## Люди

- [Поиск людей](https://kinodata.space/ru/docs/persons.md): `GET /persons` — Актёры, режиссёры и вся съёмочная группа по имени на русском или английском.
- [Карточка человека](https://kinodata.space/ru/docs/persons/card.md): `GET /persons/{type}/{id}` — Кто это: имена, даты, фото, биография, семья, награды, факты, роли за всю карьеру и самые известные работы.
- [Фильмография](https://kinodata.space/ru/docs/persons/filmography.md): `GET /persons/{type}/{id}/filmography` — Все работы человека с его ролями — с фильтрами и сортировкой каталога.
- [Совместные работы](https://kinodata.space/ru/docs/persons/together.md): `GET /persons/{type}/{id}/with/{type2}/{id2}` — Тайтлы, над которыми работали оба человека, и кем был в них каждый.

## Подборки и витрины

- [Подборки](https://kinodata.space/ru/docs/collections.md): `GET /collections` — Список подборок: топы Кинопоиска, которые обновляются каждый день, и авторские подборки.
- [Подборка](https://kinodata.space/ru/docs/collections/items.md): `GET /collections/{slug}` — Тайтлы подборки в порядке редактора — или с фильтрами и сортировкой каталога.
- [Топ](https://kinodata.space/ru/docs/charts/top.md): `GET /charts/top` — Лучшие по оценке фильмы и сериалы с порогом голосов — для рейтингов и «топ-100».
- [Скрытые жемчужины](https://kinodata.space/ru/docs/discover/hidden-gems.md): `GET /discover/hidden-gems` — Высоко оценённые фильмы и сериалы, о которых знает не так много людей.
- [Расхождения оценок](https://kinodata.space/ru/docs/discover/divergence.md): `GET /discover/divergence` — Тайтлы, которые на Кинопоиске и IMDb оценили по-разному.
- [Календарь релизов](https://kinodata.space/ru/docs/releases.md): `GET /releases` — Что выходит в кино, в онлайне и какие сезоны стартуют — по датам и регионам.

## Значения и статистика

- [Перечисления](https://kinodata.space/ru/docs/enums.md): `GET /enums` — Все закрытые наборы значений API с подписями на русском и английском — для типов и интерфейса.
- [Значения фильтров](https://kinodata.space/ru/docs/facets.md): `GET /filters` — Какие жанры, страны, площадки, метки и компании есть в базе и сколько у каждого тайтлов — для выпадающих списков.
- [Статистика базы](https://kinodata.space/ru/docs/meta/stats.md): `GET /meta/stats` — Сколько в базе тайтлов, людей, медиа, оценок, ID и насколько она полна.

## Дополнительно

- [Вся документация одним файлом](https://kinodata.space/ru/llms-full.txt): все страницы этого оглавления подряд
- [English documentation](https://kinodata.space/en/llms.txt): та же документация на английском
- [Сайт и тарифы](https://kinodata.space/ru/pricing): как получить ключ