Saltar al contenido
Twitch Drops API

Referencia de la Twitch Drops API

Una API JSON gratuita con todas las campañas de Twitch Drops y de recompensas activas, actualizada cada minuto, y las insignias globales del chat de Twitch. Llámala de forma anónima o con una clave de API gratuita para tener un límite más alto.

URL basehttps://drops.sunkwi.com/api/twitch
Consigue una clave de API gratisLeer la referencia

Pruébala

Anónimo: 1 solicitud cada 5 minutos por ruta. Con clave: 1 por minuto.

GET
Cargando la vista previa…
Explorar

Rutas

Todas las rutas responden en JSON a una solicitud GET, y los navegadores de cualquier sitio pueden llamar a la API (CORS). Ni /drops, ni /rewards ni /badges requieren registro; una clave de API gratuita sube el límite en cada una.

Las tres rutas responden igual: la lista, la hora de la última lectura de Twitch (refreshedAt) y tu límite de uso (rateLimit).

RutaDescripción
GET /dropsCampañas de Drops por juego. Todas las campañas de Drops activas, agrupadas por juego, en games: un elemento por juego, con sus campañas en rewards.
GET /rewardsCampañas de recompensas. Todas las campañas de recompensas activas (eventos en todo Twitch, insignias de chat, recompensas de socios), en campaigns.
GET /badgesInsignias globales del chat. Las insignias globales del chat de Twitch, un elemento por versión en badges, con cómo conseguirlas cuando se sabe.

Autenticación

Para leer /drops, /rewards y /badges no hace falta cuenta ni clave. Las llamadas anónimas se cuentan por dirección IP: 1 solicitud cada 5 minutos en cada ruta.

Las claves son gratuitas: inicia sesión con Discord, Twitch o GitHub, crea una en el panel y envíala en la cabecera X-API-Key. Una clave sube tu límite a 1 solicitud por minuto por defecto, ampliable si lo pides, y te muestra tu tráfico.

Cabecera de solicitud

CabeceraValorDescripción
X-API-Keyjdk_…Tu clave de API: opcional en todas las rutas. Una clave desconocida, revocada o desactivada nunca se rechaza: la llamada cuenta como anónima, y x-api-key-status: invalid lo indica.
Ejemplo de solicitud · 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

Consigue una clave de API gratis

Una clave es gratuita. Sube tu límite de 1 solicitud cada 5 minutos a 1 solicitud por minuto en cada ruta, y tu panel muestra su tráfico.

  1. Inicia sesión con Discord, Twitch o GitHub: sin contraseña ni formularios.
  2. Abre Claves de API en tu panel y crea una clave con el nombre de tu bot o de tu sitio.
  3. Copia la clave cuando se muestre (solo una vez) y envíala en la cabecera X-API-Key desde tu servidor.

Obtener campañas de Drops

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

Todas las campañas de Drops activas, agrupadas por juego: un elemento de games por juego, con sus campañas en rewards, junto con la hora del último escaneo de Twitch y tu límite de uso.

Cuerpo de la respuesta

CampoTipoDescripción
gamesGame[]Las campañas activas, en el orden del último escaneo. Un array vacío es una respuesta válida.
refreshedAtstring (ISO 8601) | nullHora del último escaneo correcto de Twitch, null antes del primero.
rateLimit{ limit, remaining, resetAt }Tu límite en esta ruta después de esta llamada, tal como lo indican las cabeceras ratelimit-*: limit solicitudes por ventana, remaining todavía permitidas y resetAt, cuándo vuelve el límite completo (ISO 8601).

Game

Un elemento de games.

CampoTipoDescripción
gameIdstringID de Twitch del juego.
gameDisplayNamestringNombre del juego.
gameBoxArtURLstring (URL)Portada del juego, 120×160.
startAtstring (ISO 8601)Inicio de la primera campaña del juego.
endAtstring (ISO 8601)Fin de la última campaña del juego.
rewardsDropCampaign[]Las campañas de Drops del juego.
Campos de DropCampaign, TimeBasedDrop y Benefit

DropCampaign

Una campaña de Drops, en rewards de un juego.

