Naar de inhoud
Twitch Drops API

Referentie van de Twitch Drops API

Een gratis JSON-API met elke actieve Twitch Drops- en beloningscampagne, elke minuut ververst, en de globale chatbadges van Twitch. Roep hem anoniem aan, of met een gratis API-sleutel voor een hogere limiet.

Basis-URLhttps://drops.sunkwi.com/api/twitch
Gratis API-sleutel aanvragenLees de referentie

Uitproberen

Anoniem: 1 verzoek per 5 minuten per route. Met een sleutel: 1 per minuut.

GET
Voorbeeld laden…
Bladeren

Routes

Elke route antwoordt met JSON op een GET-verzoek, en browsers van elke site kunnen de API aanroepen (CORS). Voor /drops, /rewards en /badges hoef je je niet te registreren; een gratis API-sleutel verhoogt de limiet op elk ervan.

De drie routes antwoorden op dezelfde manier: de lijst, het tijdstip waarop Twitch het laatst is uitgelezen (refreshedAt) en je verzoeklimiet (rateLimit).

RouteBeschrijving
GET /dropsDrops-campagnes per game. Elke actieve Drops-campagne, gegroepeerd per game, in games: één item per game, met de campagnes in rewards.
GET /rewardsBeloningscampagnes. Elke actieve beloningscampagne (evenementen op heel Twitch, chatbadges, partnerbeloningen), in campaigns.
GET /badgesGlobale chatbadges. De globale chatbadges van Twitch, één item per versie in badges, met hoe je ze krijgt als dat bekend is.

Authenticatie

Voor /drops, /rewards en /badges heb je geen account en geen sleutel nodig. Anonieme aanroepen worden per IP-adres geteld: 1 verzoek per 5 minuten op elke route.

Sleutels zijn gratis: log in met Discord, Twitch of GitHub, maak er een aan in het dashboard en verstuur hem in de header X-API-Key. Een sleutel verhoogt je limiet standaard naar 1 verzoek per minuut, op aanvraag meer, en toont je verkeer.

Verzoekheader

HeaderWaardeBeschrijving
X-API-Keyjdk_…Je API-sleutel: optioneel op elke route. Een onbekende, ingetrokken of uitgeschakelde sleutel wordt nooit geweigerd: de aanroep telt als anoniem, en x-api-key-status: invalid meldt dat.
Voorbeeldverzoek · 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

Gratis API-sleutel aanvragen

Een sleutel is gratis. Hij verhoogt je limiet van 1 verzoek per 5 minuten naar 1 verzoek per minuut op elke route, en je dashboard toont het verkeer.

  1. Log in met Discord, Twitch of GitHub: geen wachtwoord, geen formulier.
  2. Open API-sleutels in je dashboard en maak een sleutel aan met de naam van je bot of site.
  3. Kopieer de sleutel wanneer hij wordt getoond (maar één keer) en verstuur hem in de header X-API-Key, vanaf je server.

Drops-campagnes ophalen

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

Elke actieve Drops-campagne, gegroepeerd per game: één item van games per game, met de campagnes in rewards, samen met het tijdstip van de laatste Twitch-scan en je verzoeklimiet.

Antwoordbody

VeldTypeBeschrijving
gamesGame[]De actieve campagnes, in de volgorde van de laatste scan. Een lege array is een geldig antwoord.
refreshedAtstring (ISO 8601) | nullTijdstip van de laatste geslaagde Twitch-scan, null vóór de eerste.
rateLimit{ limit, remaining, resetAt }Je limiet op deze route na deze aanroep, zoals de ratelimit-*-headers die aangeven: limit verzoeken per venster, remaining nog toegestaan, en resetAt, wanneer de volledige limiet terug is (ISO 8601).

Game

Eén item van games.

VeldTypeBeschrijving
gameIdstringTwitch-id van de game.
gameDisplayNamestringNaam van de game.
gameBoxArtURLstring (URL)Box art van de game, 120×160.
startAtstring (ISO 8601)Start van de vroegste campagne van de game.
endAtstring (ISO 8601)Einde van de laatste campagne van de game.
rewardsDropCampaign[]De Drops-campagnes van de game.
Velden van DropCampaign, TimeBasedDrop en Benefit

DropCampaign

Een Drops-campagne, in rewards van een game.

