Перейти к содержимому
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.