# Shared titles

> Titles two people both worked on, and what each of them did there.

> 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/persons/{type}/{id}/with/{type2}/{id2}`

The two people’s catalogs can differ: `/persons/kp/37859/with/imdb/nm0634240` is Leonardo DiCaprio and Christopher Nolan. Each title carries both people’s roles: `credits_first` for the first person in the path, `credits_second` for the second.

Roles are set for each person separately. `role_first=actor&role_second=director` for DiCaprio and Nolan gives exactly *Inception*: Cobb and the director. `role` is a role both share: `role=actor` gives the titles they acted in together, `role=self` the broadcasts and ceremonies where both were guests. To drop broadcasts and archive footage, exclude those roles: of DiCaprio and Nolan’s 20 shared titles, `role.not=self,archive` leaves only *Inception*.

The list runs on the catalog engine: all the [filters and sorting](https://kinodata.space/en/docs/filters.md) work, as do presets, the title search `q` and `fields`. Without `sort`, it runs from newest to oldest; `order=asc` reverses that. The “English only” example below uses this to list the films Keanu Reeves and Laurence Fishburne made together, by IMDb rating, with both people’s roles. The catalog gives the same titles without roles but with a cursor: `/titles?person=kp:37859&person=imdb:nm0634240`.

If both people in the path are the same person, the response is `400` with a hint to open the filmography.

## Path parameters

- `type` (string, required) — The catalog the ID of the first person comes from: IMDb, Kinopoisk, TMDB or Kinorium.
  Values: `imdb`, `kp`, `tmdb`, `kinorium`.
- `id` (string, required) — The ID of the first person in that catalog. IMDb IDs are `nm` followed by digits (`nm0634240`); the others are digits (`41477`).
- `type2` (string, required) — The catalog the ID of the second person comes from: IMDb, Kinopoisk, TMDB or Kinorium.
  Values: `imdb`, `kp`, `tmdb`, `kinorium`.
- `id2` (string, required) — The ID of the second person in that catalog. IMDb IDs are `nm` followed by digits (`nm0634240`); the others are digits (`41477`).

## Query parameters

- `role_first` (csv) — The first person’s role. Several, comma-separated, mean any of them. `role_first.not` drops the titles where the person had only such roles.
  Values: `director`, `actor`, `self`, `archive`, `writer`, `producer`, `cinematographer`, `composer`, `sound`, `art`, `editor`, `voice_director`, `voice`, `author`, `translator`, `producer_ussr`, `crew`.
  Example: `role_first=actor`.
- `role_second` (csv) — The second person’s role. Several, comma-separated, mean any of them. `role_second.not` drops the titles where the person had only such roles.
  Values: `director`, `actor`, `self`, `archive`, `writer`, `producer`, `cinematographer`, `composer`, `sound`, `art`, `editor`, `voice_director`, `voice`, `author`, `translator`, `producer_ussr`, `crew`.
  Example: `role_second=director`.
- `role` (csv) — A role both of them had. Several, comma-separated, mean any of them. `role.not` drops the titles where either of them had only such roles.
  Values: `director`, `actor`, `self`, `archive`, `writer`, `producer`, `cinematographer`, `composer`, `sound`, `art`, `editor`, `voice_director`, `voice`, `author`, `translator`, `producer_ussr`, `crew`.
  Example: `role=actor`.
- `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: `sort=-year`.
- `order` (enum) — The direction of the default order: `order=asc` runs from oldest to newest. When `sort` is set, its sign decides the direction.
  Values: `asc`, `desc`.
  Default: `desc`. Example: `order=asc`.
