# Collections

> The list of collections: Kinopoisk tops refreshed every day, and editorial picks.

> 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`

Collections come in two kinds:

- **Kinopoisk tops**: `top-movies`, `top-series`, `popular-titles`, `weekly-trending-titles`, `daily-trending-titles`. They mirror Kinopoisk’s lists and refresh every day; `updated_at` tells you when;
- **editorial picks**: short themed lists such as `light-movies`, `single-location-movies`, `psychological-horror-movies`, `disaster-movies`, `true-story-movies`.

`q` searches collections by name and description.

A collection’s titles are at [`/collections/{slug}`](https://kinodata.space/en/docs/collections/items.md).

## Query parameters

- `q` (string) — Search by the collection’s name and description.
  Example: `q=фильмы`.
- `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 collections to return, a whole number from 1 to 50.
  Default: 50.
- `offset` (integer) — How many collections to skip, a whole number from 0.
  Default: 0.

## Response fields

- `items` (array) — Collections.
  - `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.
- `total`, `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` | `limit` is not a whole number from 1, or `offset` is below 0; a parameter the list doesn’t understand (such as `fields`), with the allowed ones in the response. |
| 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 "lang=en" \
  "https://api.kinodata.space/v1.3/collections"
```

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "slug": "top-series",
      "name_en": "250 Best TV Series",
      "description_en": "The 250 best TV series as rated by Kinopoisk viewers.",
      "poster_url": "https://api.kinodata.space/uploads/843590034d274b077b035816bb0e7d8e2f15d88755bfe970e45ea0a2372fb365.png",
      "items_count": 250,
      "created_at": "2026-06-24T09:41:15.177186Z",
      "updated_at": "2026-10-12T14:18:59.690163Z"
    },
    {
      "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"
    },
    {
      "slug": "popular-titles",
      "name_en": "Popular on Kinopoisk",
      "description_en": "The thousand films and TV series currently most popular with Kinopoisk viewers.",
      "poster_url": "https://api.kinodata.space/uploads/34686cdc02b2a6e8c2cb387020c4497f5f16d246c3380550e899669f79ad7b97.png",
      "items_count": 1000,
      "created_at": "2026-06-23T19:02:47.25172Z",
      "updated_at": "2026-10-12T14:11:35.633811Z"
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 10
}
```

### Both languages

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "limit=3" \
  "https://api.kinodata.space/v1.3/collections"
```

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "slug": "top-series",
      "name_ru": "250 лучших сериалов",
      "name_en": "250 Best TV Series",
      "description_ru": "Двести пятьдесят лучших сериалов по оценкам зрителей Кинопоиска.",
      "description_en": "The 250 best TV series as rated by Kinopoisk viewers.",
      "poster_url": "https://api.kinodata.space/uploads/843590034d274b077b035816bb0e7d8e2f15d88755bfe970e45ea0a2372fb365.png",
      "items_count": 250,
      "created_at": "2026-06-24T09:41:15.177186Z",
      "updated_at": "2026-10-12T14:18:59.690163Z"
    },
    {
      "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"
    },
    {
      "slug": "popular-titles",
      "name_ru": "Популярное на Кинопоиске",
      "name_en": "Popular on Kinopoisk",
      "description_ru": "Тысяча фильмов и сериалов, которые сейчас популярнее всего у зрителей Кинопоиска.",
      "description_en": "The thousand films and TV series currently most popular with Kinopoisk viewers.",
      "poster_url": "https://api.kinodata.space/uploads/34686cdc02b2a6e8c2cb387020c4497f5f16d246c3380550e899669f79ad7b97.png",
      "items_count": 1000,
      "created_at": "2026-06-23T19:02:47.25172Z",
      "updated_at": "2026-10-12T14:11:35.633811Z"
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 10
}
```