Pular para o conteúdo
Twitch Drops API

Referência da Twitch Drops API

Uma API JSON gratuita que lista todas as campanhas de Twitch Drops e de recompensas ativas, atualizada a cada minuto, e os emblemas globais do chat da Twitch. Chame-a anonimamente ou com uma chave de API gratuita para ter um limite maior.

URL basehttps://drops.sunkwi.com/api/twitch
Obtenha uma chave de API gratuitaLer a referência

Experimente

Anônimo: 1 requisição a cada 5 minutos por rota. Com uma chave: 1 por minuto.

GET
Carregando a prévia…
Navegar

Rotas

Toda rota responde em JSON a uma requisição GET, e navegadores de qualquer site podem chamar a API (CORS). Nem /drops, nem /rewards, nem /badges exigem cadastro; uma chave de API gratuita aumenta o limite em cada uma.

As três rotas respondem do mesmo jeito: a lista, o horário da última leitura da Twitch (refreshedAt) e seu limite de requisições (rateLimit).

RotaDescrição
GET /dropsCampanhas de Drops por jogo. Todas as campanhas de Drops ativas, agrupadas por jogo, em games: um item por jogo, com suas campanhas em rewards.
GET /rewardsCampanhas de recompensas. Todas as campanhas de recompensas ativas (eventos em toda a Twitch, emblemas de chat, recompensas de parceiros), em campaigns.
GET /badgesEmblemas globais do chat. Os emblemas globais do chat da Twitch, um item por versão em badges, com o jeito de ganhá-los quando se sabe.

Autenticação

A leitura de /drops, /rewards e /badges não exige conta nem chave. Chamadas anônimas são contadas por endereço IP: 1 requisição a cada 5 minutos em cada rota.

As chaves são gratuitas: entre com Discord, Twitch ou GitHub, crie uma no painel e envie-a no cabeçalho X-API-Key. Uma chave aumenta seu limite para 1 requisição por minuto por padrão, ou mais sob pedido, e mostra seu tráfego.

Cabeçalho da requisição

CabeçalhoValorDescrição
X-API-Keyjdk_…Sua chave de API: opcional em todas as rotas. Uma chave desconhecida, revogada ou desativada nunca é recusada: a chamada conta como anônima, e x-api-key-status: invalid indica isso.
Exemplo de requisição · 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

Obtenha uma chave de API gratuita

A chave é gratuita. Ela aumenta seu limite de 1 requisição a cada 5 minutos para 1 requisição por minuto em cada rota, e seu painel mostra o tráfego dela.

  1. Entre com Discord, Twitch ou GitHub: sem senha, sem formulário.
  2. Abra Chaves de API no seu painel e crie uma chave com o nome do seu bot ou site.
  3. Copie a chave quando ela aparecer (só uma vez) e envie-a no cabeçalho X-API-Key, a partir do seu servidor.

Obter campanhas de Drops

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

Todas as campanhas de Drops ativas, agrupadas por jogo: um item de games por jogo, com suas campanhas em rewards, junto com o horário da última verificação da Twitch e seu limite de requisições.

Corpo da resposta

CampoTipoDescrição
gamesGame[]As campanhas ativas, na ordem da última verificação. Um array vazio é uma resposta válida.
refreshedAtstring (ISO 8601) | nullHorário da última verificação bem-sucedida da Twitch, null antes da primeira.
rateLimit{ limit, remaining, resetAt }Seu limite nesta rota depois desta chamada, como os cabeçalhos ratelimit-* informam: limit requisições por janela, remaining ainda permitidas e resetAt, quando o limite volta por inteiro (ISO 8601).

Game

Um item de games.

CampoTipoDescrição
gameIdstringID do jogo na Twitch.
gameDisplayNamestringNome do jogo.
gameBoxArtURLstring (URL)Capa do jogo, 120×160.
startAtstring (ISO 8601)Início da primeira campanha do jogo.
endAtstring (ISO 8601)Fim da última campanha do jogo.
rewardsDropCampaign[]As campanhas de Drops do jogo.
Campos de DropCampaign, TimeBasedDrop e Benefit

DropCampaign

Uma campanha de Drops, em rewards de um jogo.