- `fields` (csv) — Which item fields to return, as in the [catalog](https://kinodata.space/en/docs/titles.md), plus `credits_first` and `credits_second`. IDs always come back.
  Example: `fields=title,year,credits_first,credits_second`.
- `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 1000.
  Default: 1000. Example: `limit=20`.
- `offset` (integer) — How many titles to skip, a whole number from 0.
  Default: 0.

## Response fields

- `items` (array) — The shared titles: the same card as in the [catalog](https://kinodata.space/en/docs/titles.md), with both people’s roles.
  - `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`.
  - `credits_first`, `credits_second` (array) — The first and the second person’s roles on this title, with the same fields as a role in the [filmography](https://kinodata.space/en/docs/persons/filmography.md).
    - `role` (enum) — The role. Labels are in `/enums`, set `credit_roles`.
    - `character_ru`, `character_en` (string | null) — The character, for actors and dubbing, without the source’s notes, as in the [cast](https://kinodata.space/en/docs/titles/cast.md). For `self`, what the person appears as: “Guest”, «гость».
    - `job_ru`, `job_en` (string | null) — The crew job: “Executive Producer”, «Исполнительный продюсер».
    - `ord` (integer | null) — Billing order: for actors, the order in the credits; for the crew, within their department. `null` when the place is unknown: the role comes from the person’s filmography, not the title’s credits.
    - `sources` (array) — Which catalogs confirmed the credit: `kp`, `tmdb`, `kinorium`, always in this order.
    - `uncredited` (boolean) — `true` means the title’s credits don’t name the person: the source marked the part “uncredited” («в титрах не указан»).
    - `disputed` (boolean) — `true` means only TMDB has the credit, and the title’s Kinopoisk or Kinorium cast doesn’t list the person. The [title’s cast](https://kinodata.space/en/docs/titles/cast.md) leaves such credits out; in a list of work, hide them by checking `disputed`.
- `total` (integer | null) — How many shared titles match the request. `null` with a `q` search.
- `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` | The path names the same person twice; an unknown role, filter, `sort` key or `fields` name; `order` other than `asc` or `desc`; a parameter of another endpoint (such as `relation` or `season`); `limit` below 1 or `offset` below 0; a repeated parameter; `cursor`, since the list pages with `offset`. |
| 400 | `invalid_request` | The catalog is not `imdb`, `kp`, `tmdb` or `kinorium` (people have no `tmdb_tv`); the ID doesn’t match the catalog’s format: for IMDb, `nm` followed by digits. |
| 404 | `not_found` | No person found for one of the IDs. |
| 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=movie" \
  --data-urlencode "votes_imdb.gte=100000" \
  --data-urlencode "sort=-rating_imdb" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,rating_imdb,credits_first,credits_second" \
  --data-urlencode "lang=en" \
  "https://api.kinodata.space/v1.3/persons/imdb/nm0000206/with/imdb/nm0000401"
```

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0133093",
      "kp_id": "301",
      "tmdb_id": "603",
      "tmdb_tv_id": null,
      "kinorium_id": "116780",
      "title_en": "The Matrix",
      "rating_imdb": 8.7,
      "credits_first": [
        {
          "role": "actor",
          "character_en": "Neo",
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ],
      "credits_second": [
        {
          "role": "actor",
          "character_en": "Morpheus",
          "job_en": null,
          "ord": 1,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ]
    },
    {
      "imdb_id": "tt10366206",
      "kp_id": "1267348",
      "tmdb_id": "603692",
      "tmdb_tv_id": null,
      "kinorium_id": "2055679",
      "title_en": "John Wick: Chapter 4",
      "rating_imdb": 7.6,
      "credits_first": [
        {
          "role": "actor",
          "character_en": "John Wick",
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        },
        {
          "role": "producer",
          "character_en": null,
          "job_en": "Executive Producer",
          "ord": 3,
          "sources": [
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ],
      "credits_second": [
        {
          "role": "actor",
          "character_en": "Bowery King",
          "job_en": null,
          "ord": 4,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ]
    },
    {
      "imdb_id": "tt6146586",
      "kp_id": "1009536",
      "tmdb_id": "458156",
      "tmdb_tv_id": null,
      "kinorium_id": "1606958",
      "title_en": "John Wick: Chapter 3 – Parabellum",
      "rating_imdb": 7.4,
      "credits_first": [
        {
          "role": "actor",
          "character_en": "John Wick",
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ],
      "credits_second": [
        {
          "role": "actor",
          "character_en": "Bowery King",
          "job_en": null,
          "ord": 3,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ]
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 7
}
```

### Actor and director

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "role_first=actor" \
  --data-urlencode "role_second=director" \
  --data-urlencode "fields=title,year,credits_first,credits_second" \
  "https://api.kinodata.space/v1.3/persons/kp/37859/with/imdb/nm0634240"
```

Response `200`:

```json
{
  "has_more": false,
  "items": [
    {
      "imdb_id": "tt1375666",
      "kp_id": "447301",
      "tmdb_id": "27205",
      "tmdb_tv_id": null,
      "kinorium_id": "472809",
      "title_ru": "Начало",
      "title_en": "Inception",
      "year": 2010,
      "credits_first": [
        {
          "role": "actor",
          "character_ru": null,
          "character_en": "Dom Cobb",
          "job_ru": null,
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ],
      "credits_second": [
        {
          "role": "director",
          "character_ru": null,
          "character_en": null,
          "job_ru": null,
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        },
        {
          "role": "writer",
          "character_ru": null,
          "character_en": null,
          "job_ru": "Сценарист",
          "job_en": "Writer",
          "ord": 13,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        },
        {
          "role": "producer",
          "character_ru": null,
          "character_en": null,
          "job_ru": "Продюсер",
          "job_en": "Producer",
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ]
    }
  ],
  "limit": 1000,
  "offset": 0,
  "total": 1
}
```

### Both languages

```bash
curl -G -H "X-API-Key: $KINODATA_KEY" \
  --data-urlencode "kind=movie" \
  --data-urlencode "votes_imdb.gte=100000" \
  --data-urlencode "sort=-rating_imdb" \
  --data-urlencode "limit=3" \
  --data-urlencode "fields=title,rating_imdb,credits_first,credits_second" \
  "https://api.kinodata.space/v1.3/persons/imdb/nm0000206/with/imdb/nm0000401"
```

Response `200`:

```json
{
  "has_more": true,
  "items": [
    {
      "imdb_id": "tt0133093",
      "kp_id": "301",
      "tmdb_id": "603",
      "tmdb_tv_id": null,
      "kinorium_id": "116780",
      "title_ru": "Матрица",
      "title_en": "The Matrix",
      "rating_imdb": 8.7,
      "credits_first": [
        {
          "role": "actor",
          "character_ru": null,
          "character_en": "Neo",
          "job_ru": null,
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ],
      "credits_second": [
        {
          "role": "actor",
          "character_ru": null,
          "character_en": "Morpheus",
          "job_ru": null,
          "job_en": null,
          "ord": 1,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ]
    },
    {
      "imdb_id": "tt10366206",
      "kp_id": "1267348",
      "tmdb_id": "603692",
      "tmdb_tv_id": null,
      "kinorium_id": "2055679",
      "title_ru": "Джон Уик 4",
      "title_en": "John Wick: Chapter 4",
      "rating_imdb": 7.6,
      "credits_first": [
        {
          "role": "actor",
          "character_ru": null,
          "character_en": "John Wick",
          "job_ru": null,
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        },
        {
          "role": "producer",
          "character_ru": null,
          "character_en": null,
          "job_ru": "Исполнительный продюсер",
          "job_en": "Executive Producer",
          "ord": 3,
          "sources": [
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ],
      "credits_second": [
        {
          "role": "actor",
          "character_ru": null,
          "character_en": "Bowery King",
          "job_ru": null,
          "job_en": null,
          "ord": 4,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ]
    },
    {
      "imdb_id": "tt6146586",
      "kp_id": "1009536",
      "tmdb_id": "458156",
      "tmdb_tv_id": null,
      "kinorium_id": "1606958",
      "title_ru": "Джон Уик 3",
      "title_en": "John Wick: Chapter 3 – Parabellum",
      "rating_imdb": 7.4,
      "credits_first": [
        {
          "role": "actor",
          "character_ru": null,
          "character_en": "John Wick",
          "job_ru": null,
          "job_en": null,
          "ord": 0,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ],
      "credits_second": [
        {
          "role": "actor",
          "character_ru": null,
          "character_en": "Bowery King",
          "job_ru": null,
          "job_en": null,
          "ord": 3,
          "sources": [
            "kp",
            "tmdb",
            "kinorium"
          ],
          "disputed": false,
          "uncredited": false
        }
      ]
    }
  ],
  "limit": 3,
  "offset": 0,
  "total": 7
}
```

### One person twice

```bash
curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.3/persons/kp/41477/with/imdb/nm0634240"
```

Response `400`:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "the path names the same person twice; a collaboration needs two people",
    "field": "id2",
    "hint": "for one person's work use /persons/:type/:id/filmography"
  }
}
```