# GetShows API: guide for AI agents

GetShows (https://getshows.io) is a Ukrainian catalog of films and series with a personal tracker. The REST API at `https://getshows.io/api/v1` lets a player plugin or a script act for one person: mark episodes and films as watched, rate titles and manage lists. Use it to build a scrobbler: when playback finishes in the player, the title is marked in the person's GetShows tracker.

The API only knows titles that exist in the GetShows catalog. Human-readable docs in Ukrainian: https://getshows.io/developers.

## Choose how to sign in

- **Plugin on a device** (TV app, media center, anything with a remote or a GUI): use the device flow below. The person types a short code on the website; the plugin never asks them to copy a long key.
- **Script or server** (cron job, webhook receiver, CLI): the person creates a personal key in their settings, section «Інтеграції» (https://getshows.io/profile#integrations), and pastes it into your config.

Either way every request carries the header `Authorization: Bearer <token>`. The token looks like `12|gs_…`: store and send the whole string, including the part before `|`. A token gives full access to the person's marks, ratings and lists and does not expire until the person revokes it.

## Device flow

These two requests go without a token.

1. `POST https://getshows.io/api/v1/device/code` with JSON `{"client": "<your app name>"}`. `client` is the name the person will see on the confirmation page and the name of the issued key: 2 to 40 characters, letters (any alphabet), digits, spaces and `. _ + ( ) -`, starting with a letter or digit, and it must not contain "getshows". Invalid names get 422 `validation_failed`.
2. Show `user_code` (format `XXX-XXX`) and `verification_uri` on screen; put `verification_uri_complete` into a QR code, it opens https://getshows.io/connect with the code filled in.
3. Poll `POST https://getshows.io/api/v1/device/token` with `{"device_code": "…"}` every `interval` seconds (now 5).

```
curl -X POST https://getshows.io/api/v1/device/code \
  -H "Content-Type: application/json" \
  -d '{"client": "Kodi"}'
```

```json
{
  "device_code": "…64 chars…",
  "user_code": "K7M-4QX",
  "verification_uri": "https://getshows.io/connect",
  "verification_uri_complete": "https://getshows.io/connect?code=K7M4QX",
  "expires_in": 600,
  "interval": 5
}
```

Poll outcomes (errors are HTTP 400 with `error.code`):

| Outcome | What to do |
|---|---|
| 200 `{"token": "12\|gs_…", "username": "kino_fan"}` | Save the token in the plugin settings. It is delivered only once. |
| `authorization_pending` | The person has not confirmed yet. Keep polling every `interval` seconds. |
| `access_denied` | The person pressed «Скасувати». Stop polling; start again only when the person asks. |
| `expired_token` | The code expired (600 s from creation; polling does not extend it) or was already used. Request a new code. |
| `token_limit` | The account already has 10 keys. Ask the person to revoke one in «Інтеграції», then request a new code. |

If the response with the token is lost (network error), the key already exists on the server: request a new code, and tell the person they can revoke the orphan key in «Інтеграції».

## Identifying titles

- `{ref}` in a path is a TMDB id (`1396` or `tmdb:1396`) or an IMDb id (`imdb:tt0903747`). Other prefixes give 422 `unsupported_ref`.
- For an episode, the id is the id of the **series**, plus season and episode numbers. Do not send the TMDB or IMDb id of the episode itself.
- Prefer TMDB ids: when both `tmdb_id` and `imdb_id` are sent, the API uses `tmdb_id`.
- `{type}` is `series` or `films`.
- 404 `title_not_found` means the title is not in the GetShows catalog; 409 `ambiguous_title` / `ambiguous_episode` means several matches and nothing was changed. Do not retry either.

## Scrobble recipe

Send `POST /scrobble` when the player reports that playback finished. If the player only reports progress, a common threshold is 85-90% watched; the API itself does not check progress, it records the fact "watched now".

```
curl -X POST https://getshows.io/api/v1/scrobble \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"media_type": "episode", "tmdb_id": "1396", "season": "2", "episode": "5"}'
```

Body: `media_type` (`episode` or `movie`, required), `tmdb_id` or `imdb_id` (one is required), `season` and `episode` (required for an episode). Numbers may be sent as strings; an empty string means "no value", so template-based webhooks can send empty fields.

```json
{
  "result": "marked",
  "title": {"type": "series", "tmdb_id": 1396, "name": "Пуститися берега", "url": "https://getshows.io/series/1396"},
  "episode": {"season": 2, "episode": 5, "name": "Бій товару", "air_date": "2009-04-05"}
}
```

Both `marked` and `already_watched` are success. Scrobble is idempotent: a repeat changes nothing, so it is safe to retry. An episode with a future air date gives 422 `not_aired`. Past views with their dates are not for the API: the person moves them with the site's import (https://getshows.io/import).

## Endpoints

All paths are relative to `https://getshows.io/api/v1` and need the token. Successful responses are 200 JSON. Requests that change state return `result` saying what happened.

### GET /me

Check the token. Response: `{"username": "kino_fan", "name": "Олена", "profile_url": "https://getshows.io/u/kino_fan"}`.

### POST /scrobble

See the recipe above. `result`: `marked`, `already_watched`.

### PUT /series/{ref}/episodes/{season}/{episode}/watched

Mark one episode. Same response as `/scrobble`. `result`: `marked`, `already_watched`.

### DELETE /series/{ref}/episodes/{season}/{episode}/watched

Unmark one episode. `result`: `unmarked`, `not_watched`.

### POST /series/{ref}/watch-next

Mark the next unwatched episode. **Not idempotent**: every call marks one more episode, so never retry it automatically after a network error. `result`: `marked`, `nothing_to_mark`.

### POST /series/{ref}/watch-through

Body `{"season": 2}` marks the whole season; `{"season": 2, "episode": 5}` marks everything up to and including that episode, previous seasons too. `count` says how many episodes were marked. `result`: `marked`.

### GET /series/{ref}/progress

```json
{
  "title": {"type": "series", "tmdb_id": 1396, "name": "…", "url": "…"},
  "progress": {
    "watched": 12,
    "aired": 62,
    "status": "watching",
    "next": {"season": 2, "episode": 6, "name": "…", "air_date": "…"},
    "upcoming": null
  }
}
```

`next` is the next episode to watch, `upcoming` the nearest episode not aired yet. `status` is one of `untracked`, `watching`, `caught_up`, `awaiting_season`, `completed`, `dropped`.

### GET /tracker

Series in the tracker grouped into `watching`, `waiting`, `awaiting` and `dropped`; each item has `title` and `progress` as above.

### PUT /{type}/{ref}/rating

Body `{"rating": 9}`, an integer from 1 to 10. The first rating of a series that is not in the tracker also marks every aired episode, as on the site; `auto_marked` says how many. Response: `{"result": "rated", "rating": 9, "auto_marked": 0, "title": {…}}`.

### DELETE /{type}/{ref}/rating

`result`: `unrated`, `not_rated`.

### GET /lists

Lists the person can edit: system lists, their own and shared ones. `alias` is set only for system lists.

```json
[{"slug": "weekend", "name": "На вихідні", "type": "custom", "alias": null, "count": 14, "url": "https://getshows.io/lists/weekend"}]
```

### PUT /lists/{list}/items/{type}/{ref}

Add a title. `{list}` is `watch_later`, `seen`, `favorites` or the `slug` of a list from `GET /lists`. In `watch_later` a title that is not released yet goes to «Очікую», as with the button on the site. `result`: `added`, `already_present`.

### DELETE /lists/{list}/items/{type}/{ref}

Remove a title. A series with watched episodes leaves `seen` only with `?forget_tracking=1`, and then its episode marks are erased too. `result`: `removed`, `not_present`.

## Errors

Every error is an HTTP status plus `{"error": {"code": "…", "message": "…"}}`. Branch on `code`; `message` is in Ukrainian and meant for the person.

| HTTP | code | When |
|---|---|---|
| 400 | `authorization_pending`, `access_denied`, `expired_token`, `token_limit` | device flow, see above |
| 401 | `unauthenticated` | no token, a malformed token or a revoked one |
| 403 | `insufficient_ability` | a Plex webhook key (issued on /integrations): it only marks what Plex reports, use a key from settings or the device flow |
| 404 | `title_not_found` | the title is not in the catalog |
| 404 | `episode_not_found` | the series exists, the season or episode does not |
| 404 | `list_not_found` | no such list, or the person cannot edit it |
| 409 | `ambiguous_title`, `ambiguous_episode` | several matches, nothing changed |
| 409 | `already_seen`, `already_released`, `rated`, `not_rated`, `has_episode_watches`, `dropped` | the title's state does not allow the action; the reason is in `message` |
| 422 | `not_aired` | the episode has not aired yet |
| 422 | `unsupported_ref`, `validation_failed` | bad id or body; validation errors name the fields |
| 429 | `rate_limited` | too many requests; wait `Retry-After` seconds |

## Retries and limits

- 120 requests per minute per account, however many keys it has. Over the limit: 429 with `Retry-After`; wait that long before the next request.
- 5xx and network errors: retry with exponential backoff, at most 3 attempts, and only idempotent requests (everything except `watch-next`).
- 401: first check that the `Authorization` header is sent and the token is stored whole (`id|gs_…`). Only then treat it as revoked and ask the person to connect again.
- 404 and 409 are final for that title: log and move on.
- Up to 10 keys per account.

## Security

- Never log the token, never put it in a URL, never hard-code it in the plugin source.
- Store it where the platform keeps secrets or plugin settings.
- The person revokes keys in «Інтеграції» (https://getshows.io/profile#integrations); after that the API answers 401.

## Verify your integration

1. `GET /me` returns 200 with `username`.
2. `GET /series/1396/progress` returns 200: reading works.
3. Test writes only on a title the person has really watched, or on a separate test account: marks and ratings go to the person's activity feed and achievements.
4. After a scrobble the episode shows as watched in the tracker (https://getshows.io/tracker).
