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

Довідник Twitch Drops API

Безкоштовний JSON API з усіма активними кампаніями Twitch Drops і кампаніями з нагородами (оновлюються щохвилини), а також із глобальними значками чату Twitch. Звертайтеся до нього анонімно або з безкоштовним API-ключем: з ним ліміт вищий.

Базовий URLhttps://drops.sunkwi.com/api/twitch
Отримати безкоштовний API-ключВідкрити довідник

Спробувати

Анонімно: 1 запит раз на 5 хв для кожного маршруту. З ключем: 1 за хвилину.

GET
Завантаження попереднього перегляду…
Огляд

Маршрути

Кожен маршрут відповідає в JSON на запит GET, а браузери на будь-якому сайті можуть звертатися до API (CORS). Ні /drops, ні /rewards, ні /badges не потребують реєстрації; безкоштовний API-ключ підвищує ліміт на кожному з них.

Усі три маршрути відповідають однаково: список, час останнього отримання даних від Twitch (refreshedAt) і ваш ліміт запитів (rateLimit).

МаршрутОпис
GET /dropsКампанії Drops за іграми. Усі активні кампанії Drops, згруповані за іграми, у games: один елемент на гру, її кампанії в rewards.
GET /rewardsКампанії з нагородами. Усі активні кампанії з нагородами (події на всьому Twitch, значки для чату, нагороди партнерів), у campaigns.
GET /badgesГлобальні значки чату. Глобальні значки чату Twitch, по одному елементу на версію в badges, зі способом отримання, якщо він відомий.

Автентифікація

Для читання /drops, /rewards і /badges не потрібні ні акаунт, ні ключ. Анонімні виклики рахуються за IP-адресою: 1 запит раз на 5 хв для кожного маршруту.

Ключі безкоштовні: увійдіть через Discord, Twitch або GitHub, створіть ключ в особистому кабінеті й передавайте його в заголовку X-API-Key. За замовчуванням ключ підвищує ваш ліміт до 1 запит за хвилину (більше — на запит) і показує ваш трафік.

Заголовок запиту

ЗаголовокЗначенняОпис
X-API-Keyjdk_…Ваш API-ключ: необовʼязковий для будь-якого маршруту. Невідомий, відкликаний або вимкнений ключ ніколи не відхиляється: виклик вважається анонімним, про що повідомляє x-api-key-status: invalid.
Приклад запиту · curl
# Anonymouscurl https://drops.sunkwi.com/api/twitch/drops
# With an API key, showing the rate-limit headerscurl -i -H "x-api-key: $DROPS_API_KEY" https://drops.sunkwi.com/api/twitch/drops

Отримайте безкоштовний API-ключ

Ключ безкоштовний. Він підвищує ліміт з 1 запиту раз на 5 хв до 1 запит за хвилину для кожного маршруту, а в особистому кабінеті видно його трафік.

  1. Увійдіть через Discord, Twitch або GitHub: без пароля й без анкет.
  2. Відкрийте API-ключі в особистому кабінеті та створіть ключ із назвою вашого бота чи сайту.
  3. Скопіюйте ключ, коли його буде показано (лише один раз), і передавайте його в заголовку X-API-Key зі свого сервера.

Отримати кампанії Drops

GEThttps://drops.sunkwi.com/api/twitch/drops

Усі активні кампанії Drops, згруповані за іграми: один елемент games на гру, її кампанії в rewards, разом із часом останнього сканування Twitch і вашим лімітом запитів.

Тіло відповіді

ПолеТипОпис
gamesGame[]Активні кампанії в порядку останнього сканування. Порожній масив — коректна відповідь.
refreshedAtstring (ISO 8601) | nullЧас останнього успішного сканування Twitch, null до першого.
rateLimit{ limit, remaining, resetAt }Ваш ліміт на цьому маршруті після цього виклику, як його повідомляють заголовки ratelimit-*: limit запитів на вікно, remaining ще доступно і resetAt — момент, коли ліміт повністю відновиться (ISO 8601).

Game

Один елемент games.