CampoTipoDescrição
idstringID da campanha na Twitch.
name, descriptionstringNome e descrição definidos pela publicadora.
owner{ id, name }Publicadora responsável pela campanha.
game{ id, displayName, slug }Jogo da campanha.
statusstringStatus na Twitch, ACTIVE para uma campanha em andamento.
startAt, endAtstring (ISO 8601)Período de duração da campanha.
imageURLstring (URL)Arte da campanha.
detailsURL, accountLinkURLstring (URL)Página de detalhes e página de vinculação de conta da publicadora.
allow{ isEnabled, channels? }Canais autorizados a dar os Drops quando isEnabled é true; caso contrário, qualquer canal transmitindo o jogo. displayName pode ser null ou estar ausente.
timeBasedDropsTimeBasedDrop[]Drops ganhos assistindo.
eventBasedDropsunknown[]Drops ganhos por eventos, repassados como a Twitch os envia.
firstSeenAtstring (ISO 8601) | nullQuando esta API viu a campanha pela primeira vez. Uma campanha que volta menos de um dia depois de sair da lista mantém a sua data. null para as campanhas que a API já servia quando este campo surgiu.

TimeBasedDrop

Um Drop ganho assistindo, em timeBasedDrops.

CampoTipoDescrição
id, namestringID e nome do Drop na Twitch.
startAt, endAtstring (ISO 8601)Período em que o Drop pode ser ganho.
requiredMinutesWatchednumberMinutos assistidos necessários.
requiredSubsnumberInscrições necessárias.
repeat{ everyHours, times } | nullAdicionado por esta API: com que frequência o Drop pode ser ganho de novo, com times (quantas vezes) e everyHours (24: uma vez por dia; null quando a Twitch não informa). requiredMinutesWatched é então o tempo assistido de um período. null para um Drop ganho uma só vez.
preconditionDropsunknownDrops a ganhar antes, repassados como a Twitch os envia.
benefitEdges{ benefit: Benefit, entitlementLimit }[]O que o Drop dá, com quantas vezes pode ser resgatado.

Benefit

Um item no jogo, em benefitEdges.

CampoTipoDescrição
id, namestringID e nome do item na Twitch.
imageAssetURLstring (URL)Imagem do item.
createdAtstring (ISO 8601)Data de criação do item na Twitch.
distributionTypestringComo o item é entregue: DIRECT_ENTITLEMENT para um item no jogo, BADGE para um emblema de chat.
entitlementLimitnumberQuantas vezes o item pode ser resgatado.
isIosAvailablebooleanSe o item pode ser resgatado no iOS.
game, ownerOrganization{ id, name }Jogo e publicadora do item.

Códigos de resposta

StatusDescrição
200As campanhas ativas. Uma lista vazia é uma resposta válida.
304Nada mudou desde o ETag enviado: mantenha sua cópia. Grátis, não conta no seu limite.
429RATE_LIMITED: Espere os segundos indicados por Retry-After.
429INVALID_API_KEY_RATE_LIMITED: A chave não foi reconhecida e o limite anônimo do seu endereço IP se esgotou: corrija a chave.
503SERVICE_UNAVAILABLE: Nenhuma lista carregada ainda (logo após um reinício da API): tente de novo depois do Retry-After. Grátis, não conta no seu limite.
Exemplo de requisição
curl https://drops.sunkwi.com/api/twitch/drops
Exemplo de resposta · 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" }}

Obter campanhas de recompensas

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

Todas as campanhas de recompensas ativas (eventos em toda a Twitch, emblemas de chat, recompensas de parceiros) em campaigns, junto com o horário da última verificação da Twitch e seu limite de requisições.

Corpo da resposta

CampoTipoDescrição
campaignsRewardCampaign[]As campanhas ativas, na ordem da última verificação. Um array vazio é uma resposta válida.
refreshedAtstring (ISO 8601) | nullHorário da última verificação bem-sucedida da Twitch, null antes da primeira.
rateLimit{ limit, remaining, resetAt }Seu limite nesta rota depois desta chamada, como os cabeçalhos ratelimit-* informam: limit requisições por janela, remaining ainda permitidas e resetAt, quando o limite volta por inteiro (ISO 8601).

