Vai al contenuto
Twitch Drops API

Riferimento della Twitch Drops API

Un'API JSON gratuita che elenca ogni campagna Twitch Drops e di ricompense attiva, aggiornata ogni minuto, e i badge globali della chat di Twitch. Chiamala in forma anonima, o con una chiave API gratuita per un limite più alto.

URL di basehttps://drops.sunkwi.com/api/twitch
Ottieni una chiave API gratuitaLeggi il riferimento

Provala

Anonimo: 1 richiesta ogni 5 minuti per route. Con una chiave: 1 al minuto.

GET
Caricamento dell'anteprima…
Sfoglia

Route

Ogni route risponde in JSON a una richiesta GET, e i browser di qualsiasi sito possono chiamare l'API (CORS). Né /drops, né /rewards, né /badges richiedono una registrazione; una chiave API gratuita alza il limite su ciascuna.

Le tre route rispondono allo stesso modo: l'elenco, l'ora dell'ultima lettura di Twitch (refreshedAt) e il tuo limite di richieste (rateLimit).

RouteDescrizione
GET /dropsCampagne Drops per gioco. Ogni campagna Drops attiva, raggruppata per gioco, in games: un elemento per gioco, con le sue campagne in rewards.
GET /rewardsCampagne di ricompense. Ogni campagna di ricompense attiva (eventi su tutta la piattaforma, badge della chat, ricompense dei partner), in campaigns.
GET /badgesBadge globali della chat. I badge globali della chat di Twitch, un elemento per versione in badges, con il modo di ottenerli quando è noto.

Autenticazione

La lettura di /drops, /rewards e /badges non richiede né account né chiave. Le chiamate anonime vengono conteggiate per indirizzo IP: 1 richiesta ogni 5 minuti su ogni route.

Le chiavi sono gratuite: accedi con Discord, Twitch o GitHub, creane una nella dashboard e inviala nell'header X-API-Key. Una chiave alza il tuo limite a 1 richiesta al minuto per impostazione predefinita, di più su richiesta, e mostra il tuo traffico.

Header della richiesta

HeaderValoreDescrizione
X-API-Keyjdk_…La tua chiave API: facoltativa su ogni route. Una chiave sconosciuta, revocata o disattivata non viene mai rifiutata: la chiamata conta come anonima, e x-api-key-status: invalid lo segnala.
Esempio di richiesta · 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

Ottieni una chiave API gratuita

Una chiave è gratuita. Alza il tuo limite da 1 richiesta ogni 5 minuti a 1 richiesta al minuto su ogni route, e la tua dashboard ne mostra il traffico.

  1. Accedi con Discord, Twitch o GitHub: nessuna password, nessun modulo.
  2. Apri Chiavi API nella tua dashboard e crea una chiave con il nome del tuo bot o sito.
  3. Copia la chiave quando viene mostrata (una sola volta) e inviala nell'header X-API-Key, dal tuo server.

Ottieni le campagne Drops

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

Ogni campagna Drops attiva, raggruppata per gioco: un elemento di games per gioco, con le sue campagne in rewards, accompagnato dall'ora dell'ultima scansione di Twitch e dal tuo limite di richieste.

Corpo della risposta

CampoTipoDescrizione
gamesGame[]Le campagne attive, nell'ordine dell'ultima scansione. Un array vuoto è una risposta valida.
refreshedAtstring (ISO 8601) | nullOra dell'ultima scansione di Twitch riuscita, null prima della prima.
rateLimit{ limit, remaining, resetAt }Il tuo limite su questa route dopo questa chiamata, come lo indicano gli header ratelimit-*: limit richieste per finestra, remaining ancora consentite e resetAt, quando il limite torna intero (ISO 8601).

Game

Un elemento di games.

CampoTipoDescrizione
gameIdstringID Twitch del gioco.
gameDisplayNamestringNome del gioco.
gameBoxArtURLstring (URL)Copertina del gioco, 120×160.
startAtstring (ISO 8601)Inizio della prima campagna del gioco.
endAtstring (ISO 8601)Fine dell'ultima campagna del gioco.
rewardsDropCampaign[]Le campagne Drops del gioco.
Campi di DropCampaign, TimeBasedDrop e Benefit

DropCampaign

Una campagna Drops, in rewards di un gioco.

