# Release calendar

> What comes out in theaters and online, and which seasons start, by date and region.

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

Request: `GET https://api.kinodata.space/v1.3/releases`

A calendar row is one release: the title, and in `release` when, where and how it comes out. A film that comes out digitally in Russia, the US and worldwide on the same day makes three rows.

Without parameters the calendar shows 30 days from today, nearest dates first; within a day, announcements without votes go by TMDB popularity. Set the window with `from` and `to`, at most 400 days long. `released=true` keeps the releases in the window that have happened, `released=false` the upcoming ones; for “out this week, newest first”, set `from` a week back and add `released=true&sort=-date`.

For a “Coming soon to theaters” storefront, take Russian theatrical releases and sort them by how well known they are: `type=cinema&region=ru&sort=-votes_total`. The catalog’s filters work here (`kind`, `genre`, `country`, `required=poster`), and so does `fields`.

Season premieres and `release` rows carry no region, so `region` with them returns `400`: ask `type=cinema,digital&region=ru` and `type=series` separately. The calendar hides titles with neither a Russian nor an English name; `include_obscure=true` shows them.

## Query parameters

- `type` (csv) — Kinds of release, comma-separated. Labels are in `/enums`, set `release_types`.
  Values: `cinema`, `digital`, `series`, `release`.
  Default: all. Example: `type=cinema`.
- `region` (csv) — Regions, comma-separated. Only for `cinema` and `digital`.
  Values: `ru`, `us`, `world`.
  Default: all. Example: `region=ru`.
- `from · to` (date) — The calendar window, `YYYY-MM-DD`, both dates inclusive. At most 400 days long.
  Default: today plus 30 days. Example: `from=2026-11-01&to=2026-11-30`.
- `released` (boolean) — `true` keeps releases that have happened, `false` upcoming ones.
  Default: both.
- `sort` (enum) — `date` or `+date`: earliest first; `-date`: latest first; `-votes_total`: titles with the most votes first.
  Values: `date`, `-date`, `-votes_total`.
  Default: `date`. Example: `sort=-votes_total`.
- `include_obscure` (boolean) — `true` also shows titles with neither a Russian nor an English name, and titles without a poster or 50 votes.
  Default: `false`.