CampoTipoDescripción
idstringID de Twitch de la campaña.
name, descriptionstringNombre y descripción que da el editor.
owner{ id, name }Editor que organiza la campaña.
game{ id, displayName, slug }Juego de la campaña.
statusstringEstado de Twitch, ACTIVE para una campaña en curso.
startAt, endAtstring (ISO 8601)Periodo de la campaña.
imageURLstring (URL)Imagen de la campaña.
detailsURL, accountLinkURLstring (URL)Página de detalles y página de vinculación de cuenta del editor.
allow{ isEnabled, channels? }Canales autorizados a dar los Drops cuando isEnabled es true; si no, cualquier canal que emita el juego. displayName puede ser null o no estar.
timeBasedDropsTimeBasedDrop[]Drops que se consiguen viendo streams.
eventBasedDropsunknown[]Drops que se consiguen con eventos, tal como los envía Twitch.
firstSeenAtstring (ISO 8601) | nullCuándo vio esta API la campaña por primera vez. Una campaña que vuelve menos de un día después de salir de la lista conserva su fecha. null para las campañas que ya servía cuando apareció este campo.

TimeBasedDrop

Un Drop que se consigue viendo streams, en timeBasedDrops.

CampoTipoDescripción
id, namestringID de Twitch y nombre del Drop.
startAt, endAtstring (ISO 8601)Periodo durante el que se puede conseguir el Drop.
requiredMinutesWatchednumberMinutos de visualización necesarios.
requiredSubsnumberSuscripciones necesarias.
repeat{ everyHours, times } | nullAñadido por esta API: cada cuánto se vuelve a ganar el Drop, con times (cuántas veces) y everyHours (24: una vez al día; null cuando Twitch no lo indica). requiredMinutesWatched es entonces el tiempo de visualización de un periodo. null para un Drop que se gana una sola vez.
preconditionDropsunknownDrops que hay que conseguir antes, tal como los envía Twitch.
benefitEdges{ benefit: Benefit, entitlementLimit }[]Lo que da el Drop y cuántas veces se puede reclamar.

Benefit

Un objeto del juego, en benefitEdges.

CampoTipoDescripción
id, namestringID de Twitch y nombre del objeto.
imageAssetURLstring (URL)Imagen del objeto.
createdAtstring (ISO 8601)Fecha de creación del objeto en Twitch.
distributionTypestringCómo se entrega el objeto: DIRECT_ENTITLEMENT para un objeto del juego, BADGE para una insignia de chat.
entitlementLimitnumberCuántas veces se puede reclamar el objeto.
isIosAvailablebooleanSi el objeto se puede reclamar en iOS.
game, ownerOrganization{ id, name }Juego y editor del objeto.

Códigos de respuesta

EstadoDescripción
200Las campañas activas. Una lista vacía es una respuesta válida.
304Nada ha cambiado desde el ETag que enviaste: conserva tu copia. Gratis, no cuenta en tu límite.
429RATE_LIMITED: Espera los segundos que indica Retry-After.
429INVALID_API_KEY_RATE_LIMITED: La clave no se reconoce y el límite anónimo de tu dirección IP está agotado: corrige la clave.
503SERVICE_UNAVAILABLE: Aún no hay lista cargada (justo después de un reinicio de la API): reintenta tras Retry-After. Gratis, no cuenta en tu límite.
Ejemplo de solicitud
curl https://drops.sunkwi.com/api/twitch/drops
Ejemplo de respuesta · 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" }}

Obtener campañas de recompensas

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

Todas las campañas de recompensas activas (eventos en todo Twitch, insignias de chat, recompensas de socios) en campaigns, junto con la hora del último escaneo de Twitch y tu límite de uso.

Cuerpo de la respuesta

CampoTipoDescripción
campaignsRewardCampaign[]Las campañas activas, en el orden del último escaneo. Un array vacío es una respuesta válida.
refreshedAtstring (ISO 8601) | nullHora del último escaneo correcto de Twitch, null antes del primero.
rateLimit{ limit, remaining, resetAt }Tu límite en esta ruta después de esta llamada, tal como lo indican las cabeceras ratelimit-*: limit solicitudes por ventana, remaining todavía permitidas y resetAt, cuándo vuelve el límite completo (ISO 8601).

RewardCampaign

