# 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 URL: `https://drops.sunkwi.com/api/twitch`
- Documentation: https://drops.sunkwi.com/docs (HTML, with `Try it: console`)
- Get a free API key: https://drops.sunkwi.com/dashboard

## 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`).

| Route | Description |
| --- | --- |
| `GET /drops` | **Drops campaigns by game.** Every active Drops campaign, grouped by game, in `games`: one item per game, its campaigns in `rewards`. |
| `GET /rewards` | **Reward campaigns.** Every active reward campaign (sitewide events, chat badges, partner rewards), in `campaigns`. |
| `GET /badges` | **Global 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.

> Keep the key on your server: anyone who reads it can spend your limit. Read it from an environment variable rather than writing it in your code.

### Request header

| Header | Value | Description |
| --- | --- | --- |
| `X-API-Key` | `jdk_…` | 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. |

Get a free API key: https://drops.sunkwi.com/dashboard

### Example request · curl

```sh
# Anonymous
curl https://drops.sunkwi.com/api/twitch/drops

# With an API key, showing the rate-limit headers
curl -i -H "x-api-key: $DROPS_API_KEY" https://drops.sunkwi.com/api/twitch/drops
```

### Example request · JavaScript

```javascript
// Node.js 18+ (server side: never ship your key to a browser)
const response = await fetch('https://drops.sunkwi.com/api/twitch/drops', {
  headers: { 'x-api-key': process.env.DROPS_API_KEY },
});

if (response.status === 429) {
  const seconds = Number(response.headers.get('retry-after'));
  throw new Error(`Rate limited, retry in ${seconds} s`);
}

const { games, refreshedAt, rateLimit } = await response.json();
console.log(`${games.length} games with drops, scanned at ${refreshedAt}, ${rateLimit.remaining} request(s) left`);
```

### Example request · Python

```python
import os
import requests

response = requests.get(
    "https://drops.sunkwi.com/api/twitch/drops",
    headers={"x-api-key": os.environ["DROPS_API_KEY"]},
    timeout=10,
)
response.raise_for_status()
payload = response.json()
print(len(payload["games"]), "games with drops, scanned at", payload["refreshedAt"])
```

## 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 a free API key: https://drops.sunkwi.com/dashboard
- Sign in: https://drops.sunkwi.com/login

## Get Drops campaigns

`GET https://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.

### Example request

```sh
curl https://drops.sunkwi.com/api/twitch/drops
```

### Example response · 200 OK

```json
{
  "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" }
}
```

### Response body

| Field | Type | Description |
| --- | --- | --- |
| `games` | `Game[]` | The active campaigns, in the order of the last scan. An empty array is a valid answer. |
| `refreshedAt` | `string (ISO 8601) \| null` | Time 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`.

| Field | Type | Description |
| --- | --- | --- |
| `gameId` | `string` | Twitch id of the game. |
| `gameDisplayName` | `string` | Name of the game. |
| `gameBoxArtURL` | `string (URL)` | Box art of the game, 120×160. |
| `startAt` | `string (ISO 8601)` | Start of the earliest campaign of the game. |
| `endAt` | `string (ISO 8601)` | End of the latest campaign of the game. |
| `rewards` | `DropCampaign[]` | The Drops campaigns of the game. |

### DropCampaign, TimeBasedDrop and Benefit fields

#### DropCampaign

A Drops campaign, in `rewards` of a game.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | Twitch id of the campaign. |
| `name`, `description` | `string` | Name and description given by the publisher. |
| `owner` | `{ id, name }` | Publisher running the campaign. |
| `game` | `{ id, displayName, slug }` | Game of the campaign. |
| `status` | `string` | Twitch status, `ACTIVE` for a running campaign. |
| `startAt`, `endAt` | `string (ISO 8601)` | Running period of the campaign. |
| `imageURL` | `string (URL)` | Campaign artwork. |
| `detailsURL`, `accountLinkURL` | `string (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. |
| `timeBasedDrops` | `TimeBasedDrop[]` | Drops earned by watching. |
| `eventBasedDrops` | `unknown[]` | Drops earned by events, passed through from Twitch. |
| `firstSeenAt` | `string (ISO 8601) \| null` | When 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`.