RewardCampaign

Um item de campaigns.

CampoTipoDescrição
id, name, brandstringID, nome e marca da campanha na Twitch.
statusstringStatus no momento da requisição, calculado pelas datas: UPCOMING antes de startsAt, ACTIVE até endsAt e depois EXPIRED.
summary, instructionsstringTextos exibidos pela Twitch.
startsAt, endsAtstring (ISO 8601)Período de duração da campanha.
image{ image1xURL }Arte da campanha.
aboutURL, externalURLstring (URL)Página de ajuda e página externa da campanha.
isSitewidebooleanSe todos os canais contam, não só os de um jogo.
game{ id, displayName, slug }?Jogo da campanha, quando ela tem um.
rewardValueURLParamstringValor que a Twitch adiciona aos links de resgate.
unlockRequirements{ minuteWatchedGoal, subsGoal }Minutos assistidos e inscrições necessários.
rewardGroupsRewardGroup[]?Recompensas ganhas um grupo por vez, cada grupo com sua própria meta: uma recompensa por dia é um grupo por dia. Só quando a Twitch os envia.
rewardsReward[]As recompensas da campanha, incluindo as dos seus grupos, cada uma listada uma única vez.
firstSeenAtstring (ISO 8601) | nullQuando esta API viu a campanha pela primeira vez. Uma campanha que volta menos de um dia depois de sair da lista mantém a sua data. null para as campanhas que a API já servia quando este campo surgiu.
Campos de recompensas

RewardGroup

Um grupo de recompensas de uma campanha de recompensas, ganhas juntas.

CampoTipoDescrição
idstringID do grupo na Twitch.
unlockRequirements{ minuteWatchedGoal, subsGoal, turboSubsGoal?, eventTriggerGoal? }O que o grupo exige. A Twitch adiciona ali metas do Turbo e de eventos.
repeat{ everyHours, times } | nullCom que frequência o grupo pode ser ganho de novo, como o repeat de um Drop: minuteWatchedGoal é então o tempo assistido de um período. null para um grupo ganho uma só vez.
categories{ id, displayName, slug }[]As categorias cujos canais ao vivo contam, qualquer uma delas; vazio quando a Twitch não indica nenhuma.
rewardsReward[]As recompensas do grupo, também listadas em rewards da campanha.

Reward

Uma recompensa de uma campanha de recompensas.

CampoTipoDescrição
id, namestringID e nome da recompensa na Twitch.
bannerImage, thumbnailImage{ image1xURL }Imagens da recompensa.
earnableUntilstring (ISO 8601)Último momento em que a recompensa pode ser ganha.
redemptionInstructions, redemptionURLstringComo resgatar a recompensa, e onde.

Códigos de resposta

StatusDescrição
200As campanhas ativas. Uma lista vazia é uma resposta válida.
304Nada mudou desde o ETag enviado: mantenha sua cópia. Grátis, não conta no seu limite.
429RATE_LIMITED: Espere os segundos indicados por Retry-After.
429INVALID_API_KEY_RATE_LIMITED: A chave não foi reconhecida e o limite anônimo do seu endereço IP se esgotou: corrija a chave.
503SERVICE_UNAVAILABLE: Nenhuma lista carregada ainda (logo após um reinício da API): tente de novo depois do Retry-After. Grátis, não conta no seu limite.
Exemplo de requisição
curl https://drops.sunkwi.com/api/twitch/rewards
Exemplo de resposta · 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" }}

Obter emblemas do chat

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

Os emblemas globais do chat da Twitch em badges, um item por versão, cada um com o jeito de ganhá-lo quando esta API sabe (requirement), junto com o horário da última leitura dos emblemas da Twitch e seu limite de requisições.

Corpo da resposta

CampoTipoDescrição
badgesBadge[]Os emblemas globais, um item por versão. Um array vazio é uma resposta válida.
refreshedAtstring (ISO 8601) | nullHorário da última leitura bem-sucedida dos emblemas da Twitch (a cada 5 minutos), null antes da primeira.
rateLimit{ limit, remaining, resetAt }Seu limite nesta rota depois desta chamada, como os cabeçalhos ratelimit-* informam: limit requisições por janela, remaining ainda permitidas e resetAt, quando o limite volta por inteiro (ISO 8601).

