Přejít na obsah
Twitch Drops API

Reference Twitch Drops API

Bezplatné JSON API se všemi aktivními kampaněmi Twitch Drops a kampaněmi s odměnami, obnovované každou minutu, a s globálními odznaky do chatu na Twitchi. Volej ho anonymně, nebo s bezplatným klíčem API pro vyšší limit.

Základní URLhttps://drops.sunkwi.com/api/twitch
Získej bezplatný klíč APIPřečíst referenci

Vyzkoušej si to

Anonymně: 1 požadavek za 5 min na endpoint. S klíčem: 1 za minutu.

GET
Načítání náhledu…
Procházet

Endpointy

Každý endpoint odpovídá na požadavek GET ve formátu JSON a API mohou volat prohlížeče z jakéhokoli webu (CORS). Ani /drops, ani /rewards, ani /badges nevyžadují registraci; bezplatný klíč API zvyšuje limit na každém z nich.

Všechny tři endpointy odpovídají stejně: seznam, čas posledního načtení z Twitche (refreshedAt) a tvůj limit požadavků (rateLimit).

EndpointPopis
GET /dropsKampaně Drops podle her. Všechny aktivní kampaně Drops seskupené podle her, v games: jedna položka na hru, její kampaně v rewards.
GET /rewardsKampaně s odměnami. Všechny aktivní kampaně s odměnami (události na celém Twitchi, odznaky do chatu, odměny partnerů), v campaigns.
GET /badgesGlobální odznaky do chatu. Globální odznaky do chatu na Twitchi, jedna položka na verzi v badges, se způsobem získání, pokud je známý.

Ověřování

Čtení /drops, /rewards a /badges nevyžaduje účet ani klíč. Anonymní volání se počítají podle IP adresy: 1 požadavek za 5 min na každém endpointu.

Klíče jsou zdarma: přihlas se přes Discord, Twitch nebo GitHub, vytvoř klíč na nástěnce a posílej ho v hlavičce X-API-Key. Klíč ve výchozím stavu zvýší tvůj limit na 1 požadavek za minutu, na požádání i víc, a ukazuje tvůj provoz.

Hlavička požadavku

HlavičkaHodnotaPopis
X-API-Keyjdk_…Tvůj klíč API: volitelný na každém endpointu. Neznámý, zneplatněný nebo vypnutý klíč se nikdy neodmítne: volání se počítá jako anonymní a oznámí to x-api-key-status: invalid.
Příklad požadavku · 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

Získej bezplatný klíč API

Klíč je zdarma. Zvýší tvůj limit z 1 požadavku za 5 min na 1 požadavek za minutu na každém endpointu a nástěnka ukazuje jeho provoz.

  1. Přihlas se přes Discord, Twitch nebo GitHub: žádné heslo, žádný formulář.
  2. Na nástěnce otevři Klíče API a vytvoř klíč pojmenovaný podle svého bota nebo webu.
  3. Zkopíruj klíč, až se zobrazí (jen jednou), a posílej ho v hlavičce X-API-Key ze svého serveru.

Získat kampaně Drops

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

Všechny aktivní kampaně Drops seskupené podle her: jedna položka games na hru, její kampaně v rewards, spolu s časem poslední kontroly Twitche a tvým limitem požadavků.

Tělo odpovědi

PoleTypPopis
gamesGame[]Aktivní kampaně v pořadí z poslední kontroly. Prázdné pole je platná odpověď.
refreshedAtstring (ISO 8601) | nullČas poslední úspěšné kontroly Twitche, před první kontrolou null.
rateLimit{ limit, remaining, resetAt }Tvůj limit na tomto endpointu po tomto volání, tak jak ho uvádějí hlavičky ratelimit-*: limit požadavků na okno, remaining ještě povolených a resetAt, kdy bude celý limit zase k dispozici (ISO 8601).

Game

Jedna položka games.

PoleTypPopis
gameIdstringID hry na Twitchi.
gameDisplayNamestringNázev hry.
gameBoxArtURLstring (URL)Obal hry, 120×160.
startAtstring (ISO 8601)Začátek nejdřívější kampaně hry.
endAtstring (ISO 8601)Konec nejpozdější kampaně hry.
rewardsDropCampaign[]Kampaně Drops dané hry.
Pole DropCampaign, TimeBasedDrop a Benefit

