Ir 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 los emblemas 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
Obtén 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, emblemas de chat, recompensas de socios), en campaigns.
GET /badgesEmblemas globales del chat. Los emblemas globales del chat de Twitch, un elemento por versión en badges, con cómo conseguirlos cuando se sabe.

Autenticación

Para leer /drops, /rewards y /badges no necesitas 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 el encabezado X-API-Key. Una clave sube tu límite a 1 solicitud por minuto de forma predeterminada (puedes pedir más) y te muestra tu tráfico.

Encabezado de solicitud

EncabezadoValorDescripció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

Obtén 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 aparezca (solo una vez) y envíala en el encabezado 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 exitoso 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 los encabezados 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 activa.
startAt, endAtstring (ISO 8601)Período de la campaña.
imageURLstring (URL)Imagen de la campaña.
detailsURL, accountLinkURLstring (URL)Página de detalles y página de conexión de cuenta del editor.
allow{ isEnabled, channels? }Canales autorizados a dar los Drops cuando isEnabled es true; si no, cualquier canal que transmita el juego. displayName puede ser null o faltar.
timeBasedDropsTimeBasedDrop[]Drops que se obtienen mirando streams.
eventBasedDropsunknown[]Drops que se obtienen 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 obtiene mirando streams, en timeBasedDrops.

CampoTipoDescripción
id, namestringID de Twitch y nombre del Drop.
startAt, endAtstring (ISO 8601)Período durante el que se puede obtener el Drop.
requiredMinutesWatchednumberMinutos de visualización necesarios.
requiredSubsnumberSuscripciones necesarias.
repeat{ everyHours, times } | nullAgregado 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 período. null para un Drop que se gana una sola vez.
preconditionDropsunknownDrops que hay que obtener 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 un emblema 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 cambió 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: Todavía no hay ninguna lista cargada (justo después de un reinicio de la API): vuelve a intentarlo después de 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, emblemas 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 exitoso 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 los encabezados 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)Período 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 agrega a los enlaces de canje.
unlockRequirements{ minuteWatchedGoal, subsGoal }Minutos de visualización y suscripciones necesarios.
rewardGroupsRewardGroup[]?Recompensas que se obtienen grupo por 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 obtienen juntas.

CampoTipoDescripción
idstringID de Twitch del grupo.
unlockRequirements{ minuteWatchedGoal, subsGoal, turboSubsGoal?, eventTriggerGoal? }Lo que pide el grupo. Twitch agrega 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 período. null para un grupo que se gana una sola vez.
categories{ id, displayName, slug }[]Las categorías cuyos canales en vivo 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 obtener 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 cambió 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: Todavía no hay ninguna lista cargada (justo después de un reinicio de la API): vuelve a intentarlo después de 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 emblemas del chat

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

Los emblemas globales del chat de Twitch en badges, un elemento por versión, cada uno con cómo conseguirlo cuando esta API lo sabe (requirement), junto con la hora de la última lectura de los emblemas de Twitch y tu límite de uso.

Cuerpo de la respuesta

CampoTipoDescripción
badgesBadge[]Los emblemas globales, un elemento por versión. Un array vacío es una respuesta válida.
refreshedAtstring (ISO 8601) | nullHora de la última lectura exitosa de los emblemas 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 los encabezados 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 un emblema global del chat, tal como lo lista Twitch ahora.

CampoTipoDescripción
setId, versionIdstringEl conjunto de emblemas y su versión: juntos identifican un emblema (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 el emblema, y su enlace; null cuando Twitch no da ninguno.
firstSeenAtstring (ISO 8601) | nullCuándo vio esta API el emblema por primera vez. Si vuelve más de 7 días después de que Twitch lo retirara, recibe una fecha nueva; si vuelve antes, conserva la que tenía. null para los emblemas que ya estaban en su primera lectura.
requirementBadgeRequirement | nullCómo conseguirlo; null cuando esta API no lo sabe.
Campos de BadgeRequirement

BadgeRequirement

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

CampoTipoDescripción
source'DROPS' | 'TWITCH_DESCRIPTION'DROPS o TWITCH_DESCRIPTION.
watchTimeOnlybooleantrue exactamente cuando basta con mirar: 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 de regalo, que pide.
gameId, gameNamestringEl juego: su ID de Twitch (null si se desconoce) y su nombre.
channels, channelCountstring[] (≤ 5), numberLos 5 primeros canales que lo dan (logins) y cuántos son; 0: cualquier canal que transmita el juego.
startAt, endAtstring (ISO 8601) | nullPeríodo 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 período, y requiredMinutes es el de un período, 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 vivo 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: el emblema 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 elección (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: el emblema que debes llevar equipado 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
200Los emblemas globales. Una lista vacía es una respuesta válida.
304Nada cambió 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: Todavía no hay ninguna lista cargada (justo después de un reinicio de la API): vuelve a intentarlo después de 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 los emblemas cada 5 minutos, así que consultar más seguido 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 de forma predeterminada, más si lo pidesClave de API

Encabezados de respuesta

Encabezados que la API lee y envía.

EncabezadoSentidoDescripción
x-last-updated-atresponseHora de la última lectura exitosa de Twitch: el escaneo para /drops y /rewards, los emblemas para /badges.
x-refresh-interval-secondsresponseSegundos entre dos lecturas de Twitch: pedir los datos más seguido 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, con el formato <límite>;w=<ventana en segundos>.
retry-afterresponseSegundos que hay que esperar antes de volver a intentarlo, 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 contó 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 llegan con un cuerpo JSON y un código estable: { "code": "RATE_LIMITED" }. Los códigos nunca cambian: guíate por code, no por 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 el encabezado X-API-Key contiene una clave desconocida, revocada o desactivada: la llamada contó como anónima. Corrige la clave o espera los segundos que indica Retry-After.
503SERVICE_UNAVAILABLETodavía no hay ninguna lista cargada (justo después de un reinicio de la API). No se gasta nada: vuelve a intentarlo después de 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.
Emblemas/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 emblema.
La página de un emblema/badges/<badge>/badgesUn elemento de badges, identificado por setId y versionId; "Cómo conseguirlo" es su requirement.