Skip to content
Twitch Drops API

Twitch Drops API reference

A free JSON API listing every active Twitch Drops and reward campaign, refreshed every minute, and Twitch's global chat badges. Call it anonymously, or with a free API key for a higher limit.

Base URLhttps://drops.sunkwi.com/api/twitch
Get a free API keyRead the reference

Try it

Anonymous: 1 request every 5 minutes per route. With a key: 1 per minute.

GET
Loading the preview…
Browse

Routes

Every route answers JSON to a GET request, and browsers of any site can call the API (CORS). None of /drops, /rewards or /badges need sign-up; a free API key raises the limit on each.

The three routes answer the same way: the list, the time of the last read from Twitch (refreshedAt) and your rate limit (rateLimit).

RouteDescription
GET /dropsDrops campaigns by game. Every active Drops campaign, grouped by game, in games: one item per game, its campaigns in rewards.
GET /rewardsReward campaigns. Every active reward campaign (sitewide events, chat badges, partner rewards), in campaigns.
GET /badgesGlobal chat badges. Twitch's global chat badges, one item per version in badges, with how to get them when known.

Authentication

Reading /drops, /rewards and /badges needs no account and no key. Anonymous calls are counted per IP address: 1 request every 5 minutes on each route.

Keys are free: sign in with Discord, Twitch or GitHub, create one in the dashboard and send it in the X-API-Key header. A key raises your limit to 1 request per minute by default, raised on request, and shows your traffic.

Request header

HeaderValueDescription
X-API-Keyjdk_…Your API key: optional on every route. An unknown, revoked or disabled key is never refused: the call counts as anonymous, and x-api-key-status: invalid says so.
Example request · 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

Get a free API key

A key is free. It raises your limit from 1 request every 5 minutes to 1 request per minute on each route, and your dashboard shows its traffic.

  1. Sign in with Discord, Twitch or GitHub: no password, no form.
  2. Open API keys in your dashboard and create a key named after your bot or site.
  3. Copy the key when it is shown (only once) and send it in the X-API-Key header, from your server.

Get Drops campaigns

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

Every active Drops campaign, grouped by game: one item of games per game, its campaigns in rewards, with the time of the last Twitch scan and your rate limit.

Response body

FieldTypeDescription
gamesGame[]The active campaigns, in the order of the last scan. An empty array is a valid answer.
refreshedAtstring (ISO 8601) | nullTime of the last successful Twitch scan, null before the first one.
rateLimit{ limit, remaining, resetAt }Your limit on this route after this call, as the ratelimit-* headers tell it: limit requests per window, remaining still allowed, and resetAt, when the whole limit is back (ISO 8601).

Game

One item of games.

FieldTypeDescription
gameIdstringTwitch id of the game.
gameDisplayNamestringName of the game.
gameBoxArtURLstring (URL)Box art of the game, 120×160.
startAtstring (ISO 8601)Start of the earliest campaign of the game.
endAtstring (ISO 8601)End of the latest campaign of the game.
rewardsDropCampaign[]The Drops campaigns of the game.
DropCampaign, TimeBasedDrop and Benefit fields

DropCampaign

A Drops campaign, in rewards of a game.

FieldTypeDescription
idstringTwitch id of the campaign.
name, descriptionstringName and description given by the publisher.
owner{ id, name }Publisher running the campaign.
game{ id, displayName, slug }Game of the campaign.
statusstringTwitch status, ACTIVE for a running campaign.
startAt, endAtstring (ISO 8601)Running period of the campaign.
imageURLstring (URL)Campaign artwork.
detailsURL, accountLinkURLstring (URL)Details page and account-linking page of the publisher.
allow{ isEnabled, channels? }Channels allowed to give the Drops when isEnabled is true; any channel streaming the game otherwise. displayName can be null or missing.
timeBasedDropsTimeBasedDrop[]Drops earned by watching.
eventBasedDropsunknown[]Drops earned by events, passed through from Twitch.
firstSeenAtstring (ISO 8601) | nullWhen this API first saw the campaign. A campaign back less than a day after leaving the list keeps its date. null for the campaigns it was already serving when this field appeared.

TimeBasedDrop

A Drop earned by watching, in timeBasedDrops.

