# kino.is — full agent guide

> Online movie catalog (ru/en/uk). Below: public read-only JSON API. All endpoints are GET,
> CORS-open for GET, return JSON, and accept an optional `lang` query param (ru | en | uk).
> Prefer the MCP server (https://kino.is/.well-known/mcp.json) for structured tool access.

## Public API (base https://kino.is)

### Search
`GET /api/search?q={query}&lang={ru|en|uk}`
Full-text search over films and people. Returns matching films (id, title, year, poster) and persons.
Example: https://kino.is/api/search?q=inception&lang=en

### Catalog (filtered film list)
`GET /api/catalog?type={film|serial|cartoon|cartoon-series|anime}&genre={name}&country={name}&year={YYYY}&keyword={id}&sort={new|rating|popular}&page={n}&lang={..}`
Paginated, filterable film list. `GET /api/filters?lang=..` returns the available genres, countries, types and sorts.
Example: https://kino.is/api/catalog?genre=драма&year=2024&sort=rating&lang=ru

### Film details
`GET /api/film/{id}?lang={..}`
One film: titles, year, type, ratings (Kinopoisk/IMDb), genres, countries, synopsis, runtime, cast & crew.
Related: `/api/film/{id}/geo` (where-to-watch + premiere by country), `/api/film/{id}/sessions` (UA cinema sessions).
Human page: https://kino.is/film/{id} — or Markdown: https://kino.is/film/{id}.md

### Person details
`GET /api/person/{id}?lang={..}` — name, bio, filmography. Human: https://kino.is/person/{id} (or .md)

### Cinema & showtimes
Unified catalog — one model (country → city → theater → film → showtime) over all sources.
`GET /api/v1/cinema/countries` — countries with cinema data + capabilities (sessions/cities/theaters). Start here.
`GET /api/v1/cinema/now-showing?country={UA|RU|KZ|DE|PL|LV|UZ|AM|KG|GE|...}` — films now in cinemas (unified for any country).
`GET /api/v1/cinema/cities?country={KZ|..}` — cities (for per-city providers like Kazakhstan/Kinopark).
`GET /api/v1/cinema/theaters?country={UA|KZ}&city={..}` — cinema/theater directory.
`GET /api/v1/cinema/theaters/{slug}?country={..}&city={..}` — one theater with its films and showtimes.
`GET /api/v1/films/{id}/showtimes` — showtimes for one film across cinemas (day → times, booking links).
Human pages: https://kino.is/cinema, https://kino.is/cinema/{cc}, https://kino.is/cinemas, https://kino.is/cinemas/{slug}

### Lists, calendar, discovery
`GET /api/lists` and `GET /api/list/{slug}` — curated collections.
`GET /api/now-showing`, `GET /api/calendar`, `GET /api/birthdays` — discovery feeds.

## Notes
- Identifiers: kino.is uses internal numeric film/person ids (in URLs). Films also carry kinopoisk_id/imdb_id where known.
- Languages: ru is the default (root URLs); en → `/en/…`, uk → `/uk/…`; APIs take `?lang=`.
- Structured markup: every film/person HTML page embeds Schema.org JSON-LD.
- Sitemaps: https://kino.is/sitemap.xml