DropCampaign

Kampaň Drops, v rewards hry.

PoleTypPopis
idstringID kampaně na Twitchi.
name, descriptionstringNázev a popis od vydavatele.
owner{ id, name }Vydavatel, který kampaň pořádá.
game{ id, displayName, slug }Hra kampaně.
statusstringStav na Twitchi, ACTIVE u probíhající kampaně.
startAt, endAtstring (ISO 8601)Doba trvání kampaně.
imageURLstring (URL)Obrázek kampaně.
detailsURL, accountLinkURLstring (URL)Stránka s podrobnostmi a stránka pro propojení účtu u vydavatele.
allow{ isEnabled, channels? }Kanály, které smějí rozdávat Drops, když je isEnabled true; jinak jakýkoli kanál, který hru streamuje. displayName může být null nebo chybět.
timeBasedDropsTimeBasedDrop[]Drops získávané sledováním.
eventBasedDropsunknown[]Drops získávané za události, předané z Twitche beze změny.
firstSeenAtstring (ISO 8601) | nullKdy toto API kampaň poprvé vidělo. Kampaň, která se vrátí méně než den poté, co ze seznamu zmizela, si datum ponechá. null u kampaní, které API poskytovalo už ve chvíli, kdy toto pole přibylo.

TimeBasedDrop

Odměna Drops získávaná sledováním, v timeBasedDrops.

PoleTypPopis
id, namestringID odměny na Twitchi a její název.
startAt, endAtstring (ISO 8601)Období, kdy lze odměnu získat.
requiredMinutesWatchednumberPotřebné minuty sledování.
requiredSubsnumberPotřebné odběry.
repeat{ everyHours, times } | nullPřidává toto API: jak často se Drop získává znovu, s times (kolikrát) a everyHours (24: jednou denně; null, když to Twitch neuvádí). requiredMinutesWatched je pak doba sledování za jedno období. null pro Drop získaný jen jednou.
preconditionDropsunknownDrops, které je třeba získat předem, předané z Twitche beze změny.
benefitEdges{ benefit: Benefit, entitlementLimit }[]Co odměna dává a kolikrát ji lze vyzvednout.

Benefit

Herní předmět, v benefitEdges.

PoleTypPopis
id, namestringID předmětu na Twitchi a jeho název.
imageAssetURLstring (URL)Obrázek předmětu.
createdAtstring (ISO 8601)Datum vytvoření předmětu na Twitchi.
distributionTypestringJak se předmět doručuje: DIRECT_ENTITLEMENT u herního předmětu, BADGE u odznaku do chatu.
entitlementLimitnumberKolikrát lze předmět vyzvednout.
isIosAvailablebooleanZda lze předmět vyzvednout na iOS.
game, ownerOrganization{ id, name }Hra a vydavatel předmětu.

Kódy odpovědí

StavPopis
200Aktivní kampaně. Prázdný seznam je platná odpověď.
304Od odeslaného ETag se nic nezměnilo: ponech si svou kopii. Zdarma, nepočítá se do tvého limitu.
429RATE_LIMITED: Počkej tolik sekund, kolik udává Retry-After.
429INVALID_API_KEY_RATE_LIMITED: Klíč nebyl rozpoznán a anonymní limit tvé IP adresy je vyčerpaný: oprav klíč.
503SERVICE_UNAVAILABLE: Seznam ještě není načtený (hned po restartu API): zkus to znovu po Retry-After. Zdarma, nepočítá se do tvého limitu.
Příklad požadavku
curl https://drops.sunkwi.com/api/twitch/drops
Příklad odpovědi · 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" }}

Získat kampaně s odměnami

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

Všechny aktivní kampaně s odměnami (události na celém Twitchi, odznaky do chatu, odměny partnerů) v campaigns, spolu s časem poslední kontroly Twitche a tvým limitem požadavků.

Tělo odpovědi

PoleTypPopis
campaignsRewardCampaign[]Aktivní kampaně v pořadí z poslední kontroly. Prázdné pole je platná odpověď.
refreshedAtstring (ISO 8601) | nullČas poslední úspěšné kontroly Twitche, před první kontrolou null.
rateLimit{ limit, remaining, resetAt }Tvůj limit na tomto endpointu po tomto volání, tak jak ho uvádějí hlavičky ratelimit-*: limit požadavků na okno, remaining ještě povolených a resetAt, kdy bude celý limit zase k dispozici (ISO 8601).

