# Collection

> A collection’s titles in the editor’s order, or with the catalog’s filters and sorting.

> 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/collections/{slug}`

Without parameters a collection comes in the editor’s order: `ord` is the title’s place in it, from 1. For Kinopoisk tops, that is the place in the top.

Add a filter, a `q` search or `sort`, and the collection becomes a search scope: the catalog engine builds the answer, and `ord` keeps the original place. With a filter or `q`, `total` is `null`, as in the catalog. All the [filters and sorting](https://kinodata.space/en/docs/filters.md) work here, and so does `fields`.

You can pick a collection’s titles in the catalog too: `/titles?collection=popular-titles`. It has a cursor but no `ord`.

## Path parameters

- `slug` (string, required) — The collection’s name from the [list of collections](https://kinodata.space/en/docs/collections.md).
  Example: `top-movies`.

## Query parameters

- `filters, q and sort` — The catalog’s filters, search and sorting: `kind=movie`, `q=matrix`, `sort=-rating_imdb`. Details in [Filters and sorting](https://kinodata.space/en/docs/filters.md).
  Default: the editor’s order.
- `fields` (csv) — Which item fields to return, as in the [catalog](https://kinodata.space/en/docs/titles.md), plus `ord` and `note`. IDs always come back.
  Example: `fields=title,year,ord`.
- `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 titles to return, a whole number from 1 to 50.
  Default: 50. Example: `limit=10`.
- `offset` (integer) — How many titles to skip, a whole number from 0.
  Default: 0.

## Response fields