VeldTypeBeschrijving
idstringTwitch-id van de campagne.
name, descriptionstringNaam en beschrijving van de uitgever.
owner{ id, name }Uitgever die de campagne voert.
game{ id, displayName, slug }Game van de campagne.
statusstringTwitch-status, ACTIVE voor een lopende campagne.
startAt, endAtstring (ISO 8601)Looptijd van de campagne.
imageURLstring (URL)Campagneafbeelding.
detailsURL, accountLinkURLstring (URL)Detailpagina en pagina voor accountkoppeling van de uitgever.
allow{ isEnabled, channels? }Kanalen die de Drops mogen geven als isEnabled true is; anders elk kanaal dat de game streamt. displayName kan null zijn of ontbreken.
timeBasedDropsTimeBasedDrop[]Drops die je verdient door te kijken.
eventBasedDropsunknown[]Drops die je verdient via evenementen, ongewijzigd doorgegeven van Twitch.
firstSeenAtstring (ISO 8601) | nullWanneer deze API de campagne voor het eerst zag. Een campagne die minder dan een dag na het verlaten van de lijst terugkomt, houdt haar datum. null voor de campagnes die de API al leverde toen dit veld erbij kwam.

TimeBasedDrop

Een Drop die je verdient door te kijken, in timeBasedDrops.

VeldTypeBeschrijving
id, namestringTwitch-id en naam van de Drop.
startAt, endAtstring (ISO 8601)Periode waarin de Drop te verdienen is.
requiredMinutesWatchednumberBenodigde kijkminuten.
requiredSubsnumberBenodigde abonnementen.
repeat{ everyHours, times } | nullToegevoegd door deze API: hoe vaak de Drop opnieuw te verdienen is, met times (hoe vaak) en everyHours (24: eenmaal per dag; null als Twitch het niet zegt). requiredMinutesWatched is dan de kijktijd van één periode. null voor een Drop die je één keer verdient.
preconditionDropsunknownDrops die je eerst moet verdienen, ongewijzigd doorgegeven van Twitch.
benefitEdges{ benefit: Benefit, entitlementLimit }[]Wat de Drop geeft, met hoe vaak het kan worden geclaimd.

Benefit

Een in-game item, in benefitEdges.

VeldTypeBeschrijving
id, namestringTwitch-id en naam van het item.
imageAssetURLstring (URL)Afbeelding van het item.
createdAtstring (ISO 8601)Aanmaakdatum van het item op Twitch.
distributionTypestringHoe het item wordt geleverd: DIRECT_ENTITLEMENT voor een in-game item, BADGE voor een chatbadge.
entitlementLimitnumberHoe vaak het item kan worden geclaimd.
isIosAvailablebooleanOf het item op iOS kan worden geclaimd.
game, ownerOrganization{ id, name }Game en uitgever van het item.

Antwoordcodes

StatusBeschrijving
200De actieve campagnes. Een lege lijst is een geldig antwoord.
304Er is niets veranderd sinds de ETag die je stuurde: houd je kopie. Gratis, telt niet mee voor je limiet.
429RATE_LIMITED: Wacht het aantal seconden uit Retry-After.
429INVALID_API_KEY_RATE_LIMITED: De sleutel wordt niet herkend en de anonieme limiet van je IP-adres is op: corrigeer de sleutel.
503SERVICE_UNAVAILABLE: Nog geen lijst geladen (vlak na een herstart van de API): probeer het opnieuw na Retry-After. Gratis, telt niet mee voor je limiet.
Voorbeeldverzoek
curl https://drops.sunkwi.com/api/twitch/drops
Voorbeeldantwoord · 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" }}

Beloningscampagnes ophalen

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

Elke actieve beloningscampagne (evenementen op heel Twitch, chatbadges, partnerbeloningen) in campaigns, samen met het tijdstip van de laatste Twitch-scan en je verzoeklimiet.

Antwoordbody

VeldTypeBeschrijving
campaignsRewardCampaign[]De actieve campagnes, in de volgorde van de laatste scan. Een lege array is een geldig antwoord.
refreshedAtstring (ISO 8601) | nullTijdstip van de laatste geslaagde Twitch-scan, null vóór de eerste.
rateLimit{ limit, remaining, resetAt }Je limiet op deze route na deze aanroep, zoals de ratelimit-*-headers die aangeven: limit verzoeken per venster, remaining nog toegestaan, en resetAt, wanneer de volledige limiet terug is (ISO 8601).