Badge

Um item de badges: uma versão de um emblema global do chat, como a Twitch o lista agora.

CampoTipoDescrição
setId, versionIdstringO conjunto de emblemas e sua versão: juntos, eles identificam um emblema (sub-gifter e 5).
title, descriptionstringSeu nome e a descrição da Twitch, em inglês.
imageUrl1x, imageUrl2x, imageUrl4xstring (URL)Sua imagem em 18, 36 e 72 pixels.
clickAction, clickUrlstring | nullO que a Twitch faz quando o emblema é clicado, e seu link; null quando a Twitch não informa nenhum.
firstSeenAtstring (ISO 8601) | nullQuando esta API viu o emblema pela primeira vez. Se ele voltar mais de 7 dias depois que a Twitch o removeu, ganha uma nova data; se voltar antes, mantém a que tinha. null para os emblemas que já existiam na primeira leitura dela.
requirementBadgeRequirement | nullComo ganhá-lo; null quando esta API não sabe.
Campos de BadgeRequirement

BadgeRequirement

Como ganhar um emblema: pela campanha de Drops que o oferece (DROPS), ou pela própria descrição da Twitch de um emblema de inscrito ou de visualização (TWITCH_DESCRIPTION).

CampoTipoDescrição
source'DROPS' | 'TWITCH_DESCRIPTION'DROPS ou TWITCH_DESCRIPTION.
watchTimeOnlybooleantrue exatamente quando basta assistir: uma campanha DROPS que exige tempo assistido (requiredMinutes acima de 0) e nenhuma inscrição (requiredSubs 0).
requiredMinutes, requiredSubsnumberOs minutos assistidos, e as inscrições ou inscrições presenteadas, que ela exige.
gameId, gameNamestringO jogo: seu ID na Twitch (null quando desconhecido) e seu nome.
channels, channelCountstring[] (≤ 5), numberOs 5 primeiros canais que o oferecem (logins) e quantos são; 0: qualquer canal transmitindo o jogo.
startAt, endAtstring (ISO 8601) | nullPeríodo da campanha; null para TWITCH_DESCRIPTION. Uma campanha encerrada continua.
campaignId, campaignNamestring | nullA campanha de Drops; null para TWITCH_DESCRIPTION.
repeat{ everyHours, times } | nullSó DROPS: o tempo assistido é exigido de novo a cada período, e requiredMinutes é o de um período, com times e everyHours (20 min por dia durante 3 dias: times 3, everyHours 24); senão null.
categories{ id, name }[] (≤ 50)Só DROPS: as categorias cujos canais ao vivo contam, qualquer uma delas (id e name, no máximo 50); gameId e gameName são a primeira. Senão vazio.
collection{ chestSize, completeAll } | nullSó DROPS: o emblema é uma das recompensas de uma coleção de evento, a campanha. chestSize: ele sai de um baú com essa quantidade de recompensas, uma por baú, nunca à escolha (null: dado diretamente). completeAll: dado por completar a coleção inteira, inscrições incluídas. Senão null.
evolvesFrom{ setId, versionId } | nullSó DROPS: o emblema que você precisa equipar no chat antes de assistir, pelo setId e versionId dele nesta lista: uma evolução de Pokémon pede o estágio anterior (Pikachu: Pichu). null nos outros casos, ou quando desconhecido.

Códigos de resposta

StatusDescrição
200Os emblemas globais. Uma lista vazia é uma resposta válida.
304Nada mudou desde o ETag enviado: mantenha sua cópia. Grátis, não conta no seu limite.
429RATE_LIMITED: Espere os segundos indicados por Retry-After.
429INVALID_API_KEY_RATE_LIMITED: A chave não foi reconhecida e o limite anônimo do seu endereço IP se esgotou: corrija a chave.
503SERVICE_UNAVAILABLE: Nenhuma lista carregada ainda (logo após um reinício da API): tente de novo depois do Retry-After. Grátis, não conta no seu limite.
Exemplo de requisição
curl https://drops.sunkwi.com/api/twitch/badges
Carregando a prévia…