ПолеТипОпис
gameIdstringID гри на Twitch.
gameDisplayNamestringНазва гри.
gameBoxArtURLstring (URL)Обкладинка гри, 120×160.
startAtstring (ISO 8601)Початок найранішої кампанії гри.
endAtstring (ISO 8601)Завершення найпізнішої кампанії гри.
rewardsDropCampaign[]Кампанії Drops цієї гри.
Поля DropCampaign, TimeBasedDrop і Benefit

DropCampaign

Кампанія Drops у rewards гри.

ПолеТипОпис
idstringID кампанії на Twitch.
name, descriptionstringНазва й опис від видавця.
owner{ id, name }Видавець, який проводить кампанію.
game{ id, displayName, slug }Гра кампанії.
statusstringСтатус на Twitch, ACTIVE для кампанії, що триває.
startAt, endAtstring (ISO 8601)Період проведення кампанії.
imageURLstring (URL)Зображення кампанії.
detailsURL, accountLinkURLstring (URL)Сторінка з подробицями та сторінка привʼязки акаунта у видавця.
allow{ isEnabled, channels? }Канали, яким дозволено видавати Drops, якщо isEnabled дорівнює true; інакше будь-який канал, що транслює гру. displayName може бути null або відсутнім.
timeBasedDropsTimeBasedDrop[]Drops, які отримують за перегляд.
eventBasedDropsunknown[]Drops, які отримують за події, передаються від Twitch як є.
firstSeenAtstring (ISO 8601) | nullКоли цей API вперше побачив кампанію. Кампанія, що повернулася до списку менш ніж за добу після зникнення, зберігає свою дату. null для кампаній, які API вже віддавав, коли з'явилося це поле.

TimeBasedDrop

Нагорода Drops за перегляд, у timeBasedDrops.

ПолеТипОпис
id, namestringID і назва нагороди на Twitch.
startAt, endAtstring (ISO 8601)Період, протягом якого можна отримати нагороду.
requiredMinutesWatchednumberСкільки хвилин треба дивитися.
requiredSubsnumberСкільки потрібно підписок.
repeat{ everyHours, times } | nullДодано цим API: як часто Drop можна отримати знову, з times (скільки разів) і everyHours (24: раз на день; null, якщо Twitch не повідомляє). requiredMinutesWatched тоді — час перегляду за один період. null для Drop, який отримують один раз.
preconditionDropsunknownDrops, які треба отримати спершу, передаються від Twitch як є.
benefitEdges{ benefit: Benefit, entitlementLimit }[]Що дає нагорода і скільки разів її можна отримати.

Benefit

Ігровий предмет у benefitEdges.

ПолеТипОпис
id, namestringID і назва предмета на Twitch.
imageAssetURLstring (URL)Зображення предмета.
createdAtstring (ISO 8601)Дата створення предмета на Twitch.
distributionTypestringЯк видається предмет: DIRECT_ENTITLEMENT для ігрового предмета, BADGE для значка в чаті.
entitlementLimitnumberСкільки разів можна отримати предмет.
isIosAvailablebooleanЧи можна отримати предмет на iOS.
game, ownerOrganization{ id, name }Гра й видавець предмета.

Коди відповіді

