Перейти до вмісту

API для плеєрів і скриптів

REST API з персональним ключем: позначки серій і фільмів, оцінки, списки. Готові плагіни для плеєрів на сторінці Інтеграції.

Свій плеєр через AI‑агента

  • Claude Code
  • Codex
  • Cursor
  1. Скопіюй завдання для агента:

    Завдання
    Зроби інтеграцію з GetShows за довідкою https://getshows.io/developers.md: коли я додивляюсь серію чи фільм, позначай їх переглянутими в GetShows, вхід через код з екрана. Мій плеєр: 
  2. Встав його агенту й допиши назву свого плеєра. Агент прочитає довідку і сам напише плагін.

  3. Запусти плагін і введи код з екрана на getshows.io/connect.

Початок

Адреса
https://getshows.io/api/v1
Ключ
Створи ключ у налаштуваннях, розділ «Інтеграції», і передавай цілим рядком у заголовку Authorization: Bearer <ключ>. Ключ видно лише раз.
Формат
JSON. Числа можна слати й рядками, а порожній рядок означає, що значення нема.
Тайтл
{ref} у шляху приймає TMDB id (1396, tmdb:1396) або IMDb id (imdb:tt0903747). Тайтлів, яких нема в каталозі GetShows, API не знає.
Відповідь
Успіх завжди 200. Запит, що змінює дані, каже в полі result, що саме сталося. Помилки мають свій формат.

Ключ дає повний доступ до твоїх позначок, оцінок і списків, тож засвічений ключ одразу відклич у налаштуваннях.

Перевірити ключ
curl https://getshows.io/api/v1/me \
  -H "Authorization: Bearer <ключ>"
Відповідь 200
{
  "username": "kino_fan",
  "name": "Олена",
  "profile_url": "https://getshows.io/u/kino_fan"
}

Підключення пристрою

Телевізор показує короткий код, людина вводить його на сайті, а пристрій сам забирає ключ. Обидва запити йдуть без ключа.

1. Код
POST /device/code з полем client: назва застосунку до 40 знаків без слова GetShows. Її людина побачить на сторінці підключення. Покажи на екрані user_code і verification_uri, а в QR-коді verification_uri_complete.
2. Сайт
Людина відкриває https://getshows.io/connect, вводить код і натискає «Підключити».
3. Ключ
Шли POST /device/token з device_code раз на interval секунд. Поки людина не підтвердила код, відповідь 400 authorization_pending. Ключ приходить лише раз.

Код діє expires_in секунд від створення, опитування строк не продовжує. Після access_denied, expired_token чи token_limit спроба завершена: почни з нового коду.

Запит коду
curl -X POST https://getshows.io/api/v1/device/code \
  -H "Content-Type: application/json" \
  -d '{"client": "Kodi"}'
Відповідь 200
{
  "device_code": "…",
  "user_code": "K7M-4QX",
  "verification_uri": "https://getshows.io/connect",
  "verification_uri_complete": "https://getshows.io/connect?code=K7M4QX",
  "expires_in": 600,
  "interval": 5
}
Ключ, 200
{
  "token": "12|gs_…",
  "username": "kino_fan"
}

Позначки

POST /scrobble

Позначає серію чи фільм переглянутими зараз. Повтор нічого не змінює, тож плеєр може слати запит скільки завгодно. Старі перегляди з датами переноси через імпорт.

media_type обов'язкове
episode або movie
tmdb_id одне з двох
для серії id серіалу, а не серії; коли передано обидва, шукаємо за tmdb_id
imdb_id одне з двох
tt0903747
season, episode для серії
номери сезону й серії

result: marked, already_watched

Запит
curl -X POST https://getshows.io/api/v1/scrobble \
  -H "Authorization: Bearer <ключ>" \
  -H "Content-Type: application/json" \
  -d '{"media_type": "episode", "tmdb_id": "1396",
       "season": "2", "episode": "5"}'
Відповідь 200
{
  "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"
  }
}

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

Позначає серію за номером. Відповідь як у /scrobble.

result: marked, already_watched

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

Знімає позначку з серії.

result: unmarked, not_watched

POST /series/{ref}/watch-next

Позначає наступну непереглянуту серію. Кожен виклик позначає ще одну, тож не повторюй його автоматично після помилки мережі.

result: marked, nothing_to_mark

POST /series/{ref}/watch-through

Без episode позначає весь сезон. З episode позначає все до цієї серії включно, разом із попередніми сезонами. Скільки серій позначено, каже count.