Un elemento de campaigns.

CampoTipoDescripción
id, name, brandstringID de Twitch, nombre y marca de la campaña.
statusstringEstado en el momento de la solicitud, según las fechas: UPCOMING antes de startsAt, ACTIVE hasta endsAt y luego EXPIRED.
summary, instructionsstringTextos que muestra Twitch.
startsAt, endsAtstring (ISO 8601)Periodo de la campaña.
image{ image1xURL }Imagen de la campaña.
aboutURL, externalURLstring (URL)Página de ayuda y página externa de la campaña.
isSitewidebooleanSi cuentan todos los canales, no solo los de un juego.
game{ id, displayName, slug }?Juego de la campaña, si lo tiene.
rewardValueURLParamstringValor que Twitch añade a los enlaces de canje.
unlockRequirements{ minuteWatchedGoal, subsGoal }Minutos de visualización y suscripciones necesarios.
rewardGroupsRewardGroup[]?Recompensas que se consiguen grupo a grupo, cada grupo con su propio objetivo: una recompensa al día es un grupo al día. Solo cuando Twitch los envía.
rewardsReward[]Las recompensas de la campaña, incluidas las de sus grupos, cada una una sola vez.
firstSeenAtstring (ISO 8601) | nullCuándo vio esta API la campaña por primera vez. Una campaña que vuelve menos de un día después de salir de la lista conserva su fecha. null para las campañas que ya servía cuando apareció este campo.
Campos de las recompensas

RewardGroup

Un grupo de recompensas de una campaña de recompensas, que se consiguen juntas.

CampoTipoDescripción
idstringID de Twitch del grupo.
unlockRequirements{ minuteWatchedGoal, subsGoal, turboSubsGoal?, eventTriggerGoal? }Lo que pide el grupo. Twitch añade ahí objetivos de Turbo y de eventos.
repeat{ everyHours, times } | nullCada cuánto se vuelve a ganar el grupo, como el repeat de un Drop: minuteWatchedGoal es entonces el tiempo de visualización de un periodo. null para un grupo que se gana una sola vez.
categories{ id, displayName, slug }[]Las categorías cuyos canales en directo cuentan, cualquiera de ellas; vacío cuando Twitch no nombra ninguna.
rewardsReward[]Las recompensas del grupo, que también aparecen en rewards de la campaña.

Reward

Una recompensa de una campaña de recompensas.

CampoTipoDescripción
id, namestringID de Twitch y nombre de la recompensa.
bannerImage, thumbnailImage{ image1xURL }Imágenes de la recompensa.
earnableUntilstring (ISO 8601)Último momento para conseguir la recompensa.
redemptionInstructions, redemptionURLstringCómo y dónde canjear la recompensa.

Códigos de respuesta

EstadoDescripción
200Las campañas activas. Una lista vacía es una respuesta válida.
304Nada ha cambiado desde el ETag que enviaste: conserva tu copia. Gratis, no cuenta en tu límite.
429RATE_LIMITED: Espera los segundos que indica Retry-After.
429INVALID_API_KEY_RATE_LIMITED: La clave no se reconoce y el límite anónimo de tu dirección IP está agotado: corrige la clave.
503SERVICE_UNAVAILABLE: Aún no hay lista cargada (justo después de un reinicio de la API): reintenta tras Retry-After. Gratis, no cuenta en tu límite.
Ejemplo de solicitud
curl https://drops.sunkwi.com/api/twitch/rewards
Ejemplo de respuesta · 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" }}

Obtener insignias del chat

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

Las insignias globales del chat de Twitch en badges, un elemento por versión, cada una con cómo conseguirla cuando esta API lo sabe (requirement), junto con la hora de la última lectura de las insignias de Twitch y tu límite de uso.

Cuerpo de la respuesta

CampoTipoDescripción
badgesBadge[]Las insignias globales, un elemento por versión. Un array vacío es una respuesta válida.
refreshedAtstring (ISO 8601) | nullHora de la última lectura correcta de las insignias de Twitch (cada 5 minutos), null antes de la primera.
rateLimit{ limit, remaining, resetAt }Tu límite en esta ruta después de esta llamada, tal como lo indican las cabeceras ratelimit-*: limit solicitudes por ventana, remaining todavía permitidas y resetAt, cuándo vuelve el límite completo (ISO 8601).