СтатусОпис
200Активні кампанії. Порожній список — коректна відповідь.
304Від надісланого ETag нічого не змінилося: залиште свою копію. Безкоштовно, не враховується у вашому ліміті.
429RATE_LIMITED: Зачекайте стільки секунд, скільки вказано в Retry-After.
429INVALID_API_KEY_RATE_LIMITED: Ключ не розпізнано, а анонімний ліміт вашої IP-адреси вичерпано: виправте ключ.
503SERVICE_UNAVAILABLE: Список ще не завантажено (одразу після перезапуску API): повторіть після Retry-After. Безкоштовно, не враховується у вашому ліміті.
Приклад запиту
curl https://drops.sunkwi.com/api/twitch/drops
Приклад відповіді · 200 OK
{  "games": [    {      "gameId": "460630",      "gameDisplayName": "Rainbow Six Siege",      "gameBoxArtURL": "https://static-cdn.jtvnw.net/ttv-boxart/460630-120x160.jpg",      "startAt": "2026-10-17T05:00:00Z",      "endAt": "2026-11-02T13:59:59.999Z",      "rewards": [        {          "id": "ef80b803-…",          "name": "R6S S2 2026 19",          "startAt": "2026-10-17T05:00:00Z",          "endAt": "2026-11-02T13:59:59.999Z",          "firstSeenAt": "2026-10-17T05:00:41.208Z",          "accountLinkURL": "https://drops-register.ubi.com",          "timeBasedDrops": [            {              "name": "Esports Pack",              "requiredMinutesWatched": 120,              "repeat": null,              "benefitEdges": [{ "benefit": { "name": "Esports Pack", … } }]            }          ],          …        }      ]    },    …  ],  "refreshedAt": "2026-10-24T21:14:01.936Z",  "rateLimit": { "limit": 1, "remaining": 0, "resetAt": "2026-10-24T21:15:12.000Z" }}

Отримати кампанії з нагородами

GEThttps://drops.sunkwi.com/api/twitch/rewards

Усі активні кампанії з нагородами (події на всьому Twitch, значки для чату, нагороди партнерів) у campaigns, разом із часом останнього сканування Twitch і вашим лімітом запитів.

Тіло відповіді

ПолеТипОпис
campaignsRewardCampaign[]Активні кампанії в порядку останнього сканування. Порожній масив — коректна відповідь.
refreshedAtstring (ISO 8601) | nullЧас останнього успішного сканування Twitch, null до першого.
rateLimit{ limit, remaining, resetAt }Ваш ліміт на цьому маршруті після цього виклику, як його повідомляють заголовки ratelimit-*: limit запитів на вікно, remaining ще доступно і resetAt — момент, коли ліміт повністю відновиться (ISO 8601).

RewardCampaign

Один елемент campaigns.

ПолеТипОпис
id, name, brandstringID, назва й бренд кампанії на Twitch.
statusstringСтатус на момент запиту, за датами: UPCOMING до початку (startsAt), ACTIVE до кінця (endsAt), потім EXPIRED.
summary, instructionsstringТексти, які показує Twitch.
startsAt, endsAtstring (ISO 8601)Період проведення кампанії.
image{ image1xURL }Зображення кампанії.
aboutURL, externalURLstring (URL)Сторінка довідки та зовнішня сторінка кампанії.
isSitewidebooleanЧи зараховується будь-який канал, а не лише канали однієї гри.
game{ id, displayName, slug }?Гра кампанії, якщо вона є.
rewardValueURLParamstringЗначення, яке Twitch додає до посилань для отримання нагород.
unlockRequirements{ minuteWatchedGoal, subsGoal }Скільки потрібно хвилин перегляду та підписок.
rewardGroupsRewardGroup[]?Нагороди, які отримують по одній групі за раз, кожна група має власну мету: нагорода на день — це група на день. Лише якщо Twitch їх надсилає.
rewardsReward[]Нагороди кампанії, включно з нагородами її груп, кожна по одному разу.
firstSeenAtstring (ISO 8601) | nullКоли цей API вперше побачив кампанію. Кампанія, що повернулася до списку менш ніж за добу після зникнення, зберігає свою дату. null для кампаній, які API вже віддавав, коли з'явилося це поле.
Поля нагород

RewardGroup

Група нагород кампанії з нагородами, які отримують разом.

ПолеТипОпис
idstringID групи на Twitch.
unlockRequirements{ minuteWatchedGoal, subsGoal, turboSubsGoal?, eventTriggerGoal? }Що потрібно для групи. Twitch додає сюди цілі Turbo та подій.
repeat{ everyHours, times } | nullЯк часто групу можна отримати знову, як repeat у Drop: minuteWatchedGoal тоді — час перегляду за один період. null для групи, яку отримують один раз.
categories{ id, displayName, slug }[]Категорії, канали яких в ефірі зараховуються, будь-яка з них; порожньо, якщо Twitch не називає жодної.
rewardsReward[]Нагороди групи, які також перелічено в rewards кампанії.