RewardCampaign

Jedna položka campaigns.

PoleTypPopis
id, name, brandstringID kampaně na Twitchi, její název a značka.
statusstringStav v okamžiku požadavku, určený podle dat: UPCOMING před startsAt, ACTIVE do endsAt, poté EXPIRED.
summary, instructionsstringTexty, které zobrazuje Twitch.
startsAt, endsAtstring (ISO 8601)Doba trvání kampaně.
image{ image1xURL }Obrázek kampaně.
aboutURL, externalURLstring (URL)Stránka nápovědy a externí stránka kampaně.
isSitewidebooleanZda se počítá každý kanál, nejen kanály jedné hry.
game{ id, displayName, slug }?Hra kampaně, pokud nějakou má.
rewardValueURLParamstringHodnota, kterou Twitch přidává do odkazů pro uplatnění.
unlockRequirements{ minuteWatchedGoal, subsGoal }Potřebné minuty sledování a odběry.
rewardGroupsRewardGroup[]?Odměny získávané po skupinách, každá skupina s vlastním cílem: odměna denně znamená skupinu denně. Jen když je Twitch posílá.
rewardsReward[]Odměny kampaně včetně odměn jejích skupin, každá jen jednou.
firstSeenAtstring (ISO 8601) | nullKdy toto API kampaň poprvé vidělo. Kampaň, která se vrátí méně než den poté, co ze seznamu zmizela, si datum ponechá. null u kampaní, které API poskytovalo už ve chvíli, kdy toto pole přibylo.
Pole odměn

RewardGroup

Skupina odměn kampaně s odměnami, které se získávají společně.

PoleTypPopis
idstringID skupiny na Twitchi.
unlockRequirements{ minuteWatchedGoal, subsGoal, turboSubsGoal?, eventTriggerGoal? }Co skupina vyžaduje. Twitch sem přidává cíle Turbo a cíle událostí.
repeat{ everyHours, times } | nullJak často se skupina získává znovu, stejně jako repeat u Dropu: minuteWatchedGoal je pak doba sledování za jedno období. null pro skupinu získanou jen jednou.
categories{ id, displayName, slug }[]Kategorie, jejichž živé kanály se počítají, kterákoli z nich; prázdné, když Twitch žádnou neuvádí.
rewardsReward[]Odměny skupiny, uvedené také v rewards kampaně.

Reward

Odměna kampaně s odměnami.

PoleTypPopis
id, namestringID odměny na Twitchi a její název.
bannerImage, thumbnailImage{ image1xURL }Obrázky odměny.
earnableUntilstring (ISO 8601)Poslední okamžik, kdy lze odměnu získat.
redemptionInstructions, redemptionURLstringJak a kde odměnu uplatnit.

Kódy odpovědí

StavPopis
200Aktivní kampaně. Prázdný seznam je platná odpověď.
304Od odeslaného ETag se nic nezměnilo: ponech si svou kopii. Zdarma, nepočítá se do tvého limitu.
429RATE_LIMITED: Počkej tolik sekund, kolik udává Retry-After.
429INVALID_API_KEY_RATE_LIMITED: Klíč nebyl rozpoznán a anonymní limit tvé IP adresy je vyčerpaný: oprav klíč.
503SERVICE_UNAVAILABLE: Seznam ještě není načtený (hned po restartu API): zkus to znovu po Retry-After. Zdarma, nepočítá se do tvého limitu.
Příklad požadavku
curl https://drops.sunkwi.com/api/twitch/rewards
Příklad odpovědi · 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" }}

Získat odznaky do chatu

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

Globální odznaky do chatu na Twitchi v badges, jedna položka na verzi, u každé způsob získání, pokud ho toto API zná (requirement), spolu s časem posledního načtení odznaků z Twitche a tvým limitem požadavků.

Tělo odpovědi

PoleTypPopis
badgesBadge[]Globální odznaky, jedna položka na verzi. Prázdné pole je platná odpověď.
refreshedAtstring (ISO 8601) | nullČas posledního úspěšného načtení odznaků z Twitche (každých 5 minut), před prvním načtením null.
rateLimit{ limit, remaining, resetAt }Tvůj limit na tomto endpointu po tomto volání, tak jak ho uvádějí hlavičky ratelimit-*: limit požadavků na okno, remaining ještě povolených a resetAt, kdy bude celý limit zase k dispozici (ISO 8601).

