Aller au contenu
Twitch Drops API

Référence de la Twitch Drops API

Une API JSON gratuite qui liste toutes les campagnes de Drops et de récompenses actives sur Twitch, actualisée chaque minute, ainsi que les badges de chat globaux de Twitch. Appelez-la anonymement, ou avec une clé API gratuite pour une limite plus élevée.

URL de basehttps://drops.sunkwi.com/api/twitch
Obtenir une clé API gratuiteLire la référence

Essayer

Anonyme : 1 requête toutes les 5 minutes par route. Avec une clé : 1 par minute.

GET
Chargement de l’aperçu…
Parcourir

Routes

Chaque route répond en JSON à une requête GET, et les navigateurs de n’importe quel site peuvent appeler l’API (CORS). Ni /drops, ni /rewards, ni /badges ne demandent d’inscription ; une clé API gratuite relève la limite sur chacune.

Les trois routes répondent de la même façon : la liste, l’heure de la dernière lecture de Twitch (refreshedAt) et votre limite de débit (rateLimit).

RouteDescription
GET /dropsCampagnes de Drops par jeu. Toutes les campagnes de Drops actives, regroupées par jeu, dans games : un élément par jeu, ses campagnes dans rewards.
GET /rewardsCampagnes de récompenses. Toutes les campagnes de récompenses actives (événements sur tout Twitch, badges de chat, récompenses partenaires), dans campaigns.
GET /badgesBadges de chat globaux. Les badges de chat globaux de Twitch, un élément par version dans badges, avec la façon de les obtenir quand elle est connue.

Authentification

La lecture de /drops, /rewards et /badges ne demande ni compte ni clé. Les appels anonymes sont comptés par adresse IP : 1 requête toutes les 5 minutes sur chaque route.

Les clés sont gratuites : connectez-vous avec Discord, Twitch ou GitHub, créez-en une dans le tableau de bord et envoyez-la dans l’en-tête X-API-Key. Une clé relève votre limite à 1 requête par minute par défaut, davantage sur demande, et affiche votre trafic.

En-tête de requête

En-têteValeurDescription
X-API-Keyjdk_…Votre clé API : facultative sur toutes les routes. Une clé inconnue, révoquée ou désactivée n’est jamais refusée : l’appel compte comme anonyme, et x-api-key-status: invalid le signale.
Exemple de requête · 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

Obtenir une clé API gratuite

Une clé est gratuite. Elle fait passer votre limite de 1 requête toutes les 5 minutes à 1 requête par minute sur chaque route, et votre tableau de bord affiche son trafic.

  1. Connectez-vous avec Discord, Twitch ou GitHub : ni mot de passe, ni formulaire.
  2. Ouvrez Clés API dans votre tableau de bord et créez une clé au nom de votre bot ou de votre site.
  3. Copiez la clé quand elle s’affiche (une seule fois) et envoyez-la dans l’en-tête X-API-Key, depuis votre serveur.

Obtenir les campagnes de Drops

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

Toutes les campagnes de Drops actives, regroupées par jeu : un élément de games par jeu, ses campagnes dans rewards, avec l’heure du dernier scan de Twitch et votre limite de débit.

Corps de la réponse

ChampTypeDescription
gamesGame[]Les campagnes actives, dans l’ordre du dernier scan. Un tableau vide est une réponse valide.
refreshedAtstring (ISO 8601) | nullHeure du dernier scan Twitch réussi, null avant le premier.
rateLimit{ limit, remaining, resetAt }Votre limite sur cette route après cet appel, telle que l’indiquent les en-têtes ratelimit-* : limit requêtes par fenêtre, remaining encore autorisées, et resetAt, le moment où la limite revient en entier (ISO 8601).

Game

Un élément de games.

ChampTypeDescription
gameIdstringIdentifiant Twitch du jeu.
gameDisplayNamestringNom du jeu.
gameBoxArtURLstring (URL)Jaquette du jeu, 120×160.
startAtstring (ISO 8601)Début de la première campagne du jeu.
endAtstring (ISO 8601)Fin de la dernière campagne du jeu.
rewardsDropCampaign[]Les campagnes de Drops du jeu.
Champs de DropCampaign, TimeBasedDrop et Benefit

DropCampaign

Une campagne de Drops, dans rewards d’un jeu.