Reward

Нагорода кампанії з нагородами.

ПолеТипОпис
id, namestringID і назва нагороди на Twitch.
bannerImage, thumbnailImage{ image1xURL }Зображення нагороди.
earnableUntilstring (ISO 8601)Останній момент, коли можна отримати нагороду.
redemptionInstructions, redemptionURLstringЯк і де активувати нагороду.

Коди відповіді

СтатусОпис
200Активні кампанії. Порожній список — коректна відповідь.
304Від надісланого ETag нічого не змінилося: залиште свою копію. Безкоштовно, не враховується у вашому ліміті.
429RATE_LIMITED: Зачекайте стільки секунд, скільки вказано в Retry-After.
429INVALID_API_KEY_RATE_LIMITED: Ключ не розпізнано, а анонімний ліміт вашої IP-адреси вичерпано: виправте ключ.
503SERVICE_UNAVAILABLE: Список ще не завантажено (одразу після перезапуску API): повторіть після Retry-After. Безкоштовно, не враховується у вашому ліміті.
Приклад запиту
curl https://drops.sunkwi.com/api/twitch/rewards
Приклад відповіді · 200 OK
{  "campaigns": [    {      "id": "19f00aac-…",      "name": "First Partners Collection",      "brand": "Pokemon",      "status": "ACTIVE",      "startsAt": "2026-08-24T17:00:00Z",      "endsAt": "2026-11-01T07:00:00Z",      "firstSeenAt": null,      "isSitewide": true,      "unlockRequirements": { "minuteWatchedGoal": 20, "subsGoal": 0 },      "rewards": [{ "name": "Great Ball", "earnableUntil": "2026-11-01T07:00:00Z", … }]    },    {      "id": "b7669f9e-…",      "name": "GTAVI Launch Celebration",      "brand": "Rockstar Games",      "status": "UPCOMING",      "startsAt": "2026-11-18T11:00:00Z",      "endsAt": "2026-12-01T07:59:59.999Z",      "unlockRequirements": { "minuteWatchedGoal": 60, "subsGoal": 0 },      "rewardGroups": [        {          "id": "6a0e…",          "unlockRequirements": { "minuteWatchedGoal": 60, "subsGoal": 0 },          "repeat": { "everyHours": 24, "times": 6 },          "categories": [{ "id": "1867279146", "displayName": "Grand Theft Auto VI", "slug": "grand-theft-auto-vi" }],          "rewards": [{ "name": "GTA DVD Chest", … }]        },        …      ],      …    },    …  ],  "refreshedAt": "2026-10-24T21:14:01.936Z",  "rateLimit": { "limit": 1, "remaining": 0, "resetAt": "2026-10-24T21:15:12.000Z" }}

Отримати значки чату

GEThttps://drops.sunkwi.com/api/twitch/badges

Глобальні значки чату Twitch у badges, по одному елементу на версію, у кожного спосіб отримання, якщо він відомий цьому API (requirement), разом із часом останнього отримання значків Twitch і вашим лімітом запитів.

Тіло відповіді

ПолеТипОпис
badgesBadge[]Глобальні значки, по одному елементу на версію. Порожній масив — коректна відповідь.
refreshedAtstring (ISO 8601) | nullЧас останнього успішного отримання значків Twitch (раз на 5 хвилин), null до першого.
rateLimit{ limit, remaining, resetAt }Ваш ліміт на цьому маршруті після цього виклику, як його повідомляють заголовки ratelimit-*: limit запитів на вікно, remaining ще доступно і resetAt — момент, коли ліміт повністю відновиться (ISO 8601).

Badge

Один елемент badges: одна версія глобального значка чату в тому вигляді, у якому Twitch наводить його зараз.