| Field | Type | Description |
| --- | --- | --- |
| `id`, `name` | `string` | Twitch id and name of the Drop. |
| `startAt`, `endAt` | `string (ISO 8601)` | Period during which the Drop can be earned. |
| `requiredMinutesWatched` | `number` | Minutes of watching needed. |
| `requiredSubs` | `number` | Subscriptions needed. |
| `repeat` | `{ everyHours, times } \| null` | Added 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. |
| `preconditionDrops` | `unknown` | Drops 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`.

| Field | Type | Description |
| --- | --- | --- |
| `id`, `name` | `string` | Twitch id and name of the item. |
| `imageAssetURL` | `string (URL)` | Picture of the item. |
| `createdAt` | `string (ISO 8601)` | Creation date of the item on Twitch. |
| `distributionType` | `string` | How the item is delivered: `DIRECT_ENTITLEMENT` for an in-game item, `BADGE` for a chat badge. |
| `entitlementLimit` | `number` | How many times the item can be claimed. |
| `isIosAvailable` | `boolean` | Whether the item can be claimed on iOS. |
| `game`, `ownerOrganization` | `{ id, name }` | Game and publisher of the item. |

> Field names come from Twitch and never change: new fields may appear, existing ones stay.

### Response codes

| Status | Description |
| --- | --- |
| 200 | The active campaigns. An empty list is a valid answer. |
| 304 | Nothing changed since the `ETag` you sent: keep your copy. Free, it does not count against your limit. |
| 429 | `RATE_LIMITED`: Wait for the number of seconds in `Retry-After`. |
| 429 | `INVALID_API_KEY_RATE_LIMITED`: The key is not recognised and the anonymous limit of your IP address is spent: fix the key. |
| 503 | `SERVICE_UNAVAILABLE`: No list loaded yet (right after a restart of the API): retry after `Retry-After`. Free, it does not count against your limit. |

## Get reward campaigns

`GET https://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.

### Example request

```sh
curl https://drops.sunkwi.com/api/twitch/rewards
```

### Example response · 200 OK

```json
{
  "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" }
}
```

### Response body

| Field | Type | Description |
| --- | --- | --- |
| `campaigns` | `RewardCampaign[]` | The active campaigns, in the order of the last scan. An empty array is a valid answer. |
| `refreshedAt` | `string (ISO 8601) \| null` | Time 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`.

| Field | Type | Description |
| --- | --- | --- |
| `id`, `name`, `brand` | `string` | Twitch id, name and brand of the campaign. |
| `status` | `string` | Status at the time of the request, read from the dates: `UPCOMING` before `startsAt`, `ACTIVE` until `endsAt`, then `EXPIRED`. |
| `summary`, `instructions` | `string` | Texts shown by Twitch. |
| `startsAt`, `endsAt` | `string (ISO 8601)` | Running period of the campaign. |
| `image` | `{ image1xURL }` | Campaign artwork. |
| `aboutURL`, `externalURL` | `string (URL)` | Help page and external page of the campaign. |
| `isSitewide` | `boolean` | Whether every channel counts, not only those of a game. |
| `game` | `{ id, displayName, slug }?` | Game of the campaign, when it has one. |
| `rewardValueURLParam` | `string` | Value Twitch adds to the redemption links. |
| `unlockRequirements` | `{ minuteWatchedGoal, subsGoal }` | Minutes of watching and subscriptions needed. |
| `rewardGroups` | `RewardGroup[]?` | 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. |
| `rewards` | `Reward[]` | The rewards of the campaign, those of its groups included, each once. |
| `firstSeenAt` | `string (ISO 8601) \| null` | When 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.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | Twitch id of the group. |
| `unlockRequirements` | `{ minuteWatchedGoal, subsGoal, turboSubsGoal?, eventTriggerGoal? }` | What the group asks. Twitch adds Turbo and event goals there. |
| `repeat` | `{ everyHours, times } \| null` | How 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. |
| `rewards` | `Reward[]` | The rewards of the group, also listed in the campaign's `rewards`. |

#### Reward

A reward of a reward campaign.

| Field | Type | Description |
| --- | --- | --- |
| `id`, `name` | `string` | Twitch id and name of the reward. |
| `bannerImage`, `thumbnailImage` | `{ image1xURL }` | Pictures of the reward. |
| `earnableUntil` | `string (ISO 8601)` | Last moment the reward can be earned. |
| `redemptionInstructions`, `redemptionURL` | `string` | How to redeem the reward, and where. |

### Response codes

| Status | Description |
| --- | --- |
| 200 | The active campaigns. An empty list is a valid answer. |
| 304 | Nothing changed since the `ETag` you sent: keep your copy. Free, it does not count against your limit. |
| 429 | `RATE_LIMITED`: Wait for the number of seconds in `Retry-After`. |
| 429 | `INVALID_API_KEY_RATE_LIMITED`: The key is not recognised and the anonymous limit of your IP address is spent: fix the key. |
| 503 | `SERVICE_UNAVAILABLE`: No list loaded yet (right after a restart of the API): retry after `Retry-After`. Free, it does not count against your limit. |

## Get chat badges

`GET https://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.