ChampTypeDescription
idstringIdentifiant Twitch de la campagne.
name, descriptionstringNom et description fournis par l’éditeur.
owner{ id, name }Éditeur qui mène la campagne.
game{ id, displayName, slug }Jeu de la campagne.
statusstringStatut Twitch, ACTIVE pour une campagne en cours.
startAt, endAtstring (ISO 8601)Période de la campagne.
imageURLstring (URL)Visuel de la campagne.
detailsURL, accountLinkURLstring (URL)Page de détails et page d’association de compte de l’éditeur.
allow{ isEnabled, channels? }Chaînes autorisées à donner les Drops quand isEnabled vaut true ; sinon, toute chaîne qui diffuse le jeu. displayName peut être null ou absent.
timeBasedDropsTimeBasedDrop[]Drops obtenus en regardant.
eventBasedDropsunknown[]Drops obtenus via des événements, transmis tels quels depuis Twitch.
firstSeenAtstring (ISO 8601) | nullQuand cette API a vu la campagne pour la première fois. Une campagne revenue moins d’un jour après avoir quitté la liste garde sa date. null pour les campagnes qu’elle servait déjà quand ce champ est apparu.

TimeBasedDrop

Un Drop obtenu en regardant, dans timeBasedDrops.

ChampTypeDescription
id, namestringIdentifiant Twitch et nom du Drop.
startAt, endAtstring (ISO 8601)Période pendant laquelle le Drop peut être obtenu.
requiredMinutesWatchednumberMinutes de visionnage nécessaires.
requiredSubsnumberAbonnements nécessaires.
repeat{ everyHours, times } | nullAjouté par cette API : la fréquence à laquelle le Drop s’obtient de nouveau, avec times (combien de fois) et everyHours (24 : une fois par jour ; null quand Twitch ne le dit pas). requiredMinutesWatched est alors le temps de visionnage d’une période. null pour un Drop obtenu une seule fois.
preconditionDropsunknownDrops à obtenir d’abord, transmis tels quels depuis Twitch.
benefitEdges{ benefit: Benefit, entitlementLimit }[]Ce que donne le Drop, avec le nombre de fois où il peut être récupéré.

Benefit

Un objet en jeu, dans benefitEdges.

ChampTypeDescription
id, namestringIdentifiant Twitch et nom de l’objet.
imageAssetURLstring (URL)Image de l’objet.
createdAtstring (ISO 8601)Date de création de l’objet sur Twitch.
distributionTypestringMode de remise de l’objet : DIRECT_ENTITLEMENT pour un objet en jeu, BADGE pour un badge de chat.
entitlementLimitnumberNombre de fois où l’objet peut être récupéré.
isIosAvailablebooleanIndique si l’objet peut être récupéré sur iOS.
game, ownerOrganization{ id, name }Jeu et éditeur de l’objet.

Codes de réponse

StatutDescription
200Les campagnes actives. Une liste vide est une réponse valide.
304Rien n’a changé depuis l’ETag envoyé : gardez votre copie. Gratuit, ne compte pas dans votre limite.
429RATE_LIMITED: Attendez le nombre de secondes indiqué par Retry-After.
429INVALID_API_KEY_RATE_LIMITED: La clé n’est pas reconnue et la limite anonyme de votre adresse IP est épuisée : corrigez la clé.
503SERVICE_UNAVAILABLE: Aucune liste chargée pour l’instant (juste après un redémarrage de l’API) : réessayez après Retry-After. Gratuit, ne compte pas dans votre limite.
Exemple de requête
curl https://drops.sunkwi.com/api/twitch/drops
Exemple de réponse · 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" }}

Obtenir les campagnes de récompenses

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

Toutes les campagnes de récompenses actives (événements sur tout Twitch, badges de chat, récompenses partenaires) dans campaigns, avec l’heure du dernier scan de Twitch et votre limite de débit.

Corps de la réponse

ChampTypeDescription
campaignsRewardCampaign[]Les campagnes actives, dans l’ordre du dernier scan. Un tableau vide est une réponse valide.
refreshedAtstring (ISO 8601) | nullHeure du dernier scan Twitch réussi, null avant le premier.
rateLimit{ limit, remaining, resetAt }Votre limite sur cette route après cet appel, telle que l’indiquent les en-têtes ratelimit-* : limit requêtes par fenêtre, remaining encore autorisées, et resetAt, le moment où la limite revient en entier (ISO 8601).