ПолеТипОпис
setId, versionIdstringНабір значків і його версія: разом вони позначають один значок (sub-gifter і 5).
title, descriptionstringЙого назва й опис від Twitch, англійською.
imageUrl1x, imageUrl2x, imageUrl4xstring (URL)Його зображення розміром 18, 36 і 72 пікселі.
clickAction, clickUrlstring | nullЩо робить Twitch після натискання на значок, і посилання; null, якщо Twitch його не надає.
firstSeenAtstring (ISO 8601) | nullКоли цей API вперше побачив значок. Якщо значок повернувся більш ніж через 7 днів після того, як Twitch його прибрав, він отримує нову дату; якщо раніше — зберігає попередню. null для значків, які вже були в списку під час його першого отримання.
requirementBadgeRequirement | nullЯк його отримати; null, якщо цей API не знає.
Поля BadgeRequirement

BadgeRequirement

Як отримати значок: з кампанії Drops, яка його видає (DROPS), або з власного опису Twitch для значка підписника чи глядача (TWITCH_DESCRIPTION).

ПолеТипОпис
source'DROPS' | 'TWITCH_DESCRIPTION'DROPS або TWITCH_DESCRIPTION.
watchTimeOnlybooleantrue саме тоді, коли достатньо дивитися: кампанія DROPS, яка вимагає час перегляду (requiredMinutes більше 0) і не вимагає підписки (requiredSubs дорівнює 0).
requiredMinutes, requiredSubsnumberСкільки потрібно хвилин перегляду та підписок чи подарованих підписок.
gameId, gameNamestringГра: її ID на Twitch (null, якщо невідомий) і назва.
channels, channelCountstring[] (≤ 5), numberПерші 5 каналів, які його видають (логіни), і їхня загальна кількість; 0: будь-який канал, що транслює гру.
startAt, endAtstring (ISO 8601) | nullПеріод проведення кампанії; null для TWITCH_DESCRIPTION. Завершена кампанія залишається в списку.
campaignId, campaignNamestring | nullКампанія Drops; null для TWITCH_DESCRIPTION.
repeat{ everyHours, times } | nullЛише DROPS: час перегляду потрібен знову в кожному періоді, а requiredMinutes — за один період, з times і everyHours (20 хв на день 3 дні: times 3, everyHours 24); інакше null.
categories{ id, name }[] (≤ 50)Лише DROPS: категорії, канали яких в ефірі зараховуються, будь-яка з них (id і name, не більше 50); gameId і gameName — перша з них. Інакше порожньо.
collection{ chestSize, completeAll } | nullЛише DROPS: значок — одна з нагород колекції події, тобто кампанії. chestSize: він випадає зі скрині з такою кількістю нагород, по одній за скриню, ніколи на вибір (null: видається напряму). completeAll: видається за проходження всієї колекції, включно з підписками. Інакше null.
evolvesFrom{ setId, versionId } | nullЛише DROPS: значок, який треба вибрати в чаті до перегляду, за його setId і versionId у цьому списку: еволюція покемона вимагає попередньої стадії (Pikachu: Pichu). Інакше null, або якщо він невідомий.

Коди відповіді

СтатусОпис
200Глобальні значки. Порожній список — коректна відповідь.
304Від надісланого ETag нічого не змінилося: залиште свою копію. Безкоштовно, не враховується у вашому ліміті.
429RATE_LIMITED: Зачекайте стільки секунд, скільки вказано в Retry-After.
429INVALID_API_KEY_RATE_LIMITED: Ключ не розпізнано, а анонімний ліміт вашої IP-адреси вичерпано: виправте ключ.
503SERVICE_UNAVAILABLE: Список ще не завантажено (одразу після перезапуску API): повторіть після Retry-After. Безкоштовно, не враховується у вашому ліміті.
Приклад запиту
curl https://drops.sunkwi.com/api/twitch/badges
Завантаження попереднього перегляду…

Ліміти запитів

Кожен маршрут має власний лічильник: виклик /drops ніколи не витрачає ліміт /rewards чи /badges. Кампанії змінюються раз на хвилину, а значки раз на 5 хвилин, тож частіші запити нічого нового не дадуть.

КлієнтЛіміт на маршрутОблік за
Анонімно1 запит раз на 5 хвIP-адреса
З API-ключем1 запит за хвилину за замовчуванням, більше — на запитAPI-ключ

Заголовки відповіді