FieldTypeDescription
id, namestringTwitch id and name of the Drop.
startAt, endAtstring (ISO 8601)Period during which the Drop can be earned.
requiredMinutesWatchednumberMinutes of watching needed.
requiredSubsnumberSubscriptions needed.
repeat{ everyHours, times } | nullAdded by this API: how often the Drop is earned again, with times (how many times) and everyHours (24: once a day; null when Twitch does not say). requiredMinutesWatched is then the watch time of one period. null for a Drop earned once.
preconditionDropsunknownDrops to earn first, passed through from Twitch.
benefitEdges{ benefit: Benefit, entitlementLimit }[]What the Drop gives, with how many times it can be claimed.

Benefit

An in-game item, in benefitEdges.

FieldTypeDescription
id, namestringTwitch id and name of the item.
imageAssetURLstring (URL)Picture of the item.
createdAtstring (ISO 8601)Creation date of the item on Twitch.
distributionTypestringHow the item is delivered: DIRECT_ENTITLEMENT for an in-game item, BADGE for a chat badge.
entitlementLimitnumberHow many times the item can be claimed.
isIosAvailablebooleanWhether the item can be claimed on iOS.
game, ownerOrganization{ id, name }Game and publisher of the item.

Response codes

StatusDescription
200The active campaigns. An empty list is a valid answer.
304Nothing changed since the ETag you sent: keep your copy. Free, it does not count against your limit.
429RATE_LIMITED: Wait for the number of seconds in Retry-After.
429INVALID_API_KEY_RATE_LIMITED: The key is not recognised and the anonymous limit of your IP address is spent: fix the key.
503SERVICE_UNAVAILABLE: No list loaded yet (right after a restart of the API): retry after Retry-After. Free, it does not count against your limit.
Example request
curl https://drops.sunkwi.com/api/twitch/drops
Example response · 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" }}

Get reward campaigns

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

Every active reward campaign (sitewide events, chat badges, partner rewards) in campaigns, with the time of the last Twitch scan and your rate limit.

Response body

FieldTypeDescription
campaignsRewardCampaign[]The active campaigns, in the order of the last scan. An empty array is a valid answer.
refreshedAtstring (ISO 8601) | nullTime of the last successful Twitch scan, null before the first one.
rateLimit{ limit, remaining, resetAt }Your limit on this route after this call, as the ratelimit-* headers tell it: limit requests per window, remaining still allowed, and resetAt, when the whole limit is back (ISO 8601).

RewardCampaign

One item of campaigns.

FieldTypeDescription
id, name, brandstringTwitch id, name and brand of the campaign.
statusstringStatus at the time of the request, read from the dates: UPCOMING before startsAt, ACTIVE until endsAt, then EXPIRED.
summary, instructionsstringTexts shown by Twitch.
startsAt, endsAtstring (ISO 8601)Running period of the campaign.
image{ image1xURL }Campaign artwork.
aboutURL, externalURLstring (URL)Help page and external page of the campaign.
isSitewidebooleanWhether every channel counts, not only those of a game.
game{ id, displayName, slug }?Game of the campaign, when it has one.
rewardValueURLParamstringValue Twitch adds to the redemption links.
unlockRequirements{ minuteWatchedGoal, subsGoal }Minutes of watching and subscriptions needed.
rewardGroupsRewardGroup[]?Rewards earned one group at a time, each group with its own goal: a reward a day is a group a day. Only when Twitch sends them.
rewardsReward[]The rewards of the campaign, those of its groups included, each once.
firstSeenAtstring (ISO 8601) | nullWhen this API first saw the campaign. A campaign back less than a day after leaving the list keeps its date. null for the campaigns it was already serving when this field appeared.
Reward fields

RewardGroup

A group of rewards of a reward campaign, earned together.

FieldTypeDescription
idstringTwitch id of the group.
unlockRequirements{ minuteWatchedGoal, subsGoal, turboSubsGoal?, eventTriggerGoal? }What the group asks. Twitch adds Turbo and event goals there.
repeat{ everyHours, times } | nullHow often the group is earned again, like a Drop's repeat: minuteWatchedGoal is then the watch time of one period. null for a group earned once.
categories{ id, displayName, slug }[]The categories whose live channels count, any of them; empty when Twitch names none.
rewardsReward[]The rewards of the group, also listed in the campaign's rewards.