RewardCampaign

Un élément de campaigns.

ChampTypeDescription
id, name, brandstringIdentifiant Twitch, nom et marque de la campagne.
statusstringStatut au moment de la requête, lu dans les dates : UPCOMING avant startsAt, ACTIVE jusqu’à endsAt, puis EXPIRED.
summary, instructionsstringTextes affichés par Twitch.
startsAt, endsAtstring (ISO 8601)Période de la campagne.
image{ image1xURL }Visuel de la campagne.
aboutURL, externalURLstring (URL)Page d’aide et page externe de la campagne.
isSitewidebooleanIndique si toutes les chaînes comptent, pas seulement celles d’un jeu.
game{ id, displayName, slug }?Jeu de la campagne, s’il y en a un.
rewardValueURLParamstringValeur que Twitch ajoute aux liens d’échange.
unlockRequirements{ minuteWatchedGoal, subsGoal }Minutes de visionnage et abonnements nécessaires.
rewardGroupsRewardGroup[]?Récompenses obtenues un groupe à la fois, chaque groupe avec son propre objectif : une récompense par jour, c’est un groupe par jour. Seulement quand Twitch les envoie.
rewardsReward[]Les récompenses de la campagne, y compris celles de ses groupes, chacune une seule fois.
firstSeenAtstring (ISO 8601) | nullQuand cette API a vu la campagne pour la première fois. Une campagne revenue moins d’un jour après avoir quitté la liste garde sa date. null pour les campagnes qu’elle servait déjà quand ce champ est apparu.
Champs des récompenses

RewardGroup

Un groupe de récompenses d’une campagne de récompenses, obtenues ensemble.

ChampTypeDescription
idstringIdentifiant Twitch du groupe.
unlockRequirements{ minuteWatchedGoal, subsGoal, turboSubsGoal?, eventTriggerGoal? }Ce que demande le groupe. Twitch y ajoute des objectifs Turbo et d’événements.
repeat{ everyHours, times } | nullLa fréquence à laquelle le groupe s’obtient de nouveau, comme le repeat d’un Drop : minuteWatchedGoal est alors le temps de visionnage d’une période. null pour un groupe obtenu une seule fois.
categories{ id, displayName, slug }[]Les catégories dont les chaînes en direct comptent, n’importe laquelle ; vide quand Twitch n’en nomme aucune.
rewardsReward[]Les récompenses du groupe, aussi listées dans rewards de la campagne.

Reward

Une récompense d’une campagne de récompenses.

ChampTypeDescription
id, namestringIdentifiant Twitch et nom de la récompense.
bannerImage, thumbnailImage{ image1xURL }Images de la récompense.
earnableUntilstring (ISO 8601)Dernier moment pour obtenir la récompense.
redemptionInstructions, redemptionURLstringComment échanger la récompense, et où.

Codes de réponse

StatutDescription
200Les campagnes actives. Une liste vide est une réponse valide.
304Rien n’a changé depuis l’ETag envoyé : gardez votre copie. Gratuit, ne compte pas dans votre limite.
429RATE_LIMITED: Attendez le nombre de secondes indiqué par Retry-After.
429INVALID_API_KEY_RATE_LIMITED: La clé n’est pas reconnue et la limite anonyme de votre adresse IP est épuisée : corrigez la clé.
503SERVICE_UNAVAILABLE: Aucune liste chargée pour l’instant (juste après un redémarrage de l’API) : réessayez après Retry-After. Gratuit, ne compte pas dans votre limite.
Exemple de requête
curl https://drops.sunkwi.com/api/twitch/rewards
Exemple de réponse · 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" }}

Obtenir les badges de chat

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

Les badges de chat globaux de Twitch dans badges, un élément par version, chacun avec la façon de l’obtenir quand cette API la connaît (requirement), avec l’heure de la dernière lecture des badges de Twitch et votre limite de débit.

Corps de la réponse

ChampTypeDescription
badgesBadge[]Les badges globaux, un élément par version. Un tableau vide est une réponse valide.
refreshedAtstring (ISO 8601) | nullHeure de la dernière lecture réussie des badges de Twitch (toutes les 5 minutes), null avant la première.
rateLimit{ limit, remaining, resetAt }Votre limite sur cette route après cet appel, telle que l’indiquent les en-têtes ratelimit-* : limit requêtes par fenêtre, remaining encore autorisées, et resetAt, le moment où la limite revient en entier (ISO 8601).