season обов'язкове
номер сезону
episode необов'язкове
номер серії

result: marked

Прогрес і трекер

GET /series/{ref}/progress

Поле next показує наступну серію до перегляду, upcoming найближчу, що ще не вийшла. status набуває значень untracked, watching, caught_up, awaiting_season, completed чи dropped.

Відповідь 200
{
  "title": {…},
  "progress": {
    "watched": 12,
    "aired": 62,
    "status": "watching",
    "next": {"season": 2, "episode": 6, …},
    "upcoming": null
  }
}

GET /tracker

Повертає серіали трекера в секціях watching, waiting, awaiting і dropped. Кожен серіал має title і progress, як у відповіді вище.

Оцінки

{type}: series або films.

PUT /{type}/{ref}/rating

Ставить оцінку. Перша оцінка серіалу, якого нема в трекері, як і на сайті позначає всі серії, що вже вийшли. Скільки серій позначено, каже auto_marked.

rating обов'язкове
ціле від 1 до 10

result: rated

Запит
curl -X PUT https://getshows.io/api/v1/series/1396/rating \
  -H "Authorization: Bearer <ключ>" \
  -H "Content-Type: application/json" \
  -d '{"rating": 9}'

DELETE /{type}/{ref}/rating

Прибирає оцінку.

result: unrated, not_rated

Списки

{list}: watch_later, seen, favorites або slug твого списку з GET /lists. {type}: series або films.

GET /lists

Повертає списки, які можна змінювати: системні, твої власні й спільні. Поле alias є лише в системних.

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

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

Додає тайтл у список. У watch_later тайтл, що ще не вийшов, лягає в «Очікую», як і кнопкою на сайті.

result: added, already_present

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

Прибирає тайтл зі списку. Серіал із позначеними серіями можна прибрати з seen лише з ?forget_tracking=1, і тоді позначки серій теж зітруться.

result: removed, not_present

Помилки

Помилка завжди приходить з HTTP-кодом і полем error: code для програми, message українською для людини.

Відповідь 404
{
  "error": {
    "code": "episode_not_found",
    "message": "Серіал є, а такої серії чи сезону нема."
  }
}
HTTPcodeКоли
400 authorization_pending, access_denied, expired_token, token_limit підключення пристрою: код ще не підтвердили, підключення скасували, код застарів або ключів уже максимум
401 unauthenticated ключа нема, він хибний чи відкликаний
403 insufficient_ability це ключ вебхука Plex з /integrations: він уміє лише позначати перегляди з Plex
404 title_not_found тайтла нема в каталозі
404 episode_not_found серіал є, а такої серії чи сезону нема
404 list_not_found списку нема або його не можна змінювати
409 ambiguous_title, ambiguous_episode знайшлося кілька збігів, нічого не змінено
409 already_seen, already_released, rated, not_rated, has_episode_watches, dropped стан тайтла не дозволяє дію, причина в message
422 not_aired серія ще не вийшла
422 unsupported_ref, validation_failed хибний id чи тіло запиту
429 rate_limited забагато запитів; скільки чекати, каже заголовок Retry-After

Обмеження

Запити
120 на хвилину на акаунт, хоч скільки в нього ключів. Понад ліміт відповідь 429 із заголовком Retry-After.
Ключі
До 10 на акаунт. Ключ діє, доки його не відкличеш.
Облік
Позначки й оцінки з API рахуються як зроблені на сайті: потрапляють в активність, досягнення й рейтинги спільноти з тими самими денними межами.

GetShows на твоєму пристрої

Нативного застосунку для Android та iPhone поки немає, він буде пізніше. Зараз можна встановити PWA: це сайт, який відкривається з власної іконки в окремому вікні. Для роботи потрібен інтернет.

iPhone та iPad
Відкрий сайт у Safari, натисни «Поширити» й обери «На початковий екран». Якщо є перемикач «Відкривати як вебзастосунок», увімкни його.
Safari на Mac
У меню «Файл» обери «Додати в Dock» і підтвердь додавання.
Chrome та Edge
У меню браузера знайди встановлення сторінки як застосунку. На комп’ютері в Chrome цей пункт розташовано в розділі «Трансляція, збереження й поширення», на Android шукай «Додати на головний екран» або «Встановити застосунок».

Назви пунктів залежать від мови й версії браузера. Якщо встановлення недоступне, відкрий сайт у свіжій версії Chrome або Safari.