### Example request

```sh
curl https://drops.sunkwi.com/api/twitch/badges
```

### Example response · 200 OK

```json
{
  "badges": [
    {
      "setId": "game-awards-2026",
      "versionId": "1",
      "title": "Game Awards 2026",
      "description": "This badge was earned by watching The Game Awards 2026.",
      "imageUrl1x": "https://static-cdn.jtvnw.net/badges/v1/a7c2e9d4-…/1",
      "imageUrl2x": "https://static-cdn.jtvnw.net/badges/v1/a7c2e9d4-…/2",
      "imageUrl4x": "https://static-cdn.jtvnw.net/badges/v1/a7c2e9d4-…/3",
      "clickAction": null,
      "clickUrl": null,
      "firstSeenAt": "2026-11-03T18:05:00.000Z",
      "requirement": {
        "source": "DROPS",
        "watchTimeOnly": true,
        "requiredMinutes": 30,
        "requiredSubs": 0,
        "gameId": "509663",
        "gameName": "Special Events",
        "channels": ["thegameawards"],
        "channelCount": 1,
        "startAt": "2026-11-03T17:00:00Z",
        "endAt": "2026-11-10T16:59:59Z",
        "campaignId": "8a1b…",
        "campaignName": "The Game Awards 2026",
        "repeat": null,
        "categories": [{ "id": "509663", "name": "Special Events" }],
        "collection": null,
        "evolvesFrom": null
      }
    },
    {
      "setId": "gta-vi-launch-celebration",
      "versionId": "1",
      "title": "GTA VI Launch Celebration",
      …
      "requirement": {
        "source": "DROPS",
        "watchTimeOnly": true,
        "requiredMinutes": 60,
        "requiredSubs": 0,
        "gameId": "1867279146",
        "gameName": "Grand Theft Auto VI",
        "channels": [],
        "channelCount": 0,
        "startAt": "2026-11-18T11:00:00.000Z",
        "endAt": "2026-12-01T07:59:59.999Z",
        "campaignId": "b7669f9e-…",
        "campaignName": "GTAVI Launch Celebration",
        "repeat": { "everyHours": 24, "times": 6 },
        "categories": [{ "id": "1867279146", "name": "Grand Theft Auto VI" }],
        "collection": { "chestSize": 6, "completeAll": false },
        "evolvesFrom": null
      }
    },
    {
      "setId": "pikachu",
      "versionId": "1",
      "title": "Pikachu",
      …
      "requirement": {
        "source": "DROPS",
        "watchTimeOnly": true,
        "requiredMinutes": 20,
        "requiredSubs": 0,
        "gameId": "13332",
        "gameName": "Pokémon FireRed/LeafGreen",
        "channels": [],
        "channelCount": 0,
        "startAt": "2026-10-16T17:00:00.000Z",
        "endAt": "2027-01-30T22:59:59.999Z",
        "campaignId": "3e7f0c98-…",
        "campaignName": "Pokemon Evolutions",
        "repeat": { "everyHours": 24, "times": 3 },
        "categories": [{ "id": "13332", "name": "Pokémon FireRed/LeafGreen" }, …],
        "collection": { "chestSize": null, "completeAll": false },
        "evolvesFrom": { "setId": "pichu", "versionId": "1" }
      }
    },
    …
  ],
  "refreshedAt": "2026-11-05T21:10:02.118Z",
  "rateLimit": { "limit": 1, "remaining": 0, "resetAt": "2026-10-24T21:15:12.000Z" }
}
```

