# Texts

> Facts, questions with answers and quotes about a title.

> 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/titles/{type}/{id}/texts`

Without parameters the texts come split into sections: facts, questions and answers, quotes. `counts` is how many texts of each kind the title has, with any `kind`: label your tabs with it.

Texts are in Russian only for now: the `_en` fields are `null`. With `lang=en` the text comes back empty, which shows there is no translation yet.

On *The Matrix*, one fact in four gives the plot away. To show facts next to the overview, drop the spoilers: `spoilers=false`.

## Path parameters

- `type` (string, required) — The catalog the ID comes from: IMDb, Kinopoisk, TMDB (movie or series) or Kinorium.
  Values: `imdb`, `kp`, `tmdb`, `tmdb_tv`, `kinorium`.
- `id` (string, required) — The ID in that catalog. IMDb IDs are `tt` followed by digits (`tt1375666`); the others are digits (`447301`).

## Query parameters

- `kind` (csv) — Kinds of text, comma-separated. Labels are in `/enums`, set `text_kinds`.
  Values: `fact`, `faq`, `quote`.
  Default: all three. Example: `kind=quote`.
- `spoilers` (boolean) — `false` drops facts that give the plot away.
  Default: with spoilers. Example: `spoilers=false`.
- `fact_kind` (csv) — Fact subtypes, comma-separated. Labels are in `/enums`, set `fact_kinds`.
  Values: `general`, `trivia`, `blooper`.
  Example: `fact_kind=blooper`.
- `group` (enum) — Split the list into sections. `none` gives a flat list. How sections work is in [Lists and pagination](https://kinodata.space/en/docs/lists.md#sections).
  Values: `kind`, `none`.
  Default: `kind`.
- `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 items to return, a whole number from 1. With sections, per section, up to 50. In a flat list, up to 1000. Above the cap isn’t an error: the API lowers it and shows the value in `limit`.
  Default: 10 per section, 1000 in a flat list. Example: `limit=20`.
- `offset` (integer) — How many items to skip, a whole number from 0. Only in a flat list: with sections it returns `400`.
  Default: 0.

## Response fields

- `counts` (object) — How many facts, questions and quotes the title has: `fact`, `faq`, `quote`.
- `items` (array) — The texts. Fields depend on the kind, `kind`. With sections, sections with their own `total` and labels.
  - `kind` (enum) — Kind: `fact`, `faq` or `quote`.
  - `text_ru`, `text_en` (string | null) — The fact or the quote.
  - `fact_kind` (enum) — Fact subtype: `general`, `trivia` or `blooper`.
  - `is_spoiler` (boolean) — The fact gives the plot away. `false` means the source didn’t mark it so.
  - `ord` (integer) — The fact’s order at the source.
  - `question_ru`, `question_en`, `answer_ru`, `answer_en` (string | null) — The question and the answer.
  - `links` (array) — Who the answer mentions: `text` as written, `type`, and IDs with a name, as for a person in the cast.
  - `original`, `original_lang` (string | null) — The quote in the original language, and that language as ISO 639-1.
  - `author_ru`, `author_en` (string | null) — Who says the quote: the actor.
  - `author_role_ru`, `author_role_en` (string | null) — The character the quote belongs to.
- `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` | An unknown `kind`, `fact_kind` or `group`; `offset` together with sections; a parameter this list doesn’t understand (such as `sort` or `fields`); the response lists the allowed ones. |
| 404 | `not_found` | No title found for this ID. |
| 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 "kind=quote" \
  --data-urlencode "limit=2" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/titles/kp/301/texts"
```

Response `200`:

```json
{
  "counts": {
    "fact": 100,
    "faq": 14,
    "quote": 5
  },
  "has_more": true,
  "items": [
    {
      "author_en": null,
      "author_role_en": null,
      "kind": "quote",
      "original": "There is no spoon.",
      "original_lang": "en",
      "text_en": null
    },
    {
      "author_en": null,
      "author_role_en": null,
      "kind": "quote",
      "original": "I know kung fu.",
      "original_lang": "en",
      "text_en": null
    }
  ],
  "limit": 2,
  "offset": 0,
  "total": 5
}
```

### Quotes

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=quote" \
  --data-urlencode "limit=2" \
  "https://api.kinodata.space/v1.3/titles/kp/301/texts"
```

Response `200`:

```json
{
  "counts": {
    "fact": 100,
    "faq": 14,
    "quote": 5
  },
  "has_more": true,
  "items": [
    {
      "author_ru": "Роуэн Уитт",
      "author_en": null,
      "author_role_ru": "мальчик с ложкой",
      "author_role_en": null,
      "kind": "quote",
      "original": "There is no spoon.",
      "original_lang": "en",
      "text_ru": "Ложки не существует.",
      "text_en": null
    },
    {
      "author_ru": "Киану Ривз",
      "author_en": null,
      "author_role_ru": "Нео",
      "author_role_en": null,
      "kind": "quote",
      "original": "I know kung fu.",
      "original_lang": "en",
      "text_ru": "Я знаю кунг-фу.",
      "text_en": null
    }
  ],
  "limit": 2,
  "offset": 0,
  "total": 5
}
```

### Facts

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=fact" \
  --data-urlencode "limit=2" \
  "https://api.kinodata.space/v1.3/titles/kp/301/texts"
```

Response `200`:

```json
{
  "counts": {
    "fact": 100,
    "faq": 14,
    "quote": 5
  },
  "has_more": true,
  "items": [
    {
      "fact_kind": "blooper",
      "is_spoiler": false,
      "kind": "fact",
      "ord": 64,
      "text_ru": "В эпизоде, где Тринити и Нео в поисках Морфиуса оказываются на крыше, один из пилотов вертолета трансформируется в агента Джонса. При этом левый висок Джонса приходится на затылок пилота. Однако после выстрела Тринити именно в этот висок, пулевое отверстие у пилота, покинутого «программой» агента, почему-то оказывается во лбу.",
      "text_en": null
    },
    {
      "fact_kind": "blooper",
      "is_spoiler": false,
      "kind": "fact",
      "ord": 65,
      "text_ru": "В сцене, когда Нео впервые встречается с Морфиусом, герой Лоренса Фишбёрна здоровается с Избранным. Морфиус протягивает правую руку, при этом левая рука у него за спиной. Далее сразу же следует вставка с другого ракурса, где левая рука уже почему-то опущена к полу. В следующем кадре левая рука Морфиуса снова за спиной.",
      "text_en": null
    }
  ],
  "limit": 2,
  "offset": 0,
  "total": 100
}
```

### Q&A

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=faq" \
  --data-urlencode "limit=1" \
  "https://api.kinodata.space/v1.3/titles/kp/301/texts"
```

Response `200`:

```json
{
  "counts": {
    "fact": 100,
    "faq": 14,
    "quote": 5
  },
  "has_more": true,
  "items": [
    {
      "answer_ru": "Фильм следует за Томасом Андерсоном, который начинает подозревать, что привычная реальность — лишь тщательно сконструированная иллюзия. Встреча с Морфеусом и его командой втягивает героя в конфликт с системой контроля и её агентами, заставляя выбирать между комфортной ложью и рискованной правдой.",
      "answer_en": null,
      "kind": "faq",
      "links": [],
      "question_ru": "О чём фильм «Матрица» без спойлеров концовки?",
      "question_en": null
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 14
}
```