Badge

Un élément de badges : une version d’un badge de chat global, telle que Twitch la liste en ce moment.

ChampTypeDescription
setId, versionIdstringLe jeu de badges (setId) et sa version : à eux deux, ils désignent un badge (sub-gifter et 5).
title, descriptionstringSon nom et la description de Twitch, en anglais.
imageUrl1x, imageUrl2x, imageUrl4xstring (URL)Son image en 18, 36 et 72 pixels.
clickAction, clickUrlstring | nullCe que fait Twitch quand on clique sur le badge, et son lien ; null quand Twitch n’en donne pas.
firstSeenAtstring (ISO 8601) | nullQuand cette API a vu le badge pour la première fois. Un badge revenu plus de 7 jours après son retrait par Twitch prend une nouvelle date ; revenu avant, il garde la sienne. null pour les badges déjà présents lors de sa première lecture.
requirementBadgeRequirement | nullComment l’obtenir ; null quand cette API ne le sait pas.
Champs de BadgeRequirement

BadgeRequirement

Comment obtenir un badge : par la campagne de Drops qui le donne (DROPS), ou d’après la description que Twitch donne elle-même d’un badge d’abonnement ou de visionnage (TWITCH_DESCRIPTION).

ChampTypeDescription
source'DROPS' | 'TWITCH_DESCRIPTION'DROPS ou TWITCH_DESCRIPTION.
watchTimeOnlybooleantrue exactement quand regarder suffit : une campagne DROPS qui demande du temps de visionnage (requiredMinutes supérieur à 0) et aucun abonnement (requiredSubs à 0).
requiredMinutes, requiredSubsnumberLes minutes de visionnage et les abonnements (ou abonnements offerts) demandés.
gameId, gameNamestringLe jeu : son identifiant Twitch (null s’il est inconnu) et son nom.
channels, channelCountstring[] (≤ 5), numberLes 5 premières chaînes qui le donnent (logins) et leur nombre ; 0 : toute chaîne qui diffuse le jeu.
startAt, endAtstring (ISO 8601) | nullPériode de la campagne ; null pour TWITCH_DESCRIPTION. Une campagne terminée reste.
campaignId, campaignNamestring | nullLa campagne de Drops ; null pour TWITCH_DESCRIPTION.
repeat{ everyHours, times } | nullDROPS seulement : le temps de visionnage est demandé de nouveau à chaque période, requiredMinutes étant celui d’une période, avec times et everyHours (20 min par jour, 3 jours : times 3, everyHours 24) ; null sinon.
categories{ id, name }[] (≤ 50)DROPS seulement : les catégories dont les chaînes en direct comptent, n’importe laquelle (id et name, 50 au plus) ; gameId et gameName sont la première. Vide sinon.
collection{ chestSize, completeAll } | nullDROPS seulement : le badge est une récompense d’une collection d’événement, la campagne. chestSize : il sort d’un coffre d’autant de récompenses, une par coffre, jamais au choix (null : donné tel quel). completeAll : donné pour avoir terminé toute la collection, abonnements compris. null sinon.
evolvesFrom{ setId, versionId } | nullDROPS seulement : le badge à équiper dans le chat avant de regarder, par son setId et son versionId dans cette liste : une évolution Pokémon demande son stade précédent (Pikachu : Pichu). null sinon, ou s’il est inconnu.

Codes de réponse

StatutDescription
200Les badges globaux. Une liste vide est une réponse valide.
304Rien n’a changé depuis l’ETag envoyé : gardez votre copie. Gratuit, ne compte pas dans votre limite.
429RATE_LIMITED: Attendez le nombre de secondes indiqué par Retry-After.
429INVALID_API_KEY_RATE_LIMITED: La clé n’est pas reconnue et la limite anonyme de votre adresse IP est épuisée : corrigez la clé.
503SERVICE_UNAVAILABLE: Aucune liste chargée pour l’instant (juste après un redémarrage de l’API) : réessayez après Retry-After. Gratuit, ne compte pas dans votre limite.
Exemple de requête
curl https://drops.sunkwi.com/api/twitch/badges
Chargement de l’aperçu…