Reward

A reward of a reward campaign.

FieldTypeDescription
id, namestringTwitch id and name of the reward.
bannerImage, thumbnailImage{ image1xURL }Pictures of the reward.
earnableUntilstring (ISO 8601)Last moment the reward can be earned.
redemptionInstructions, redemptionURLstringHow to redeem the reward, and where.

Response codes

StatusDescription
200The active campaigns. An empty list is a valid answer.
304Nothing changed since the ETag you sent: keep your copy. Free, it does not count against your limit.
429RATE_LIMITED: Wait for the number of seconds in Retry-After.
429INVALID_API_KEY_RATE_LIMITED: The key is not recognised and the anonymous limit of your IP address is spent: fix the key.
503SERVICE_UNAVAILABLE: No list loaded yet (right after a restart of the API): retry after Retry-After. Free, it does not count against your limit.
Example request
curl https://drops.sunkwi.com/api/twitch/rewards
Example response · 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" }}

Get chat badges

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

Twitch's global chat badges in badges, one item per version. Each one says how to get it when this API knows (requirement). With the time of the last read of Twitch's badges and your rate limit.

Response body

FieldTypeDescription
badgesBadge[]The global badges, one item per version. An empty array is a valid answer.
refreshedAtstring (ISO 8601) | nullTime of the last successful read of Twitch's badges (every 5 minutes), null before the first one.
rateLimit{ limit, remaining, resetAt }Your limit on this route after this call, as the ratelimit-* headers tell it: limit requests per window, remaining still allowed, and resetAt, when the whole limit is back (ISO 8601).

Badge

One item of badges: one version of a global chat badge, as Twitch lists it now.

FieldTypeDescription
setId, versionIdstringThe badge set and its version: together they name one badge (sub-gifter and 5).
title, descriptionstringIts name and Twitch's description, in English.
imageUrl1x, imageUrl2x, imageUrl4xstring (URL)Its picture at 18, 36 and 72 pixels.
clickAction, clickUrlstring | nullWhat Twitch does when the badge is clicked, and its link; null when Twitch gives none.
firstSeenAtstring (ISO 8601) | nullWhen this API first saw the badge. A badge back more than 7 days after Twitch removed it gets a new date; back sooner, it keeps the one it had. null for the badges already there at its first read.
requirementBadgeRequirement | nullHow to get it; null when this API does not know.
BadgeRequirement fields

BadgeRequirement

How to get a badge: from the Drops campaign that gives it (DROPS), or from Twitch's own description of a subscription or watch badge (TWITCH_DESCRIPTION).

FieldTypeDescription
source'DROPS' | 'TWITCH_DESCRIPTION'DROPS or TWITCH_DESCRIPTION.
watchTimeOnlybooleantrue exactly when watching is enough: a DROPS campaign that asks watch time (requiredMinutes above 0) and no subscription (requiredSubs 0).
requiredMinutes, requiredSubsnumberMinutes of watching, and subscriptions or gifts, it asks.
gameId, gameNamestringThe game: its Twitch id (null when unknown) and its name.
channels, channelCountstring[] (≤ 5), numberThe first 5 channels that give it (logins) and how many there are; 0: any channel streaming the game.
startAt, endAtstring (ISO 8601) | nullWhen the campaign runs; null for TWITCH_DESCRIPTION. An ended campaign stays.
campaignId, campaignNamestring | nullThe Drops campaign; null for TWITCH_DESCRIPTION.
repeat{ everyHours, times } | nullDROPS only: the watch time is needed again each period, requiredMinutes being one period's, with times and everyHours (20 min a day on 3 days: times 3, everyHours 24); null otherwise.
categories{ id, name }[] (≤ 50)DROPS only: the categories whose live channels count, any of them (id and name, 50 at most); gameId and gameName are the first one. Empty otherwise.
collection{ chestSize, completeAll } | nullDROPS only: the badge is one reward of an event collection, the campaign. chestSize: it comes out of a chest of that many rewards, one per chest, never a chosen one (null: given as such). completeAll: given for completing the whole collection, subscriptions included. null otherwise.
evolvesFrom{ setId, versionId } | nullDROPS only: the badge to equip in the chat before watching, by its setId and versionId in this list: a Pokémon evolution asks for its previous stage (Pikachu: Pichu). null otherwise, or when unknown.