RewardCampaign

Eén item van campaigns.

VeldTypeBeschrijving
id, name, brandstringTwitch-id, naam en merk van de campagne.
statusstringStatus op het moment van het verzoek, afgeleid uit de datums: UPCOMING vóór startsAt, ACTIVE tot endsAt, daarna EXPIRED.
summary, instructionsstringTeksten die Twitch toont.
startsAt, endsAtstring (ISO 8601)Looptijd van de campagne.
image{ image1xURL }Campagneafbeelding.
aboutURL, externalURLstring (URL)Hulppagina en externe pagina van de campagne.
isSitewidebooleanOf elk kanaal meetelt, niet alleen die van één game.
game{ id, displayName, slug }?Game van de campagne, als ze er een heeft.
rewardValueURLParamstringWaarde die Twitch aan de inwissellinks toevoegt.
unlockRequirements{ minuteWatchedGoal, subsGoal }Benodigde kijkminuten en abonnementen.
rewardGroupsRewardGroup[]?Beloningen die je groep voor groep verdient, elke groep met een eigen doel: een beloning per dag is een groep per dag. Alleen als Twitch ze stuurt.
rewardsReward[]De beloningen van de campagne, inclusief die van de groepen, elk één keer.
firstSeenAtstring (ISO 8601) | nullWanneer deze API de campagne voor het eerst zag. Een campagne die minder dan een dag na het verlaten van de lijst terugkomt, houdt haar datum. null voor de campagnes die de API al leverde toen dit veld erbij kwam.
Velden van beloningen

RewardGroup

Een groep beloningen van een beloningscampagne, die je samen verdient.

VeldTypeBeschrijving
idstringTwitch-id van de groep.
unlockRequirements{ minuteWatchedGoal, subsGoal, turboSubsGoal?, eventTriggerGoal? }Wat de groep vraagt. Twitch zet daar ook Turbo- en evenementdoelen.
repeat{ everyHours, times } | nullHoe vaak de groep opnieuw te verdienen is, zoals de repeat van een Drop: minuteWatchedGoal is dan de kijktijd van één periode. null voor een groep die je één keer verdient.
categories{ id, displayName, slug }[]De categorieën waarvan de livekanalen tellen, welke ook; leeg als Twitch er geen noemt.
rewardsReward[]De beloningen van de groep, ook vermeld in rewards van de campagne.

Reward

Een beloning van een beloningscampagne.

VeldTypeBeschrijving
id, namestringTwitch-id en naam van de beloning.
bannerImage, thumbnailImage{ image1xURL }Afbeeldingen van de beloning.
earnableUntilstring (ISO 8601)Laatste moment waarop de beloning te verdienen is.
redemptionInstructions, redemptionURLstringHoe en waar je de beloning inwisselt.

Antwoordcodes

StatusBeschrijving
200De actieve campagnes. Een lege lijst is een geldig antwoord.
304Er is niets veranderd sinds de ETag die je stuurde: houd je kopie. Gratis, telt niet mee voor je limiet.
429RATE_LIMITED: Wacht het aantal seconden uit Retry-After.
429INVALID_API_KEY_RATE_LIMITED: De sleutel wordt niet herkend en de anonieme limiet van je IP-adres is op: corrigeer de sleutel.
503SERVICE_UNAVAILABLE: Nog geen lijst geladen (vlak na een herstart van de API): probeer het opnieuw na Retry-After. Gratis, telt niet mee voor je limiet.
Voorbeeldverzoek
curl https://drops.sunkwi.com/api/twitch/rewards
Voorbeeldantwoord · 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" }}

Chatbadges ophalen

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

De globale chatbadges van Twitch in badges, één item per versie, elk met hoe je hem krijgt als deze API dat weet (requirement), samen met het tijdstip waarop de badges van Twitch het laatst zijn uitgelezen en je verzoeklimiet.

Antwoordbody

VeldTypeBeschrijving
badgesBadge[]De globale badges, één item per versie. Een lege array is een geldig antwoord.
refreshedAtstring (ISO 8601) | nullTijdstip waarop de badges van Twitch het laatst met succes zijn uitgelezen (elke 5 minuten), null vóór de eerste keer.
rateLimit{ limit, remaining, resetAt }Je limiet op deze route na deze aanroep, zoals de ratelimit-*-headers die aangeven: limit verzoeken per venster, remaining nog toegestaan, en resetAt, wanneer de volledige limiet terug is (ISO 8601).