Badge

Un elemento de badges: una versión de una insignia global del chat, tal como la lista Twitch ahora.

CampoTipoDescripción
setId, versionIdstringEl conjunto de insignias y su versión: juntos identifican una insignia (sub-gifter y 5).
title, descriptionstringSu nombre y la descripción de Twitch, en inglés.
imageUrl1x, imageUrl2x, imageUrl4xstring (URL)Su imagen a 18, 36 y 72 píxeles.
clickAction, clickUrlstring | nullLo que hace Twitch al hacer clic en la insignia, y su enlace; null cuando Twitch no da ninguno.
firstSeenAtstring (ISO 8601) | nullCuándo vio esta API la insignia por primera vez. Si vuelve más de 7 días después de que Twitch la retirara, recibe una fecha nueva; si vuelve antes, conserva la que tenía. null para las insignias que ya estaban en su primera lectura.
requirementBadgeRequirement | nullCómo conseguirla; null cuando esta API no lo sabe.
Campos de BadgeRequirement

BadgeRequirement

Cómo conseguir una insignia: con la campaña de Drops que la da (DROPS), o según la propia descripción de Twitch de una insignia de suscripción o de visualización (TWITCH_DESCRIPTION).

CampoTipoDescripción
source'DROPS' | 'TWITCH_DESCRIPTION'DROPS o TWITCH_DESCRIPTION.
watchTimeOnlybooleantrue exactamente cuando basta con ver: una campaña DROPS que pide tiempo de visualización (requiredMinutes mayor que 0) y ninguna suscripción (requiredSubs 0).
requiredMinutes, requiredSubsnumberLos minutos de visualización, y las suscripciones o suscripciones regaladas, que pide.
gameId, gameNamestringEl juego: su ID de Twitch (null si se desconoce) y su nombre.
channels, channelCountstring[] (≤ 5), numberLos 5 primeros canales que la dan (logins) y cuántos son; 0: cualquier canal que emita el juego.
startAt, endAtstring (ISO 8601) | nullPeriodo de la campaña; null para TWITCH_DESCRIPTION. Una campaña terminada se queda.
campaignId, campaignNamestring | nullLa campaña de Drops; null para TWITCH_DESCRIPTION.
repeat{ everyHours, times } | nullSolo DROPS: el tiempo de visualización se pide de nuevo en cada periodo, y requiredMinutes es el de un periodo, con times y everyHours (20 min al día durante 3 días: times 3, everyHours 24); null en otro caso.
categories{ id, name }[] (≤ 50)Solo DROPS: las categorías cuyos canales en directo cuentan, cualquiera de ellas (id y name, 50 como máximo); gameId y gameName son la primera. Vacío en otro caso.
collection{ chestSize, completeAll } | nullSolo DROPS: la insignia es una de las recompensas de una colección de evento, la campaña. chestSize: sale de un cofre con esa cantidad de recompensas, una por cofre, nunca a elegir (null: se da tal cual). completeAll: se da por completar toda la colección, suscripciones incluidas. null en otro caso.
evolvesFrom{ setId, versionId } | nullSolo DROPS: la insignia que debes llevar equipada en el chat antes de ver, por su setId y su versionId en esta lista: una evolución de Pokémon pide su etapa anterior (Pikachu: Pichu). null en otro caso, o si no se conoce.

Códigos de respuesta

EstadoDescripción
200Las insignias globales. Una lista vacía es una respuesta válida.
304Nada ha cambiado desde el ETag que enviaste: conserva tu copia. Gratis, no cuenta en tu límite.
429RATE_LIMITED: Espera los segundos que indica Retry-After.
429INVALID_API_KEY_RATE_LIMITED: La clave no se reconoce y el límite anónimo de tu dirección IP está agotado: corrige la clave.
503SERVICE_UNAVAILABLE: Aún no hay lista cargada (justo después de un reinicio de la API): reintenta tras Retry-After. Gratis, no cuenta en tu límite.
Ejemplo de solicitud
curl https://drops.sunkwi.com/api/twitch/badges
Cargando la vista previa…