Заголовки, які API читає й надсилає.

ЗаголовокНапрямокОпис
x-last-updated-atresponseЧас останнього успішного отримання даних від Twitch: сканування для /drops і /rewards, значків для /badges.
x-refresh-interval-secondsresponseІнтервал у секундах між двома запитами до Twitch: частіші запити повертають ті самі дані (60 для /drops і /rewards, 300 для /badges).
ratelimit-limitresponseСкільки запитів дозволено у вікні для цього маршруту.
ratelimit-remainingresponseСкільки запитів залишилося в поточному вікні.
ratelimit-resetresponseЧерез скільки секунд знову можна надіслати запит.
ratelimit-policyresponseПолітика у форматі <ліміт>;w=<вікно в секундах>.
retry-afterresponseСкільки секунд зачекати перед повтором, у відповіді 429 або 503.
x-api-keyrequestВаш API-ключ: необовʼязковий для будь-якого маршруту.
x-api-key-statusresponseinvalid, якщо надісланий ключ невідомий, відкликаний або вимкнений: виклик зараховано як анонімний, у межах ліміту вашої IP-адреси.
etagresponseМітка цієї відповіді. Надішліть її назад у If-None-Match: поки дані не змінилися, відповіддю буде 304, що не враховується у вашому ліміті.
if-none-matchrequestETag вашої останньої відповіді, необовʼязково: незмінений список відповідає 304 Not Modified, безкоштовно.
Другий анонімний виклик протягом 5 хв
HTTP/1.1 429 Too Many Requestscontent-type: application/json; charset=utf-8retry-after: 214ratelimit-limit: 1ratelimit-remaining: 0ratelimit-reset: 214ratelimit-policy: 1;w=300
{ "code": "RATE_LIMITED" }

Помилки

Помилки повертають тіло JSON зі стабільним кодом: { "code": "RATE_LIMITED" }. Коди ніколи не змінюються: спирайтеся на code, а не на текст повідомлення.

СтатусКодОпис
429RATE_LIMITEDЗабагато запитів до цього маршруту: зачекайте стільки секунд, скільки вказано в Retry-After.
429INVALID_API_KEY_RATE_LIMITEDЗабагато запитів, а в заголовку X-API-Key невідомий, відкликаний або вимкнений ключ: виклик зараховано як анонімний. Виправте ключ або зачекайте стільки секунд, скільки вказано в Retry-After.
503SERVICE_UNAVAILABLEСписок ще не завантажено (одразу після перезапуску API). Нічого не витрачається: повторіть запит через стільки секунд, скільки вказано в Retry-After.
404NOT_FOUNDТакого маршруту не існує.
500INTERNAL_SERVER_ERRORЗбій на сервері: повторіть спробу пізніше.
Приклад помилки
HTTP/1.1 404 Not Foundcontent-type: application/json; charset=utf-8
{ "code": "NOT_FOUND" }

Від сайту до API

Усі сторінки цього сайту читають ці самі маршрути. Тут показано, де у відповідях міститься те, що показує сторінка.

СторінкаМаршрутДе у відповіді
Drops/drops/dropsgames: один елемент на гру, її кампанії в rewards. Вигляд «Сітка» будується за startAt і endAt кожної кампанії.
Сторінка гри/drops/<game>/dropsОдин елемент games, знайдений за gameId. Кожна кампанія — це games[i].rewards[j]; її нагороди — це benefitEdges із timeBasedDrops, з requiredMinutesWatched.
Нагороди/rewards/rewardscampaigns: один елемент на кампанію з нагородами, її нагороди в rewards, а умови — в unlockRequirements.
Сторінка кампанії з нагородами/rewards/<campaign>/rewardsОдин елемент campaigns, знайдений за id; його нагороди — в rewards.
Значки/badges/badgesbadges: усі елементи, спочатку ті, що мають requirement, зі способом отримання. Вигляд «Сітка» будується за requirement.startAt і requirement.endAt кожного значка.
Сторінка значка/badges/<badge>/badgesОдин елемент badges, знайдений за setId і versionId; «Як отримати» — це його requirement.