### Response body

| Field | Type | Description |
| --- | --- | --- |
| `badges` | `Badge[]` | The global badges, one item per version. An empty array is a valid answer. |
| `refreshedAt` | `string (ISO 8601) \| null` | Time 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.

| Field | Type | Description |
| --- | --- | --- |
| `setId`, `versionId` | `string` | The badge set and its version: together they name one badge (`sub-gifter` and `5`). |
| `title`, `description` | `string` | Its name and Twitch's description, in English. |
| `imageUrl1x`, `imageUrl2x`, `imageUrl4x` | `string (URL)` | Its picture at 18, 36 and 72 pixels. |
| `clickAction`, `clickUrl` | `string \| null` | What Twitch does when the badge is clicked, and its link; `null` when Twitch gives none. |
| `firstSeenAt` | `string (ISO 8601) \| null` | When 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. |
| `requirement` | `BadgeRequirement \| null` | How 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`).

| Field | Type | Description |
| --- | --- | --- |
| `source` | `'DROPS' \| 'TWITCH_DESCRIPTION'` | `DROPS` or `TWITCH_DESCRIPTION`. |
| `watchTimeOnly` | `boolean` | `true` exactly when watching is enough: a `DROPS` campaign that asks watch time (`requiredMinutes` above 0) and no subscription (`requiredSubs` 0). |
| `requiredMinutes`, `requiredSubs` | `number` | Minutes of watching, and subscriptions or gifts, it asks. |
| `gameId`, `gameName` | `string` | The game: its Twitch id (`null` when unknown) and its name. |
| `channels`, `channelCount` | `string[] (≤ 5), number` | The first 5 channels that give it (logins) and how many there are; `0`: any channel streaming the game. |
| `startAt`, `endAt` | `string (ISO 8601) \| null` | When the campaign runs; `null` for `TWITCH_DESCRIPTION`. An ended campaign stays. |
| `campaignId`, `campaignName` | `string \| null` | The Drops campaign; `null` for `TWITCH_DESCRIPTION`. |
| `repeat` | `{ everyHours, times } \| null` | `DROPS` 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 } \| null` | `DROPS` 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 } \| null` | `DROPS` 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. |

> For Drops miners: keep the badges whose `requirement.watchTimeOnly` is `true`. They come from a Drops campaign that gives the badge for watch time alone, never for a subscription. Check `startAt` and `endAt` too: an ended campaign stays in the list.

> Some badges ask more: with `repeat`, watch `requiredMinutes` again each period, `times` times, before `endAt`; any live channel of `categories` counts; with `collection`, a chest may give another badge than the one you want (`chestSize`), and `completeAll` takes the whole collection, subscriptions included. With `evolvesFrom`, equip that badge before watching.

### Response codes

| Status | Description |
| --- | --- |
| 200 | The global badges. An empty list is a valid answer. |
| 304 | Nothing changed since the `ETag` you sent: keep your copy. Free, it does not count against your limit. |
| 429 | `RATE_LIMITED`: Wait for the number of seconds in `Retry-After`. |
| 429 | `INVALID_API_KEY_RATE_LIMITED`: The key is not recognised and the anonymous limit of your IP address is spent: fix the key. |
| 503 | `SERVICE_UNAVAILABLE`: No list loaded yet (right after a restart of the API): retry after `Retry-After`. Free, it does not count against your limit. |

## 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.

| Caller | Limit per route | Counted per |
| --- | --- | --- |
| Anonymous | 1 request every 5 minutes | IP address |
| With an API key | 1 request per minute by default, raised on request | API key |

### Response headers

Headers read and sent by the API.

| Header | Direction | Description |
| --- | --- | --- |
| `x-last-updated-at` | `response` | Time of the last successful read from Twitch: the scan for `/drops` and `/rewards`, the badges for `/badges`. |
| `x-refresh-interval-seconds` | `response` | Seconds between two reads of Twitch: asking more often returns the same data (60 for `/drops` and `/rewards`, 300 for `/badges`). |
| `ratelimit-limit` | `response` | Requests allowed in the window, for this route. |
| `ratelimit-remaining` | `response` | Requests left in the current window. |
| `ratelimit-reset` | `response` | Seconds until a request is allowed again. |
| `ratelimit-policy` | `response` | The policy, as `<limit>;w=<window in seconds>`. |
| `retry-after` | `response` | Seconds to wait before retrying, on a `429` or `503` answer. |
| `x-api-key` | `request` | Your API key: optional on every route. |
| `x-api-key-status` | `response` | `invalid` when the key sent is unknown, revoked or disabled: the call counted as anonymous, against the limit of your IP address. |
| `etag` | `response` | Tag 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-match` | `request` | The `ETag` of your last answer, optional: an unchanged list answers `304 Not Modified`, free. |

