---
url: https://docs.dataflair.ai/dataflair/toplist-api.md
description: >-
  Base URL, endpoints, scopes, rate limits and API versions for the DataFlair
  Toplist API.
---

# Toplist API

## What this is, and isn't

This is a **reference document only**: endpoints, authentication, response shapes, the geo
resolution algorithm your integration must implement, and the compliance reasoning behind it.

* **No SDK or package is provided.** DataFlair does not ship a client library in any language. You
  build your own HTTP client against the plain-JSON contract described in this section.
* **No live "resolve my visitor's geo" endpoint exists.** DataFlair does not evaluate your visitor's
  location for you on a per-request basis. See [Integration model](/dataflair/toplist-api/integration-model).
* Code samples in this section are **curl** (a raw HTTP request) or **plain pseudocode** (the
  resolution algorithm). The [playground](/dataflair/toplist-api/playground) also shows the same
  request in PHP, Node and Python.

## Base URL and scoping

Base URL: `https://{your-tenant-domain}`. The domain of the request resolves your **tenant** only.
The **site** your data is scoped to is a separate, finer-grained resolution: it comes from the
`site_id` baked into the credential you authenticated with, not from the hostname. Changing which
domain you call does not change which site's toplists you get back. That's determined entirely by
which credential you used. Your DataFlair account contact will give you the exact domain and
credentials for your integration.

## Endpoints

All endpoints below (except the auth exchange) require the `Authorization: Bearer` header and are
rate-limited **per-credential**, default **60 requests/minute** (your specific credential may be
configured with a different limit: check with your DataFlair contact if you're unsure).

| Method | Path | Requires scope | Purpose |
|---|---|---|---|
| `POST` | `/api/v1/auth/token` | none (key+secret) | Exchange credentials for a bearer token. See [Auth token endpoint](/dataflair/toplist-api/authentication) |
| `GET` | `/api/v1/toplists` | `toplist:read` | List toplists, optionally filtered. See [Toplists endpoints](/dataflair/toplist-api/toplists-endpoint) |
| `GET` | `/api/v1/toplists/by-slug/{slug}` | `toplist:read` | Fetch one toplist by its slug |
| `GET` | `/api/v1/toplists/{id}` | `toplist:read` | Fetch one toplist by its numeric ID |
| `GET` | `/api/v1/brands` | `brand:read` | List every active brand in the tenant. See [Brands endpoint](/dataflair/toplist-api/brands-endpoint) |

## API versions (v1 vs v2)

Everything documented in this section is **v1** (`/api/v1/...`), the recommended surface for a new
integration. A **v2** (`/api/v2/...`) also exists. Its **brand** shape is genuinely additive on top
of v1: every v1 brand field name is unchanged, with ~15 new multi-vertical fields appended (sports
betting fields like `sportsCovered` / `hasLiveBetting` / `hasBetBuilder`, poker fields like
`pokerVariants` / `pokerNetwork`, and sweepstakes-casino fields like `hasSweepsCoins` /
`scToUsdRate`).

**Its offer shape is not additive. It's a rename.** The offer embedded inside a v2 toplist item
uses different camelCase field names than either v1 offer shape, not just different casing: for
example `wageringRequirement` (not `bonusWageringRequirement` as in v1's `/api/v1/brands`, and not
`bonus_wagering_requirement` as in v1's toplist-embedded offer). A parser written against either v1
offer shape will silently get missing/`null` fields if pointed at a v2 response instead of an error.
Don't assume v2's offer fields are a superset of v1's. The `geo` object and the outer
toplist/item envelope (ids, position, template, site, etc.) are identical between the two versions.
The two sub-objects that do differ are `brand` (additive) and `offer` (renamed). Don't assume only
one of them changed.

Use v2 instead of v1 only if you specifically need one of those multi-vertical fields. One practical
heads-up if you do: v2's single-toplist lookups (`/api/v2/toplists/{id}` and
`/api/v2/toplists/by-slug/{slug}`) are currently missing the same "must have a live edition" gate
that v1's equivalents and both versions' `GET /toplists` listing apply. A toplist with no live
edition, one that correctly never appears in `GET /api/v2/toplists` (or any v1 endpoint) and
correctly 404s on v1's single-item lookups, can still come back as a 200 from v2's single-item
lookup, just with an empty `items` array and no `currentPeriod`, instead of the 404 you'd get
everywhere else. Don't treat a 200 from a v2 single-item lookup as proof a toplist is genuinely live;
if you need that guarantee, check the `index()` listing (either version) or use v1's single-item
endpoints instead. This is a known internal inconsistency, not intended behavior. Flag it to your
DataFlair contact if you hit it.

## Non-goals

* No SDK, package, or generated client is provided in any language.
* No live per-request geo-resolution endpoint exists. You always fetch ahead and resolve locally
  (see [Integration model](/dataflair/toplist-api/integration-model)).
* This section does not cover DataFlair's admin UI or internal editing workflows: only the
  read-only external API surface documented here.