CampoTipoDescrizione
idstringID Twitch della campagna.
name, descriptionstringNome e descrizione forniti dall'editore.
owner{ id, name }Editore che gestisce la campagna.
game{ id, displayName, slug }Gioco della campagna.
statusstringStato Twitch, ACTIVE per una campagna in corso.
startAt, endAtstring (ISO 8601)Periodo di svolgimento della campagna.
imageURLstring (URL)Immagine della campagna.
detailsURL, accountLinkURLstring (URL)Pagina dei dettagli e pagina di collegamento account dell'editore.
allow{ isEnabled, channels? }Canali autorizzati ad assegnare i Drops quando isEnabled è true; altrimenti qualsiasi canale che trasmette il gioco. displayName può essere null o assente.
timeBasedDropsTimeBasedDrop[]Drop ottenuti guardando.
eventBasedDropsunknown[]Drop ottenuti tramite eventi, riportati così come li invia Twitch.
firstSeenAtstring (ISO 8601) | nullQuando questa API ha visto la campagna per la prima volta. Una campagna che torna meno di un giorno dopo essere uscita dalla lista mantiene la sua data. null per le campagne che l'API serviva già quando è comparso questo campo.

TimeBasedDrop

Un Drop ottenuto guardando, in timeBasedDrops.

CampoTipoDescrizione
id, namestringID Twitch e nome del Drop.
startAt, endAtstring (ISO 8601)Periodo in cui il Drop può essere ottenuto.
requiredMinutesWatchednumberMinuti di visione necessari.
requiredSubsnumberAbbonamenti necessari.
repeat{ everyHours, times } | nullAggiunto da questa API: ogni quanto il Drop si ottiene di nuovo, con times (quante volte) e everyHours (24: una volta al giorno; null quando Twitch non lo dice). requiredMinutesWatched è allora il tempo di visione di un periodo. null per un Drop che si ottiene una sola volta.
preconditionDropsunknownDrop da ottenere prima, riportati così come li invia Twitch.
benefitEdges{ benefit: Benefit, entitlementLimit }[]Cosa assegna il Drop, con quante volte può essere riscattato.

Benefit

Un oggetto di gioco, in benefitEdges.

CampoTipoDescrizione
id, namestringID Twitch e nome dell'oggetto.
imageAssetURLstring (URL)Immagine dell'oggetto.
createdAtstring (ISO 8601)Data di creazione dell'oggetto su Twitch.
distributionTypestringCome viene consegnato l'oggetto: DIRECT_ENTITLEMENT per un oggetto di gioco, BADGE per un badge della chat.
entitlementLimitnumberQuante volte l'oggetto può essere riscattato.
isIosAvailablebooleanSe l'oggetto può essere riscattato su iOS.
game, ownerOrganization{ id, name }Gioco ed editore dell'oggetto.

Codici di risposta