Badge

Jedna položka badges: jedna verze globálního odznaku do chatu, tak jak ji Twitch teď uvádí.

PoleTypPopis
setId, versionIdstringSada odznaků a její verze: dohromady určují jeden odznak (sub-gifter a 5).
title, descriptionstringJeho název a popis od Twitche, anglicky.
imageUrl1x, imageUrl2x, imageUrl4xstring (URL)Jeho obrázek v 18, 36 a 72 pixelech.
clickAction, clickUrlstring | nullCo Twitch udělá po kliknutí na odznak, a odkaz; null, když ho Twitch nedává.
firstSeenAtstring (ISO 8601) | nullKdy toto API odznak poprvé vidělo. Odznak, který se vrátí víc než 7 dní poté, co ho Twitch odebral, dostane nové datum; vrátí-li se dřív, ponechá si původní. null u odznaků, které tu byly už při jeho prvním načtení.
requirementBadgeRequirement | nullJak ho získat; null, když to toto API neví.
Pole BadgeRequirement

BadgeRequirement

Jak získat odznak: z kampaně Drops, která ho dává (DROPS), nebo z vlastního popisu Twitche u odznaku za odběr nebo sledování (TWITCH_DESCRIPTION).

PoleTypPopis
source'DROPS' | 'TWITCH_DESCRIPTION'DROPS nebo TWITCH_DESCRIPTION.
watchTimeOnlybooleantrue právě tehdy, když stačí sledovat: kampaň DROPS, která vyžaduje dobu sledování (requiredMinutes nad 0) a žádný odběr (requiredSubs 0).
requiredMinutes, requiredSubsnumberPotřebné minuty sledování a odběry nebo darované odběry.
gameId, gameNamestringHra: její ID na Twitchi (null, když není známé) a její název.
channels, channelCountstring[] (≤ 5), numberPrvních 5 kanálů, které ho dávají (loginy), a kolik jich je celkem; 0: jakýkoli kanál, který hru streamuje.
startAt, endAtstring (ISO 8601) | nullDoba trvání kampaně; null u TWITCH_DESCRIPTION. Skončená kampaň v seznamu zůstává.
campaignId, campaignNamestring | nullKampaň Drops; null u TWITCH_DESCRIPTION.
repeat{ everyHours, times } | nullJen DROPS: doba sledování je potřeba znovu v každém období, requiredMinutes platí pro jedno období, s times a everyHours (20 min denně po 3 dny: times 3, everyHours 24); jinak null.
categories{ id, name }[] (≤ 50)Jen DROPS: kategorie, jejichž živé kanály se počítají, kterákoli z nich (id a name, nejvýš 50); gameId a gameName jsou ta první. Jinak prázdné.
collection{ chestSize, completeAll } | nullJen DROPS: odznak je jednou z odměn kolekce k události, tedy kampaně. chestSize: padá z truhly s tolika odměnami, jedna na truhlu, nikdy podle výběru (null: dává se přímo). completeAll: dává se za dokončení celé kolekce, včetně odběrů. Jinak null.
evolvesFrom{ setId, versionId } | nullJen DROPS: odznak, který je třeba mít v chatu nasazený před sledováním, podle jeho setId a versionId v tomto seznamu: vývoj Pokémona vyžaduje předchozí stadium (Pikachu: Pichu). Jinak null, nebo když není znám.

Kódy odpovědí

StavPopis
200Globální odznaky. Prázdný seznam je platná odpověď.
304Od odeslaného ETag se nic nezměnilo: ponech si svou kopii. Zdarma, nepočítá se do tvého limitu.
429RATE_LIMITED: Počkej tolik sekund, kolik udává Retry-After.
429INVALID_API_KEY_RATE_LIMITED: Klíč nebyl rozpoznán a anonymní limit tvé IP adresy je vyčerpaný: oprav klíč.
503SERVICE_UNAVAILABLE: Seznam ještě není načtený (hned po restartu API): zkus to znovu po Retry-After. Zdarma, nepočítá se do tvého limitu.
Příklad požadavku
curl https://drops.sunkwi.com/api/twitch/badges
Načítání náhledu…