- `catalog filters` — The catalog’s filters: `kind=movie`, `genre=horror`, `country=ru`, `required=poster`. Details in [Filters and sorting](https://kinodata.space/en/docs/filters.md).
- `fields` (csv) — Which item fields to return, as in the [catalog](https://kinodata.space/en/docs/titles.md), plus `release`. IDs always come back.
  Example: `fields=title,poster_url,release`.
- `lang` (ru | en) — Keep one language in the response. Without it, text fields come in `_ru` and `_en` pairs. More in [Response languages](https://kinodata.space/en/docs/languages.md).
  Example: `lang=en`.
- `limit` (integer) — How many rows to return, a whole number from 1 to 50.
  Default: 50. Example: `limit=20`.
- `offset` (integer) — How many rows to skip, a whole number from 0.
  Default: 0.

## Response fields

- `from`, `to` (string) — The calendar window the API applied.
- `type`, `region` (array | null) — The `type` and `region` from the request. `null` means no selection.
- `items` (array) — Calendar rows: the title card, as in the [catalog](https://kinodata.space/en/docs/titles.md), and the release event.
  - `imdb_id`, `kp_id`, `tmdb_id`, `tmdb_tv_id`, `kinorium_id` (string | null) — The title’s catalog IDs. Always returned, even with `fields`.
  - `title_ru`, `title_en`, `title_original` (string | null) — Titles: Russian, English and in the original language.
  - `year` (integer | null) — Release year.
  - `release_date` (string | null) — First release date, `YYYY-MM-DD`.
  - `kind` (enum) — Kind of title: `movie`, `series`, `mini_series`, `tv_show`, `anime`, `cartoon`, `short`.
  - `poster_url_ru`, `poster_url_en` (string | null) — Poster for a Russian and an English storefront.
  - `posters_by_source` (object) — Each source’s poster: `kp`, `tmdb`, `imdb`, `kinorium`.
  - `rating_kp`, `rating_tmdb`, `rating_imdb`, `rating_kr`, `rating_letterboxd` (number | null) — Kinopoisk, TMDB, IMDb, Kinorium and Letterboxd ratings, 0–10 scale.
  - `votes_kp`, `votes_tmdb`, `votes_imdb` (integer | null) — Kinopoisk, TMDB and IMDb votes.
  - `countries` (array) — Countries: `code`, `name_ru`, `name_en`.
  - `genres` (array) — Genres: `slug`, `name_ru`, `name_en`.
  - `release` (object) — The release event.
    - `type` (enum) — `cinema`: in theaters; `digital`: on streaming and digital stores; `series`: a season premiere; `release`: a release whose source gave neither a kind nor a region.
      Values: `cinema`, `digital`, `series`, `release`.
    - `region` (enum | null) — `ru`: Russia; `us`: the United States; `world`: a worldwide release not tied to a country. `null` for `series` and `release`.
      Values: `ru`, `us`, `world`.
    - `date` (string) — Release date, `YYYY-MM-DD`.
    - `rerelease` (boolean) — A re-release: *Twilight* back in theaters.
    - `season` (integer | null) — The season number for `series`.
- `total` (integer) — How many rows the window holds, filters applied.
- `limit`, `offset`, `has_more` — Paging, as in [every list](https://kinodata.space/en/docs/lists.md#the-shape-of-a-list).

## Errors

| status | code | when |
|---|---|---|
| 400 | `invalid_request` | An unknown `type` or `region`; `region` together with `series` or `release`; a date not in `YYYY-MM-DD`; `to` before `from`, or a window over 400 days; `sort` other than `date`, `-date` or `-votes_total`; `q`, `preset` or `cursor`, which don’t apply to the calendar; an unknown filter or `fields` name; a parameter of another endpoint (such as `role` or `relation`); `limit` is not a whole number from 1, or `offset` is below 0. |
| 401 | `unauthorized` | The `X-API-Key` header is missing, or the key is unknown or revoked. |
| 429 | `rate_limited` | The per-second rate limit or the daily quota is used up. |

Every code and what to do about it is on the [Errors](https://kinodata.space/en/docs/errors.md) page.

## Examples

### English only

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "type=cinema" \
  --data-urlencode "region=ru" \
  --data-urlencode "sort=-votes_total" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,poster_url,release" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/releases"
```

Response `200`:

```json
{
  "from": "2026-10-12",
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt1325004",
      "kp_id": "432423",
      "tmdb_id": "24021",
      "tmdb_tv_id": null,
      "kinorium_id": "461497",
      "title_en": "The Twilight Saga: Eclipse",
      "year": 2010,
      "poster_url_en": "https://image.tmdb.org/t/p/original/dK4Gi1UdMiHzHc7r7CZQG4IQ9Sr.jpg",
      "release": {
        "type": "cinema",
        "region": "ru",
        "date": "2026-11-05",
        "rerelease": true,
        "season": null
      }
    },
    {
      "imdb_id": "tt33296751",
      "kp_id": "7518867",
      "tmdb_id": "1340206",
      "tmdb_tv_id": null,
      "kinorium_id": "12220331",
      "title_en": "Tuner",
      "year": 2025,
      "poster_url_en": "https://image.tmdb.org/t/p/original/kyM60vcgf7lfofmZB4F5Rj7OrHW.jpg",
      "release": {
        "type": "cinema",
        "region": "ru",
        "date": "2026-11-05",
        "rerelease": false,
        "season": null
      }
    },
    {
      "imdb_id": "tt36733027",
      "kp_id": "7783722",
      "tmdb_id": "1304434",
      "tmdb_tv_id": null,
      "kinorium_id": "12255198",
      "title_en": "Nobody",
      "year": 2025,
      "poster_url_en": "https://image.tmdb.org/t/p/original/mCa8Pb4L0X56gxV1sIQkLJ2RKz0.jpg",
      "release": {
        "type": "cinema",
        "region": "ru",
        "date": "2026-10-29",
        "rerelease": false,
        "season": null
      }
    }
  ],
  "limit": 3,
  "offset": 0,
  "region": [
    "ru"
  ],
  "to": "2026-11-11",
  "total": 45,
  "type": [
    "cinema"
  ]
}
```

### Both languages

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "type=cinema" \
  --data-urlencode "region=ru" \
  --data-urlencode "sort=-votes_total" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,poster_url,release" \
  "https://api.kinodata.space/v1.3/releases"
```

Response `200`:

```json
{
  "from": "2026-10-12",
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt1325004",
      "kp_id": "432423",
      "tmdb_id": "24021",
      "tmdb_tv_id": null,
      "kinorium_id": "461497",
      "title_ru": "Сумерки. Сага. Затмение",
      "title_en": "The Twilight Saga: Eclipse",
      "year": 2010,
      "poster_url_ru": "https://avatars.mds.yandex.net/get-kinopoisk-image/10703859/47c6c237-15e3-42f8-8cce-9d9d08902d76/600x900",
      "poster_url_en": "https://image.tmdb.org/t/p/original/dK4Gi1UdMiHzHc7r7CZQG4IQ9Sr.jpg",
      "release": {
        "type": "cinema",
        "region": "ru",
        "date": "2026-11-05",
        "rerelease": true,
        "season": null
      }
    },
    {
      "imdb_id": "tt33296751",
      "kp_id": "7518867",
      "tmdb_id": "1340206",
      "tmdb_tv_id": null,
      "kinorium_id": "12220331",
      "title_ru": "Настройщик",
      "title_en": "Tuner",
      "year": 2025,
      "poster_url_ru": "https://avatars.mds.yandex.net/get-kinopoisk-image/10703859/a1b23635-40fe-406b-8e54-a7104d654820/600x900",
      "poster_url_en": "https://image.tmdb.org/t/p/original/kyM60vcgf7lfofmZB4F5Rj7OrHW.jpg",
      "release": {
        "type": "cinema",
        "region": "ru",
        "date": "2026-11-05",
        "rerelease": false,
        "season": null
      }
    },
    {
      "imdb_id": "tt36733027",
      "kp_id": "7783722",
      "tmdb_id": "1304434",
      "tmdb_tv_id": null,
      "kinorium_id": "12255198",
      "title_ru": "Маленькие демоны путешествуют на Запад",
      "title_en": "Nobody",
      "year": 2025,
      "poster_url_ru": "https://avatars.mds.yandex.net/get-kinopoisk-image/10703959/611d17a7-e219-4310-90de-81d1fbf92d3e/600x900",
      "poster_url_en": "https://image.tmdb.org/t/p/original/mCa8Pb4L0X56gxV1sIQkLJ2RKz0.jpg",
      "release": {
        "type": "cinema",
        "region": "ru",
        "date": "2026-10-29",
        "rerelease": false,
        "season": null
      }
    }
  ],
  "limit": 3,
  "offset": 0,
  "region": [
    "ru"
  ],
  "to": "2026-11-11",
  "total": 45,
  "type": [
    "cinema"
  ]
}
```

### Online

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "type=digital" \
  --data-urlencode "region=ru" \
  --data-urlencode "sort=-votes_total" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,release" \
  "https://api.kinodata.space/v1.3/releases"
```

Response `200`:

```json
{
  "from": "2026-10-12",
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt1756855",
      "kp_id": "572477",
      "tmdb_id": "1204680",
      "tmdb_tv_id": null,
      "kinorium_id": "553192",
      "title_ru": "Хитрый койот",
      "title_en": "Coyote vs. Acme",
      "year": 2026,
      "release": {
        "type": "digital",
        "region": "ru",
        "date": "2026-10-22",
        "rerelease": false,
        "season": null
      }
    },
    {
      "imdb_id": "tt33253232",
      "kp_id": "8261895",
      "tmdb_id": "1336928",
      "tmdb_tv_id": null,
      "kinorium_id": "11534696",
      "title_ru": "Незваные гости",
      "title_en": "McMANSION",
      "year": 2025,
      "release": {
        "type": "digital",
        "region": "ru",
        "date": "2026-10-14",
        "rerelease": false,
        "season": null
      }
    },
    {
      "imdb_id": "tt32268691",
      "kp_id": "5595288",
      "tmdb_id": "1284046",
      "tmdb_tv_id": null,
      "kinorium_id": "11252404",
      "title_ru": "Натиск",
      "title_en": "Onslaught",
      "year": 2026,
      "release": {
        "type": "digital",
        "region": "ru",
        "date": "2026-10-22",
        "rerelease": false,
        "season": null
      }
    }
  ],
  "limit": 3,
  "offset": 0,
  "region": [
    "ru"
  ],
  "to": "2026-11-11",
  "total": 65,
  "type": [
    "digital"
  ]
}
```

### Seasons

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "type=series" \
  --data-urlencode "sort=-votes_total" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,release" \
  "https://api.kinodata.space/v1.3/releases"
```

Response `200`:

```json
{
  "from": "2026-10-12",
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt28751684",
      "kp_id": "5249042",
      "tmdb_id": null,
      "tmdb_tv_id": "234291",
      "kinorium_id": "11997917",
      "title_ru": "Папины дочки. Новые",
      "title_en": "Daddy's Daughters. New",
      "year": 2023,
      "release": {
        "type": "series",
        "region": null,
        "date": "2026-10-19",
        "rerelease": false,
        "season": 6
      }
    },
    {
      "imdb_id": "tt7631058",
      "kp_id": "1112513",
      "tmdb_id": null,
      "tmdb_tv_id": "84773",
      "kinorium_id": "1659219",
      "title_ru": "Властелин колец: Кольца власти",
      "title_en": "The Lord of the Rings: The Rings of Power",
      "year": 2022,
      "release": {
        "type": "series",
        "region": null,
        "date": "2026-11-11",
        "rerelease": false,
        "season": 3
      }
    },
    {
      "imdb_id": "tt12590266",
      "kp_id": "2000102",
      "tmdb_id": null,
      "tmdb_tv_id": "105248",
      "kinorium_id": "2402738",
      "title_ru": "Киберпанк: Бегущие по краю",
      "title_en": null,
      "year": 2022,
      "release": {
        "type": "series",
        "region": null,
        "date": "2026-10-20",
        "rerelease": false,
        "season": 2
      }
    }
  ],
  "limit": 3,
  "offset": 0,
  "region": null,
  "to": "2026-11-11",
  "total": 148,
  "type": [
    "series"
  ]
}
```

### Out this week

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "from=2026-10-03" \
  --data-urlencode "released=true" \
  --data-urlencode "sort=-date" \
  --data-urlencode "type=cinema,digital" \
  --data-urlencode "region=ru" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,release" \
  "https://api.kinodata.space/v1.3/releases"
```

Response `200`:

```json
{
  "from": "2026-10-03",
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt40385667",
      "kp_id": "11467031",
      "tmdb_id": null,
      "tmdb_tv_id": "333101",
      "kinorium_id": "12822306",
      "title_ru": "Остров сокровищ",
      "title_en": "Treasure Island",
      "year": 2026,
      "release": {
        "type": "digital",
        "region": "ru",
        "date": "2026-10-12",
        "rerelease": false,
        "season": null
      }
    },
    {
      "imdb_id": "tt44120119",
      "kp_id": null,
      "tmdb_id": null,
      "tmdb_tv_id": null,
      "kinorium_id": "13112838",
      "title_ru": "Последний стрим",
      "title_en": "Last Stream",
      "year": 2026,
      "release": {
        "type": "digital",
        "region": "ru",
        "date": "2026-10-12",
        "rerelease": false,
        "season": null
      }
    },
    {
      "imdb_id": "tt32293052",
      "kp_id": "12429497",
      "tmdb_id": "1471672",
      "tmdb_tv_id": null,
      "kinorium_id": "11243111",
      "title_ru": "Падение сэра Дугласа Уитерфорда",
      "title_en": "The Fall of Sir Douglas Weatherford",
      "year": 2026,
      "release": {
        "type": "cinema",
        "region": "ru",
        "date": "2026-10-10",
        "rerelease": false,
        "season": null
      }
    }
  ],
  "limit": 3,
  "offset": 0,
  "region": [
    "ru"
  ],
  "to": "2026-11-02",
  "total": 57,
  "type": [
    "cinema",
    "digital"
  ]
}
```

### Window over 400 days

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "from=2026-01-01" \
  --data-urlencode "to=2027-12-31" \
  "https://api.kinodata.space/v1.3/releases"
```

Response `400`:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "a release window spans at most 400 days",
    "field": "to"
  }
}
```