Limites de requisições

Cada rota tem seu próprio contador: chamar /drops nunca gasta a cota de /rewards nem a de /badges. As campanhas mudam uma vez por minuto e os emblemas a cada 5 minutos, então consultar com mais frequência não traz nada novo.

ClienteLimite por rotaContado por
Anônimo1 requisição a cada 5 minutosEndereço IP
Com uma chave de API1 requisição por minuto por padrão, ou mais sob pedidoChave de API

Cabeçalhos da resposta

Cabeçalhos lidos e enviados pela API.

CabeçalhoDireçãoDescrição
x-last-updated-atresponseHorário da última leitura bem-sucedida da Twitch: a verificação para /drops e /rewards, os emblemas para /badges.
x-refresh-interval-secondsresponseSegundos entre duas leituras da Twitch: consultar com mais frequência retorna os mesmos dados (60 para /drops e /rewards, 300 para /badges).
ratelimit-limitresponseRequisições permitidas na janela, para esta rota.
ratelimit-remainingresponseRequisições restantes na janela atual.
ratelimit-resetresponseSegundos até uma requisição ser permitida de novo.
ratelimit-policyresponseA política, no formato <limite>;w=<janela em segundos>.
retry-afterresponseSegundos de espera antes de tentar de novo, em uma resposta 429 ou 503.
x-api-keyrequestSua chave de API: opcional em todas as rotas.
x-api-key-statusresponseinvalid quando a chave enviada é desconhecida, revogada ou desativada: a chamada contou como anônima, no limite do seu endereço IP.
etagresponseEtiqueta desta resposta. Envie-a de volta em If-None-Match: enquanto os dados não mudarem, a resposta é um 304 que não conta no seu limite.
if-none-matchrequestO ETag da sua última resposta, opcional: uma lista inalterada responde 304 Not Modified, de graça.
Uma segunda chamada anônima em menos de 5 minutos
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" }

Erros

Os erros respondem com um corpo JSON contendo um código estável: { "code": "RATE_LIMITED" }. Os códigos nunca mudam: baseie-se em code, não em uma mensagem.

StatusCódigoDescrição
429RATE_LIMITEDRequisições demais nesta rota: espere os segundos indicados por Retry-After.
429INVALID_API_KEY_RATE_LIMITEDRequisições demais, e o cabeçalho X-API-Key contém uma chave desconhecida, revogada ou desativada: a chamada contou como anônima. Corrija a chave ou espere os segundos indicados por Retry-After.
503SERVICE_UNAVAILABLENenhuma lista carregada ainda (logo após um reinício da API). Nada é gasto: tente de novo depois dos segundos indicados por Retry-After.
404NOT_FOUNDA rota não existe.
500INTERNAL_SERVER_ERRORO servidor falhou: tente de novo mais tarde.
Exemplo de erro
HTTP/1.1 404 Not Foundcontent-type: application/json; charset=utf-8
{ "code": "NOT_FOUND" }

Do site para a API

Todas as páginas deste site leem estas mesmas rotas. Veja onde fica, nas respostas, o que cada página mostra.

PáginaRotaOnde na resposta
Drops/drops/dropsgames: um item por jogo, com suas campanhas em rewards. A visualização em grade desenha startAt e endAt de cada campanha.
A página de um jogo/drops/<game>/dropsUm item de games, identificado por gameId. Cada campanha é games[i].rewards[j]; suas recompensas são os benefitEdges de timeBasedDrops, com requiredMinutesWatched.
Recompensas/rewards/rewardscampaigns: um item por campanha de recompensas, com suas recompensas em rewards e o que ela exige em unlockRequirements.
A página de uma campanha de recompensas/rewards/<campaign>/rewardsUm item de campaigns, identificado por id; suas recompensas ficam em rewards.
Emblemas/badges/badgesbadges: todos os itens, primeiro os que têm requirement, com o jeito de ganhá-los. A visualização em grade desenha requirement.startAt e requirement.endAt de cada emblema.
A página de um emblema/badges/<badge>/badgesUm item de badges, identificado por setId e versionId; “Como ganhar” é o seu requirement.