Limity požadavků

Každý endpoint má vlastní počítadlo: volání /drops nikdy nečerpá limit /rewards ani /badges. Kampaně se mění jednou za minutu a odznaky každých 5 minut, takže častější dotazování nic nového nepřinese.

VolajícíLimit na endpointPočítáno podle
Anonymně1 požadavek za 5 minIP adresa
S klíčem APIVe výchozím stavu 1 požadavek za minutu, na požádání vícKlíč API

Hlavičky odpovědi

Hlavičky, které API čte a posílá.

HlavičkaSměrPopis
x-last-updated-atresponseČas posledního úspěšného načtení z Twitche: kontroly pro /drops a /rewards, odznaků pro /badges.
x-refresh-interval-secondsresponsePočet sekund mezi dvěma načteními z Twitche: častější dotazy vrátí stejná data (60 pro /drops a /rewards, 300 pro /badges).
ratelimit-limitresponsePočet požadavků povolených v okně pro tento endpoint.
ratelimit-remainingresponsePočet požadavků, které v aktuálním okně zbývají.
ratelimit-resetresponsePočet sekund, než bude požadavek znovu povolen.
ratelimit-policyresponsePravidlo ve tvaru <limit>;w=<okno v sekundách>.
retry-afterresponsePočet sekund, které je třeba počkat před dalším pokusem, u odpovědi 429 nebo 503.
x-api-keyrequestTvůj klíč API: volitelný na každém endpointu.
x-api-key-statusresponseinvalid, když je odeslaný klíč neznámý, zneplatněný nebo vypnutý: volání se započítalo jako anonymní, do limitu tvé IP adresy.
etagresponseZnačka této odpovědi. Pošli ji zpět v If-None-Match: dokud se data nezmění, odpověď je 304 a nepočítá se do tvého limitu.
if-none-matchrequestETag tvé poslední odpovědi, volitelný: nezměněný seznam odpoví 304 Not Modified, zdarma.
Druhé anonymní volání během 5 min
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" }

Chyby

Chyby vracejí tělo JSON se stálým kódem: { "code": "RATE_LIMITED" }. Kódy se nikdy nemění: spoléhej na code, ne na text zprávy.

StavKódPopis
429RATE_LIMITEDPříliš mnoho požadavků na tomto endpointu: počkej tolik sekund, kolik udává Retry-After.
429INVALID_API_KEY_RATE_LIMITEDPříliš mnoho požadavků a hlavička X-API-Key obsahuje neznámý, zneplatněný nebo vypnutý klíč: volání se započítalo jako anonymní. Oprav klíč, nebo počkej tolik sekund, kolik udává Retry-After.
503SERVICE_UNAVAILABLESeznam ještě není načtený (hned po restartu API). Nic se nečerpá: zkus to znovu po tolika sekundách, kolik udává Retry-After.
404NOT_FOUNDEndpoint neexistuje.
500INTERNAL_SERVER_ERRORChyba serveru: zkus to později.
Příklad chyby
HTTP/1.1 404 Not Foundcontent-type: application/json; charset=utf-8
{ "code": "NOT_FOUND" }

Od webu k API

Každá stránka tohoto webu čte tytéž endpointy. Tady najdeš, kde v odpovědích leží to, co stránka zobrazuje.

StránkaEndpointKde v odpovědi
Drops/drops/dropsgames: jedna položka na hru, její kampaně v rewards. Zobrazení v mřížce kreslí startAt a endAt každé kampaně.
Stránka hry/drops/<game>/dropsJedna položka games, spárovaná podle gameId. Každá kampaň je games[i].rewards[j]; její odměny jsou benefitEdges z timeBasedDrops, s requiredMinutesWatched.
Odměny/rewards/rewardscampaigns: jedna položka na kampaň s odměnami, její odměny v rewards a její podmínky v unlockRequirements.
Stránka kampaně s odměnami/rewards/<campaign>/rewardsJedna položka campaigns, spárovaná podle id; její odměny jsou v rewards.
Odznaky/badges/badgesbadges: všechny položky, napřed ty s requirement, se způsobem získání. Zobrazení v mřížce kreslí requirement.startAt a requirement.endAt každého odznaku.
Stránka odznaku/badges/<badge>/badgesJedna položka badges, spárovaná podle setId a versionId; „Jak získat“ je její requirement.