# Brandbing Data API — Full Reference

> Read-only programmatic access to Brandbing's verified iGaming casino/brand dataset. This file is the complete reference; the machine-readable spec is at https://brandbing.com/api/v1/openapi.json.

## Getting a key

1. Create a free developer account at https://brandbing.com/developers (email + password) and verify your email.
2. Sign in and open your dashboard at https://brandbing.com/account/api.
3. Click "Create key" — the full key (`bb_live_…`) is shown once. Copy it immediately; only its hash is stored.
4. Need higher limits? Request a higher tier from the "Higher-Tier Access" form on /developers; approvals are emailed within 24–48h.

Free tier: 100 requests/minute, 10,000 requests/month. Higher tiers raise both.

## Authentication

Send the key as a Bearer token on every request:

```
Authorization: Bearer bb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

A missing or invalid key returns `401`. Over-limit returns `429` with `Retry-After` and `X-RateLimit-Limit` / `X-RateLimit-Remaining` headers. If the rate-limiter backend is unavailable the API fails closed with `503` (it never silently grants unlimited access).

## Response envelope

Success:
```json
{ "success": true, "data": ..., "meta": { "total": 250, "page": 1, "limit": 50, "pages": 5 } }
```
Error:
```json
{ "success": false, "error": "Invalid or missing API key" }
```
`meta` is present only on the list endpoint.

## Endpoints

### GET /api/v1/casinos

Paginated list of live, published casinos.

Query parameters:
- `license` — filter by license substring (e.g. `MGA`).
- `page` — 1-based page number (default 1).
- `limit` — results per page (default 20, max 100).

Each item (public subset):
- `id` (string)
- `name` (string)
- `slug` (string) — use with the single-casino endpoint
- `website` (string|null)
- `year_founded` (integer|null)
- `license` (string|null)
- `safety_index` (number|null) — computed 0–10 license/editorial score
- `editor_rating` (number|null) — editorial score, 0–10
- `logo` (string|null)

Example:
```
curl -H "Authorization: Bearer bb_live_…" \
  "https://brandbing.com/api/v1/casinos?license=MGA&limit=50"
```

### GET /api/v1/casinos/{slug}

Full public brand sheet for one live casino plus its active bonuses. Returns `404` if the slug isn't a live, published casino.

`data.casino` — the full public sheet (admin-only fields removed; `safety_index` added).
`data.bonuses` — array of active bonuses (see below).

### GET /api/v1/casinos/{slug}/bonuses

Just the active bonuses for one live casino. Each bonus is the public bonus record with `tracking_link` removed (fields include `bonus_name`, `bonus_type`, and more).

## Using with Claude Code / LLM agents

The fastest path is the hosted MCP server — Brandbing exposes its dataset as native Model Context Protocol tools over Streamable HTTP. In Claude Code:

```
claude mcp add --transport http brandbing \
  https://mcp.brandbing.com/mcp \
  --header "Authorization: Bearer bb_live_…"
```

That gives the agent four typed tools — `search_casinos`, `get_casino`, `get_bonuses`, `compare_casinos` — backed by the same auth, per-key rate limits, and live-visibility gate as the REST API. The MCP server is a thin proxy over `/api/v1/*`, so it can never expose more than the REST endpoints do.

Prefer to generate your own client? Point your agent or code generator at the OpenAPI spec instead:

```
https://brandbing.com/api/v1/openapi.json
```

It fully describes auth, endpoints, parameters, and response schemas, so an agent can call the API correctly with only a key.

## Guarantees

- Read-only. There is no write/mutation API.
- Data never exceeds the public field subset behind the live-visibility gate — a leaked key's blast radius is "restated public data".