> A refused call (429) still counts as a call: wait for `Retry-After` before trying again.

### A second anonymous call within 5 minutes

```http
HTTP/1.1 429 Too Many Requests
content-type: application/json; charset=utf-8
retry-after: 214
ratelimit-limit: 1
ratelimit-remaining: 0
ratelimit-reset: 214
ratelimit-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.

| Status | Code | Description |
| --- | --- | --- |
| 429 | `RATE_LIMITED` | Too many requests on this route: wait for the number of seconds in `Retry-After`. |
| 429 | `INVALID_API_KEY_RATE_LIMITED` | Too 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`. |
| 503 | `SERVICE_UNAVAILABLE` | No list is loaded yet (right after a restart of the API). Nothing is spent: retry after the seconds given by `Retry-After`. |
| 404 | `NOT_FOUND` | The route does not exist. |
| 500 | `INTERNAL_SERVER_ERROR` | The server failed: retry later. |

### Example error

```http
HTTP/1.1 404 Not Found
content-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.

| Page | Route | Where in the answer |
| --- | --- | --- |
| Drops (`https://drops.sunkwi.com/drops`) | `/drops` | `games`: one item per game, its campaigns in `rewards`. The grid view draws `startAt` and `endAt` of each campaign. |
| A game page (`https://drops.sunkwi.com/drops/<game>`) | `/drops` | One item of `games`, matched on `gameId`. Each campaign is `games[i].rewards[j]`; its rewards are the `benefitEdges` of `timeBasedDrops`, with `requiredMinutesWatched`. |
| Rewards (`https://drops.sunkwi.com/rewards`) | `/rewards` | `campaigns`: one item per reward campaign, its rewards in `rewards` and what it asks in `unlockRequirements`. |
| A reward campaign page (`https://drops.sunkwi.com/rewards/<campaign>`) | `/rewards` | One item of `campaigns`, matched on `id`; its rewards are in `rewards`. |
| Badges (`https://drops.sunkwi.com/badges`) | `/badges` | `badges`: 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 (`https://drops.sunkwi.com/badges/<badge>`) | `/badges` | One item of `badges`, matched on `setId` and `versionId`; “How to get it” is its `requirement`. |

> A game page address comes from the game name (`Rocket League` → `/drops/rocket-league`). It is an address of this site, not a field of the API: match games on `gameId`.