Badge

Eén item van badges: één versie van een globale chatbadge, zoals Twitch hem nu vermeldt.

VeldTypeBeschrijving
setId, versionIdstringDe badgeset en de versie: samen duiden ze één badge aan (sub-gifter en 5).
title, descriptionstringDe naam en de beschrijving van Twitch, in het Engels.
imageUrl1x, imageUrl2x, imageUrl4xstring (URL)De afbeelding op 18, 36 en 72 pixels.
clickAction, clickUrlstring | nullWat Twitch doet als je op de badge klikt, en de link; null als Twitch er geen geeft.
firstSeenAtstring (ISO 8601) | nullWanneer deze API de badge voor het eerst zag. Komt een badge meer dan 7 dagen nadat Twitch hem verwijderde terug, dan krijgt hij een nieuwe datum; komt hij eerder terug, dan houdt hij zijn oude. null voor de badges die er bij de eerste uitlezing al waren.
requirementBadgeRequirement | nullHoe je hem krijgt; null als deze API het niet weet.
Velden van BadgeRequirement

BadgeRequirement

Hoe je een badge krijgt: via de Drops-campagne die hem geeft (DROPS), of volgens de eigen beschrijving van Twitch van een abonnee- of kijkbadge (TWITCH_DESCRIPTION).

VeldTypeBeschrijving
source'DROPS' | 'TWITCH_DESCRIPTION'DROPS of TWITCH_DESCRIPTION.
watchTimeOnlybooleantrue precies wanneer kijken genoeg is: een DROPS-campagne die kijktijd vraagt (requiredMinutes boven 0) en geen abonnement (requiredSubs 0).
requiredMinutes, requiredSubsnumberDe kijkminuten, en abonnementen of cadeau-abonnementen, die ze vraagt.
gameId, gameNamestringDe game: de Twitch-id (null als onbekend) en de naam.
channels, channelCountstring[] (≤ 5), numberDe eerste 5 kanalen die hem geven (logins) en hoeveel het er zijn; 0: elk kanaal dat de game streamt.
startAt, endAtstring (ISO 8601) | nullLooptijd van de campagne; null bij TWITCH_DESCRIPTION. Een afgelopen campagne blijft staan.
campaignId, campaignNamestring | nullDe Drops-campagne; null bij TWITCH_DESCRIPTION.
repeat{ everyHours, times } | nullAlleen DROPS: de kijktijd is elke periode opnieuw nodig, waarbij requiredMinutes die van één periode is, met times en everyHours (20 min per dag op 3 dagen: times 3, everyHours 24); anders null.
categories{ id, name }[] (≤ 50)Alleen DROPS: de categorieën waarvan de livekanalen tellen, welke ook (id en name, maximaal 50); gameId en gameName zijn de eerste. Anders leeg.
collection{ chestSize, completeAll } | nullAlleen DROPS: de badge is een van de beloningen van een evenementcollectie, de campagne. chestSize: hij komt uit een kist met zoveel beloningen, één per kist, nooit naar keuze (null: zo gegeven). completeAll: gegeven voor het voltooien van de hele collectie, abonnementen inbegrepen. Anders null.
evolvesFrom{ setId, versionId } | nullAlleen DROPS: de badge die je vóór het kijken in de chat moet dragen, via zijn setId en versionId in deze lijst: een Pokémon-evolutie vraagt haar vorige stadium (Pikachu: Pichu). Anders null, of als hij onbekend is.

Antwoordcodes

StatusBeschrijving
200De globale badges. Een lege lijst is een geldig antwoord.
304Er is niets veranderd sinds de ETag die je stuurde: houd je kopie. Gratis, telt niet mee voor je limiet.
429RATE_LIMITED: Wacht het aantal seconden uit Retry-After.
429INVALID_API_KEY_RATE_LIMITED: De sleutel wordt niet herkend en de anonieme limiet van je IP-adres is op: corrigeer de sleutel.
503SERVICE_UNAVAILABLE: Nog geen lijst geladen (vlak na een herstart van de API): probeer het opnieuw na Retry-After. Gratis, telt niet mee voor je limiet.
Voorbeeldverzoek
curl https://drops.sunkwi.com/api/twitch/badges
Voorbeeld laden…