Limites de débit

Chaque route a son propre compteur : appeler /drops n’entame jamais le quota de /rewards ni celui de /badges. Les campagnes changent une fois par minute et les badges toutes les 5 minutes : interroger plus souvent n’apporte rien de nouveau.

AppelantLimite par routeCompté par
Anonyme1 requête toutes les 5 minutesAdresse IP
Avec une clé API1 requête par minute par défaut, davantage sur demandeClé API

En-têtes de réponse

En-têtes lus et envoyés par l’API.

En-têteSensDescription
x-last-updated-atresponseHeure de la dernière lecture réussie de Twitch : le scan pour /drops et /rewards, les badges pour /badges.
x-refresh-interval-secondsresponseSecondes entre deux lectures de Twitch : demander plus souvent renvoie les mêmes données (60 pour /drops et /rewards, 300 pour /badges).
ratelimit-limitresponseRequêtes autorisées dans la fenêtre, pour cette route.
ratelimit-remainingresponseRequêtes restantes dans la fenêtre en cours.
ratelimit-resetresponseSecondes avant qu’une requête soit de nouveau autorisée.
ratelimit-policyresponseLa politique, au format <limite>;w=<fenêtre en secondes>.
retry-afterresponseSecondes à attendre avant de réessayer, sur une réponse 429 ou 503.
x-api-keyrequestVotre clé API : facultative sur toutes les routes.
x-api-key-statusresponseinvalid quand la clé envoyée est inconnue, révoquée ou désactivée : l’appel a compté comme anonyme, sur la limite de votre adresse IP.
etagresponseÉtiquette de cette réponse. Renvoyez-la dans If-None-Match : tant que les données n’ont pas changé, la réponse est un 304 qui ne compte pas dans votre limite.
if-none-matchrequestL’ETag de votre dernière réponse, facultatif : une liste inchangée répond 304 Not Modified, gratuitement.
Un deuxième appel anonyme en moins de 5 minutes
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" }

Erreurs

Les erreurs renvoient un corps JSON avec un code stable : { "code": "RATE_LIMITED" }. Les codes ne changent jamais : appuyez-vous sur code, pas sur un message.

StatutCodeDescription
429RATE_LIMITEDTrop de requêtes sur cette route : attendez le nombre de secondes indiqué par Retry-After.
429INVALID_API_KEY_RATE_LIMITEDTrop de requêtes, et l’en-tête X-API-Key contient une clé inconnue, révoquée ou désactivée : l’appel a compté comme anonyme. Corrigez la clé, ou attendez le nombre de secondes indiqué par Retry-After.
503SERVICE_UNAVAILABLEAucune liste n’est encore chargée (juste après un redémarrage de l’API). Rien n’est décompté : réessayez après le nombre de secondes indiqué par Retry-After.
404NOT_FOUNDLa route n’existe pas.
500INTERNAL_SERVER_ERRORErreur du serveur : réessayez plus tard.
Exemple d’erreur
HTTP/1.1 404 Not Foundcontent-type: application/json; charset=utf-8
{ "code": "NOT_FOUND" }

Du site à l’API

Chaque page de ce site lit ces mêmes routes. Voici où se trouve, dans les réponses, ce qu’affiche chaque page.

PageRouteOù dans la réponse
Drops/drops/dropsgames : un élément par jeu, ses campagnes dans rewards. La vue en grille trace startAt et endAt de chaque campagne.
Une page de jeu/drops/<game>/dropsUn élément de games, identifié par gameId. Chaque campagne est games[i].rewards[j] ; ses récompenses sont les benefitEdges de timeBasedDrops, avec requiredMinutesWatched.
Récompenses/rewards/rewardscampaigns : un élément par campagne de récompenses, ses récompenses dans rewards et ses conditions dans unlockRequirements.
Une page de campagne de récompenses/rewards/<campaign>/rewardsUn élément de campaigns, identifié par id ; ses récompenses sont dans rewards.
Badges/badges/badgesbadges : tous les éléments, ceux qui ont un requirement en premier, avec la façon de les obtenir. La vue en grille trace requirement.startAt et requirement.endAt de chaque badge.
Une page de badge/badges/<badge>/badgesUn élément de badges, identifié par setId et versionId ; « Comment l’obtenir » est son requirement.