- `collection` (object) — The collection itself: the same object as in the [list of collections](https://kinodata.space/en/docs/collections.md).
  - `slug` (string) — The collection’s name in the URL and in the catalog’s `collection` filter.
  - `name_ru`, `name_en` (string | null) — Name.
  - `description_ru`, `description_en` (string | null) — Description. Editorial collections may have none.
  - `poster_url` (string | null) — The collection’s cover image. Without one of its own, the first title’s poster.
  - `items_count` (integer) — How many titles the collection holds.
  - `created_at`, `updated_at` (string) — When the collection was created and when its contents last changed, ISO 8601 in UTC.
- `items` (array) — Titles: the same card as in the [catalog](https://kinodata.space/en/docs/titles.md).
  - `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`.
  - `ord` (integer) — The title’s place in the collection, from 1.
  - `note` (string | null) — The editor’s note on the title.
- `total` (integer | null) — How many titles the collection holds. `null` with a filter or `q`.
- `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 filter, `sort` key 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; a repeated parameter; `cursor`, since a collection pages with `offset`. |
| 404 | `not_found` | No collection with this `slug`. |
| 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 "limit=3" \
  --data-urlencode "fields=title,year,rating_kp,ord" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/collections/top-movies"
```

Response `200`:

```json
{
  "collection": {
    "slug": "top-movies",
    "name_en": "500 Best Movies",
    "description_en": "The 500 best films as rated by Kinopoisk viewers — the classics and the newer films audiences rate highest.",
    "poster_url": "https://api.kinodata.space/uploads/56c18b27af130ab32118807743318e000bb750fceccfb153dec0bac6df6e7d64.png",
    "items_count": 500,
    "created_at": "2026-06-24T09:41:15.166286Z",
    "updated_at": "2026-10-12T14:15:10.418807Z"
  },
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0816692",
      "kp_id": "258687",
      "tmdb_id": "157336",
      "tmdb_tv_id": null,
      "kinorium_id": null,
      "title_en": "Interstellar",
      "year": 2014,
      "rating_kp": 8.7,
      "ord": 1
    },
    {
      "imdb_id": "tt0111161",
      "kp_id": "326",
      "tmdb_id": "278",
      "tmdb_tv_id": null,
      "kinorium_id": null,
      "title_en": "The Shawshank Redemption",
      "year": 1994,
      "rating_kp": 9.1,
      "ord": 2
    },
    {
      "imdb_id": "tt0120689",
      "kp_id": "435",
      "tmdb_id": "497",
      "tmdb_tv_id": null,
      "kinorium_id": null,
      "title_en": "The Green Mile",
      "year": 1999,
      "rating_kp": 9.1,
      "ord": 3
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 500
}
```

### Editor’s order

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,rating_kp,ord" \
  "https://api.kinodata.space/v1.3/collections/top-movies"
```

Response `200`:

```json
{
  "collection": {
    "slug": "top-movies",
    "name_ru": "500 лучших фильмов",
    "name_en": "500 Best Movies",
    "description_ru": "Пятьсот лучших фильмов по оценкам зрителей Кинопоиска — классика и новые картины, которые зрители ценят выше всего.",
    "description_en": "The 500 best films as rated by Kinopoisk viewers — the classics and the newer films audiences rate highest.",
    "poster_url": "https://api.kinodata.space/uploads/56c18b27af130ab32118807743318e000bb750fceccfb153dec0bac6df6e7d64.png",
    "items_count": 500,
    "created_at": "2026-06-24T09:41:15.166286Z",
    "updated_at": "2026-10-12T14:15:10.418807Z"
  },
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0816692",
      "kp_id": "258687",
      "tmdb_id": "157336",
      "tmdb_tv_id": null,
      "kinorium_id": "384511",
      "title_ru": "Интерстеллар",
      "title_en": "Interstellar",
      "year": 2014,
      "rating_kp": 8.7,
      "ord": 1
    },
    {
      "imdb_id": "tt0111161",
      "kp_id": "326",
      "tmdb_id": "278",
      "tmdb_tv_id": null,
      "kinorium_id": "101209",
      "title_ru": "Побег из Шоушенка",
      "title_en": "The Shawshank Redemption",
      "year": 1994,
      "rating_kp": 9.1,
      "ord": 2
    },
    {
      "imdb_id": "tt0120689",
      "kp_id": "435",
      "tmdb_id": "497",
      "tmdb_tv_id": null,
      "kinorium_id": "109273",
      "title_ru": "Зелёная миля",
      "title_en": "The Green Mile",
      "year": 1999,
      "rating_kp": 9.1,
      "ord": 3
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 500
}
```

### Filtered

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "country=ru" \
  --data-urlencode "sort=-rating_kp" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,year,rating_kp,ord" \
  "https://api.kinodata.space/v1.3/collections/top-movies"
```

Response `200`:

```json
{
  "collection": {
    "slug": "top-movies",
    "name_ru": "500 лучших фильмов",
    "name_en": "500 Best Movies",
    "description_ru": "Пятьсот лучших фильмов по оценкам зрителей Кинопоиска — классика и новые картины, которые зрители ценят выше всего.",
    "description_en": "The 500 best films as rated by Kinopoisk viewers — the classics and the newer films audiences rate highest.",
    "poster_url": "https://api.kinodata.space/uploads/56c18b27af130ab32118807743318e000bb750fceccfb153dec0bac6df6e7d64.png",
    "items_count": 500,
    "created_at": "2026-06-24T09:41:15.166286Z",
    "updated_at": "2026-10-12T14:15:10.418807Z"
  },
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt12073988",
      "kp_id": "1234939",
      "tmdb_id": "644612",
      "tmdb_tv_id": null,
      "kinorium_id": "2368311",
      "title_ru": "Счастье в конверте",
      "title_en": "Letters Of Happiness",
      "year": 2020,
      "rating_kp": 8.5,
      "ord": 185
    },
    {
      "imdb_id": "tt36683785",
      "kp_id": "7605663",
      "tmdb_id": "1424967",
      "tmdb_tv_id": null,
      "kinorium_id": "12222872",
      "title_ru": "Диодорова. Против течения",
      "title_en": "Diodorova. Against the Current",
      "year": 2025,
      "rating_kp": 8.5,
      "ord": 270
    },
    {
      "imdb_id": "tt38504885",
      "kp_id": "7525290",
      "tmdb_id": "1458240",
      "tmdb_tv_id": null,
      "kinorium_id": "12221529",
      "title_ru": "Двое в одной жизни, не считая собаки",
      "title_en": "Two People in One Life and a Dog",
      "year": 2025,
      "rating_kp": 8.4,
      "ord": 168
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": null
}
```

### No such collection

```bash
curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.3/collections/best-films"
```

Response `404`:

```json
{
  "error": {
    "code": "not_found",
    "message": "collection not found: best-films"
  }
}
```