Verzoeklimieten

Elke route heeft een eigen teller: /drops aanroepen gaat nooit af van het budget van /rewards of /badges. De campagnes veranderen één keer per minuut en de badges elke 5 minuten, dus vaker opvragen levert niets nieuws op.

AanroeperLimiet per routeGeteld per
Anoniem1 verzoek per 5 minutenIP-adres
Met een API-sleutelStandaard 1 verzoek per minuut, op aanvraag meerAPI-sleutel

Antwoordheaders

Headers die de API leest en verstuurt.

HeaderRichtingBeschrijving
x-last-updated-atresponseTijdstip waarop Twitch het laatst met succes is uitgelezen: de scan voor /drops en /rewards, de badges voor /badges.
x-refresh-interval-secondsresponseSeconden tussen twee keer Twitch uitlezen: vaker vragen geeft dezelfde data (60 voor /drops en /rewards, 300 voor /badges).
ratelimit-limitresponseToegestane verzoeken in het venster, voor deze route.
ratelimit-remainingresponseResterende verzoeken in het huidige venster.
ratelimit-resetresponseSeconden tot er weer een verzoek is toegestaan.
ratelimit-policyresponseHet beleid, als <limiet>;w=<venster in seconden>.
retry-afterresponseSeconden wachten voor een nieuwe poging, bij een 429- of 503-antwoord.
x-api-keyrequestJe API-sleutel: optioneel op elke route.
x-api-key-statusresponseinvalid als de verstuurde sleutel onbekend, ingetrokken of uitgeschakeld is: de aanroep telde als anoniem, binnen de limiet van je IP-adres.
etagresponseLabel van dit antwoord. Stuur het terug in If-None-Match: zolang de gegevens niet veranderd zijn, is het antwoord een 304 die niet meetelt voor je limiet.
if-none-matchrequestDe ETag van je laatste antwoord, optioneel: een ongewijzigde lijst antwoordt 304 Not Modified, gratis.
Een tweede anonieme aanroep binnen 5 minuten
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" }

Fouten

Fouten antwoorden met een JSON-body met een vaste code: { "code": "RATE_LIMITED" }. Codes veranderen nooit: bouw op code, niet op een bericht.

StatusCodeBeschrijving
429RATE_LIMITEDTe veel verzoeken op deze route: wacht het aantal seconden uit Retry-After.
429INVALID_API_KEY_RATE_LIMITEDTe veel verzoeken, en de header X-API-Key bevat een onbekende, ingetrokken of uitgeschakelde sleutel: de aanroep telde als anoniem. Corrigeer de sleutel, of wacht het aantal seconden uit Retry-After.
503SERVICE_UNAVAILABLENog geen lijst geladen (vlak na een herstart van de API). Er wordt niets verbruikt: probeer het opnieuw na het aantal seconden uit Retry-After.
404NOT_FOUNDDe route bestaat niet.
500INTERNAL_SERVER_ERRORDe server faalde: probeer het later opnieuw.
Voorbeeldfout
HTTP/1.1 404 Not Foundcontent-type: application/json; charset=utf-8
{ "code": "NOT_FOUND" }

Van de site naar de API

Elke pagina van deze site leest dezelfde routes. Hier zie je waar in de antwoorden staat wat een pagina toont.

PaginaRouteWaar in het antwoord
Drops/drops/dropsgames: één item per game, met de campagnes in rewards. De rasterweergave tekent startAt en endAt van elke campagne.
Een gamepagina/drops/<game>/dropsEén item van games, gekoppeld op gameId. Elke campagne is games[i].rewards[j]; de beloningen ervan zijn de benefitEdges van timeBasedDrops, met requiredMinutesWatched.
Beloningen/rewards/rewardscampaigns: één item per beloningscampagne, met de beloningen in rewards en wat ze vraagt in unlockRequirements.
Een beloningscampagnepagina/rewards/<campaign>/rewardsEén item van campaigns, gekoppeld op id; de beloningen ervan staan in rewards.
Badges/badges/badgesbadges: elk item, die met een requirement eerst, met hoe je ze krijgt. De rasterweergave tekent requirement.startAt en requirement.endAt van elke badge.
Een badgepagina/badges/<badge>/badgesEén item van badges, gekoppeld op setId en versionId; “Zo krijg je hem” is de requirement ervan.