Response codes

StatusDescription
200The global badges. An empty list is a valid answer.
304Nothing changed since the ETag you sent: keep your copy. Free, it does not count against your limit.
429RATE_LIMITED: Wait for the number of seconds in Retry-After.
429INVALID_API_KEY_RATE_LIMITED: The key is not recognised and the anonymous limit of your IP address is spent: fix the key.
503SERVICE_UNAVAILABLE: No list loaded yet (right after a restart of the API): retry after Retry-After. Free, it does not count against your limit.
Example request
curl https://drops.sunkwi.com/api/twitch/badges
Loading the preview…

Rate limits

Each route has its own counter: calling /drops never spends the budget of /rewards or /badges. The campaigns change once a minute and the badges every 5 minutes, so polling faster brings nothing new.

CallerLimit per routeCounted per
Anonymous1 request every 5 minutesIP address
With an API key1 request per minute by default, raised on requestAPI key

Response headers

Headers read and sent by the API.

HeaderDirectionDescription
x-last-updated-atresponseTime of the last successful read from Twitch: the scan for /drops and /rewards, the badges for /badges.
x-refresh-interval-secondsresponseSeconds between two reads of Twitch: asking more often returns the same data (60 for /drops and /rewards, 300 for /badges).
ratelimit-limitresponseRequests allowed in the window, for this route.
ratelimit-remainingresponseRequests left in the current window.
ratelimit-resetresponseSeconds until a request is allowed again.
ratelimit-policyresponseThe policy, as <limit>;w=<window in seconds>.
retry-afterresponseSeconds to wait before retrying, on a 429 or 503 answer.
x-api-keyrequestYour API key: optional on every route.
x-api-key-statusresponseinvalid when the key sent is unknown, revoked or disabled: the call counted as anonymous, against the limit of your IP address.
etagresponseTag of this answer. Send it back in If-None-Match: while the data has not changed, the answer is a 304 that does not count against your limit.
if-none-matchrequestThe ETag of your last answer, optional: an unchanged list answers 304 Not Modified, free.
A second anonymous call within 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" }

Errors

An error comes with a JSON body and a stable code: { "code": "RATE_LIMITED" }. Codes never change: build on code, not on a message.

StatusCodeDescription
429RATE_LIMITEDToo many requests on this route: wait for the number of seconds in Retry-After.
429INVALID_API_KEY_RATE_LIMITEDToo many requests, and the X-API-Key header holds an unknown, revoked or disabled key: the call counted as anonymous. Fix the key, or wait for the number of seconds in Retry-After.
503SERVICE_UNAVAILABLENo list is loaded yet (right after a restart of the API). Nothing is spent: retry after the seconds given by Retry-After.
404NOT_FOUNDThe route does not exist.
500INTERNAL_SERVER_ERRORThe server failed: retry later.
Example error
HTTP/1.1 404 Not Foundcontent-type: application/json; charset=utf-8
{ "code": "NOT_FOUND" }

From the site to the API

Every page of this site reads these same routes. Here is where the content of each page sits in the answers.

PageRouteWhere in the answer
Drops/drops/dropsgames: one item per game, its campaigns in rewards. The grid view draws startAt and endAt of each campaign.
A game page/drops/<game>/dropsOne item of games, matched on gameId. Each campaign is games[i].rewards[j]; its rewards are the benefitEdges of timeBasedDrops, with requiredMinutesWatched.
Rewards/rewards/rewardscampaigns: one item per reward campaign, its rewards in rewards and what it asks in unlockRequirements.
A reward campaign page/rewards/<campaign>/rewardsOne item of campaigns, matched on id; its rewards are in rewards.
Badges/badges/badgesbadges: every item, and those with a requirement first, with how to get them. The grid view draws requirement.startAt and requirement.endAt of each badge.
A badge page/badges/<badge>/badgesOne item of badges, matched on setId and versionId; “How to get it” is its requirement.