Límites de uso

Cada ruta tiene su propio contador: llamar a /drops nunca gasta el cupo de /rewards ni el de /badges. Las campañas cambian una vez por minuto y las insignias cada 5 minutos, así que consultar más a menudo no aporta nada nuevo.

ClienteLímite por rutaSe cuenta por
Anónimo1 solicitud cada 5 minutosDirección IP
Con clave de API1 solicitud por minuto por defecto, ampliable si lo pidesClave de API

Cabeceras de respuesta

Cabeceras que la API lee y envía.

CabeceraSentidoDescripción
x-last-updated-atresponseHora de la última lectura correcta de Twitch: el escaneo para /drops y /rewards, las insignias para /badges.
x-refresh-interval-secondsresponseSegundos entre dos lecturas de Twitch: pedir los datos más a menudo devuelve lo mismo (60 para /drops y /rewards, 300 para /badges).
ratelimit-limitresponseSolicitudes permitidas en la ventana, para esta ruta.
ratelimit-remainingresponseSolicitudes restantes en la ventana actual.
ratelimit-resetresponseSegundos hasta que se vuelva a permitir una solicitud.
ratelimit-policyresponseLa política, en formato <límite>;w=<ventana en segundos>.
retry-afterresponseSegundos que hay que esperar antes de reintentar, en una respuesta 429 o 503.
x-api-keyrequestTu clave de API: opcional en todas las rutas.
x-api-key-statusresponseinvalid cuando la clave enviada es desconocida, está revocada o está desactivada: la llamada ha contado como anónima, con el límite de tu dirección IP.
etagresponseEtiqueta de esta respuesta. Devuélvela en If-None-Match: mientras los datos no cambien, la respuesta es un 304 que no cuenta en tu límite.
if-none-matchrequestEl ETag de tu última respuesta, opcional: una lista sin cambios responde 304 Not Modified, gratis.
Una segunda llamada anónima en 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" }

Errores

Los errores devuelven un cuerpo JSON con un código estable: { "code": "RATE_LIMITED" }. Los códigos nunca cambian: básate en code, no en un mensaje.

EstadoCódigoDescripción
429RATE_LIMITEDDemasiadas solicitudes en esta ruta: espera los segundos que indica Retry-After.
429INVALID_API_KEY_RATE_LIMITEDDemasiadas solicitudes, y la cabecera X-API-Key contiene una clave desconocida, revocada o desactivada: la llamada ha contado como anónima. Corrige la clave o espera los segundos que indica Retry-After.
503SERVICE_UNAVAILABLEAún no hay lista cargada (justo después de un reinicio de la API). No se gasta nada: reintenta tras los segundos que indica Retry-After.
404NOT_FOUNDLa ruta no existe.
500INTERNAL_SERVER_ERRORError del servidor: vuelve a intentarlo más tarde.
Ejemplo de error
HTTP/1.1 404 Not Foundcontent-type: application/json; charset=utf-8
{ "code": "NOT_FOUND" }

Del sitio a la API

Todas las páginas de este sitio leen estas mismas rutas. Aquí puedes ver en qué parte de las respuestas está lo que muestra cada página.

PáginaRutaDónde está en la respuesta
Drops/drops/dropsgames: un elemento por juego, con sus campañas en rewards. La vista de cuadrícula dibuja startAt y endAt de cada campaña.
La página de un juego/drops/<game>/dropsUn elemento de games, identificado por gameId. Cada campaña es games[i].rewards[j]; sus recompensas son los benefitEdges de timeBasedDrops, con requiredMinutesWatched.
Recompensas/rewards/rewardscampaigns: un elemento por campaña de recompensas, con sus recompensas en rewards y sus requisitos en unlockRequirements.
La página de una campaña de recompensas/rewards/<campaign>/rewardsUn elemento de campaigns, identificado por id; sus recompensas están en rewards.
Insignias/badges/badgesbadges: todos los elementos, primero los que tienen requirement, con cómo conseguirlos. La vista de cuadrícula dibuja requirement.startAt y requirement.endAt de cada insignia.
La página de una insignia/badges/<badge>/badgesUn elemento de badges, identificado por setId y versionId; «Cómo se consigue» es su requirement.