StatoDescrizione
200Le campagne attive. Un elenco vuoto è una risposta valida.
304Nulla è cambiato dall'ETag inviato: tieni la tua copia. Gratis, non conta nel tuo limite.
429RATE_LIMITED: Attendi i secondi indicati da Retry-After.
429INVALID_API_KEY_RATE_LIMITED: La chiave non è riconosciuta e il limite anonimo del tuo indirizzo IP è esaurito: correggi la chiave.
503SERVICE_UNAVAILABLE: Nessun elenco ancora caricato (subito dopo un riavvio dell'API): riprova dopo Retry-After. Gratis, non conta nel tuo limite.
Esempio di richiesta
curl https://drops.sunkwi.com/api/twitch/drops
Esempio di risposta · 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" }}

Ottieni le campagne di ricompense

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

Ogni campagna di ricompense attiva (eventi su tutta la piattaforma, badge della chat, ricompense dei partner) in campaigns, accompagnata dall'ora dell'ultima scansione di Twitch e dal tuo limite di richieste.

Corpo della risposta

CampoTipoDescrizione
campaignsRewardCampaign[]Le campagne attive, nell'ordine dell'ultima scansione. Un array vuoto è una risposta valida.
refreshedAtstring (ISO 8601) | nullOra dell'ultima scansione di Twitch riuscita, null prima della prima.
rateLimit{ limit, remaining, resetAt }Il tuo limite su questa route dopo questa chiamata, come lo indicano gli header ratelimit-*: limit richieste per finestra, remaining ancora consentite e resetAt, quando il limite torna intero (ISO 8601).

RewardCampaign

Un elemento di campaigns.

CampoTipoDescrizione
id, name, brandstringID Twitch, nome e marchio della campagna.
statusstringStato al momento della richiesta, ricavato dalle date: UPCOMING prima di startsAt, ACTIVE fino a endsAt, poi EXPIRED.
summary, instructionsstringTesti mostrati da Twitch.
startsAt, endsAtstring (ISO 8601)Periodo di svolgimento della campagna.
image{ image1xURL }Immagine della campagna.
aboutURL, externalURLstring (URL)Pagina di aiuto e pagina esterna della campagna.
isSitewidebooleanSe conta ogni canale, non solo quelli di un gioco.
game{ id, displayName, slug }?Gioco della campagna, se ne ha uno.
rewardValueURLParamstringValore che Twitch aggiunge ai link di riscatto.
unlockRequirements{ minuteWatchedGoal, subsGoal }Minuti di visione e abbonamenti necessari.
rewardGroupsRewardGroup[]?Ricompense ottenute un gruppo alla volta, ogni gruppo con il proprio obiettivo: una ricompensa al giorno è un gruppo al giorno. Solo quando Twitch li invia.
rewardsReward[]Le ricompense della campagna, incluse quelle dei suoi gruppi, ciascuna una sola volta.
firstSeenAtstring (ISO 8601) | nullQuando questa API ha visto la campagna per la prima volta. Una campagna che torna meno di un giorno dopo essere uscita dalla lista mantiene la sua data. null per le campagne che l'API serviva già quando è comparso questo campo.
Campi delle ricompense

RewardGroup

Un gruppo di ricompense di una campagna di ricompense, ottenute insieme.

CampoTipoDescrizione
idstringID Twitch del gruppo.
unlockRequirements{ minuteWatchedGoal, subsGoal, turboSubsGoal?, eventTriggerGoal? }Cosa richiede il gruppo. Twitch vi aggiunge obiettivi Turbo e di eventi.
repeat{ everyHours, times } | nullOgni quanto il gruppo si ottiene di nuovo, come il repeat di un Drop: minuteWatchedGoal è allora il tempo di visione di un periodo. null per un gruppo che si ottiene una sola volta.
categories{ id, displayName, slug }[]Le categorie i cui canali in diretta contano, una qualsiasi; vuoto quando Twitch non ne indica nessuna.
rewardsReward[]Le ricompense del gruppo, elencate anche in rewards della campagna.

Reward

Una ricompensa di una campagna di ricompense.

CampoTipoDescrizione
id, namestringID Twitch e nome della ricompensa.
bannerImage, thumbnailImage{ image1xURL }Immagini della ricompensa.
earnableUntilstring (ISO 8601)Ultimo momento in cui la ricompensa può essere ottenuta.
redemptionInstructions, redemptionURLstringCome riscattare la ricompensa, e dove.

Codici di risposta

StatoDescrizione
200Le campagne attive. Un elenco vuoto è una risposta valida.
304Nulla è cambiato dall'ETag inviato: tieni la tua copia. Gratis, non conta nel tuo limite.
429RATE_LIMITED: Attendi i secondi indicati da Retry-After.
429INVALID_API_KEY_RATE_LIMITED: La chiave non è riconosciuta e il limite anonimo del tuo indirizzo IP è esaurito: correggi la chiave.
503SERVICE_UNAVAILABLE: Nessun elenco ancora caricato (subito dopo un riavvio dell'API): riprova dopo Retry-After. Gratis, non conta nel tuo limite.
Esempio di richiesta
curl https://drops.sunkwi.com/api/twitch/rewards
Esempio di risposta · 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" }}

Ottieni i badge della chat

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

I badge globali della chat di Twitch in badges, un elemento per versione, ciascuno con il modo di ottenerlo quando questa API lo conosce (requirement), accompagnati dall'ora dell'ultima lettura dei badge di Twitch e dal tuo limite di richieste.

Corpo della risposta

CampoTipoDescrizione
badgesBadge[]I badge globali, un elemento per versione. Un array vuoto è una risposta valida.
refreshedAtstring (ISO 8601) | nullOra dell'ultima lettura riuscita dei badge di Twitch (ogni 5 minuti), null prima della prima.
rateLimit{ limit, remaining, resetAt }Il tuo limite su questa route dopo questa chiamata, come lo indicano gli header ratelimit-*: limit richieste per finestra, remaining ancora consentite e resetAt, quando il limite torna intero (ISO 8601).

Badge

Un elemento di badges: una versione di un badge globale della chat, come Twitch lo elenca ora.

CampoTipoDescrizione
setId, versionIdstringIl set di badge e la sua versione: insieme identificano un badge (sub-gifter e 5).
title, descriptionstringIl suo nome e la descrizione di Twitch, in inglese.
imageUrl1x, imageUrl2x, imageUrl4xstring (URL)La sua immagine a 18, 36 e 72 pixel.
clickAction, clickUrlstring | nullCosa fa Twitch quando si clicca sul badge, e il suo link; null quando Twitch non ne fornisce.
firstSeenAtstring (ISO 8601) | nullQuando questa API ha visto il badge per la prima volta. Se torna più di 7 giorni dopo che Twitch l'ha rimosso, prende una nuova data; se torna prima, mantiene la sua. null per i badge già presenti alla sua prima lettura.
requirementBadgeRequirement | nullCome ottenerlo; null quando questa API non lo sa.
Campi di BadgeRequirement

BadgeRequirement

Come ottenere un badge: dalla campagna Drops che lo assegna (DROPS), o dalla descrizione che Twitch stessa dà di un badge abbonato o di visione (TWITCH_DESCRIPTION).

CampoTipoDescrizione
source'DROPS' | 'TWITCH_DESCRIPTION'DROPS o TWITCH_DESCRIPTION.
watchTimeOnlybooleantrue esattamente quando basta guardare: una campagna DROPS che richiede tempo di visione (requiredMinutes maggiore di 0) e nessun abbonamento (requiredSubs 0).
requiredMinutes, requiredSubsnumberI minuti di visione, e gli abbonamenti o abbonamenti regalati, richiesti.
gameId, gameNamestringIl gioco: il suo ID Twitch (null se sconosciuto) e il suo nome.
channels, channelCountstring[] (≤ 5), numberI primi 5 canali che lo assegnano (login) e quanti sono; 0: qualsiasi canale che trasmette il gioco.
startAt, endAtstring (ISO 8601) | nullPeriodo di svolgimento della campagna; null per TWITCH_DESCRIPTION. Una campagna terminata resta.
campaignId, campaignNamestring | nullLa campagna Drops; null per TWITCH_DESCRIPTION.
repeat{ everyHours, times } | nullSolo DROPS: il tempo di visione è richiesto di nuovo a ogni periodo, e requiredMinutes è quello di un periodo, con times e everyHours (20 min al giorno per 3 giorni: times 3, everyHours 24); altrimenti null.
categories{ id, name }[] (≤ 50)Solo DROPS: le categorie i cui canali in diretta contano, una qualsiasi (id e name, al massimo 50); gameId e gameName sono la prima. Altrimenti vuoto.
collection{ chestSize, completeAll } | nullSolo DROPS: il badge è una delle ricompense di una collezione evento, la campagna. chestSize: esce da uno scrigno con altrettante ricompense, una per scrigno, mai a scelta (null: dato così com'è). completeAll: dato per aver completato tutta la collezione, abbonamenti inclusi. Altrimenti null.
evolvesFrom{ setId, versionId } | nullSolo DROPS: il badge da equipaggiare in chat prima di guardare, tramite il suo setId e il suo versionId in questo elenco: un’evoluzione Pokémon chiede il suo stadio precedente (Pikachu: Pichu). Altrimenti null, o se non è noto.

Codici di risposta

StatoDescrizione
200I badge globali. Un elenco vuoto è una risposta valida.
304Nulla è cambiato dall'ETag inviato: tieni la tua copia. Gratis, non conta nel tuo limite.
429RATE_LIMITED: Attendi i secondi indicati da Retry-After.
429INVALID_API_KEY_RATE_LIMITED: La chiave non è riconosciuta e il limite anonimo del tuo indirizzo IP è esaurito: correggi la chiave.
503SERVICE_UNAVAILABLE: Nessun elenco ancora caricato (subito dopo un riavvio dell'API): riprova dopo Retry-After. Gratis, non conta nel tuo limite.
Esempio di richiesta
curl https://drops.sunkwi.com/api/twitch/badges
Caricamento dell'anteprima…

Limiti di richieste

Ogni route ha il suo contatore: chiamare /drops non consuma mai il budget di /rewards o di /badges. Le campagne cambiano una volta al minuto e i badge ogni 5 minuti, quindi interrogare l'API più spesso non porta nulla di nuovo.

ChiamanteLimite per routeConteggiato per
Anonimo1 richiesta ogni 5 minutiIndirizzo IP
Con una chiave API1 richiesta al minuto per impostazione predefinita, di più su richiestaChiave API

Header della risposta

Header letti e inviati dall'API.

HeaderDirezioneDescrizione
x-last-updated-atresponseOra dell'ultima lettura di Twitch riuscita: la scansione per /drops e /rewards, i badge per /badges.
x-refresh-interval-secondsresponseSecondi tra due letture di Twitch: chiedere più spesso restituisce gli stessi dati (60 per /drops e /rewards, 300 per /badges).
ratelimit-limitresponseRichieste consentite nella finestra, per questa route.
ratelimit-remainingresponseRichieste rimanenti nella finestra corrente.
ratelimit-resetresponseSecondi prima che una richiesta sia di nuovo consentita.
ratelimit-policyresponseLa policy, nel formato <limite>;w=<finestra in secondi>.
retry-afterresponseSecondi da attendere prima di riprovare, in caso di risposta 429 o 503.
x-api-keyrequestLa tua chiave API: facoltativa su ogni route.
x-api-key-statusresponseinvalid quando la chiave inviata è sconosciuta, revocata o disattivata: la chiamata è stata conteggiata come anonima, nel limite del tuo indirizzo IP.
etagresponseEtichetta di questa risposta. Rimandala in If-None-Match: finché i dati non cambiano, la risposta è un 304 che non conta nel tuo limite.
if-none-matchrequestL'ETag della tua ultima risposta, facoltativo: una lista invariata risponde 304 Not Modified, gratis.
Una seconda chiamata anonima entro 5 minuti
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" }

Errori

Gli errori restituiscono un corpo JSON con un codice stabile: { "code": "RATE_LIMITED" }. I codici non cambiano mai: basati su code, non su un messaggio.

StatoCodiceDescrizione
429RATE_LIMITEDTroppe richieste su questa route: attendi i secondi indicati da Retry-After.
429INVALID_API_KEY_RATE_LIMITEDTroppe richieste, e l'header X-API-Key contiene una chiave sconosciuta, revocata o disattivata: la chiamata è stata conteggiata come anonima. Correggi la chiave, o attendi i secondi indicati da Retry-After.
503SERVICE_UNAVAILABLENessun elenco ancora caricato (subito dopo un riavvio dell'API). Non viene consumato nulla: riprova dopo i secondi indicati da Retry-After.
404NOT_FOUNDLa route non esiste.
500INTERNAL_SERVER_ERRORErrore del server: riprova più tardi.
Esempio di errore
HTTP/1.1 404 Not Foundcontent-type: application/json; charset=utf-8
{ "code": "NOT_FOUND" }

Dal sito all'API

Ogni pagina di questo sito legge queste stesse route. Ecco dove si trova, nelle risposte, ciò che mostra ogni pagina.

PaginaRouteDove nella risposta
Drops/drops/dropsgames: un elemento per gioco, con le sue campagne in rewards. La vista a griglia disegna startAt e endAt di ogni campagna.
Una pagina gioco/drops/<game>/dropsUn elemento di games, identificato tramite gameId. Ogni campagna è games[i].rewards[j]; le sue ricompense sono i benefitEdges di timeBasedDrops, con requiredMinutesWatched.
Ricompense/rewards/rewardscampaigns: un elemento per campagna di ricompense, con le sue ricompense in rewards e ciò che richiede in unlockRequirements.
Una pagina campagna di ricompense/rewards/<campaign>/rewardsUn elemento di campaigns, identificato tramite id; le sue ricompense sono in rewards.
Badge/badges/badgesbadges: tutti gli elementi, prima quelli con un requirement, con il modo di ottenerli. La vista a griglia disegna requirement.startAt e requirement.endAt di ogni badge.
Una pagina badge/badges/<badge>/badgesUn elemento di badges, identificato tramite setId e versionId; «Come si ottiene» è il suo requirement.