API documentation

REST endpoints under /api/v1. All requests must include a bearer token. Get a key →

Authentication

All endpoints require a bearer token in the Authorization header.

Authorization: Bearer bsk_live_<your-key>

List businesses

Paginated, filterable list of public businesses.

GET /api/v1/businesses?city=london&category=plumbers&page=1&per_page=25

Response:
{
  "data": [
    {
      "slug": "ace-plumbers-london",
      "name": "Ace Plumbers",
      "shortDesc": "24/7 emergency plumbing across Greater London",
      "cityName": "London",
      "postcode": "EC1A 1BB",
      "averageRating": 4.7,
      "reviewCount": 102,
      "isPremium": true,
      "isVerified": true,
      "categorySlug": "plumbers"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 421, "has_more": true }
}

Query parameters

page — default 1
per_page — 1–100, default 25
city — city slug, e.g. london
category — category slug, e.g. plumbers

Business detail

GET /api/v1/businesses/{slug}

Returns the full business record including photos, opening hours and category.

Search

GET /api/v1/search?q=cafe+manchester&limit=20

Returns the same ranked result set our own search page uses.

Errors

401 { "error": "missing" | "invalid" }      — bad or no Authorization header
403 { "error": "revoked" | "expired" }       — key has been disabled
429 { "error": "rate_limited", "retryAfter": 7 }  — token bucket exhausted
429 { "error": "quota_exceeded" }            — monthly quota used up

Rate limits & quotas

Each key is metered by a per-minute token bucket and a monthly quota that rolls over on the first of each month. Standard tier ceilings:

Developer — 1,000 req/month, 60 req/min
Starter — 10,000 req/month, 120 req/min
Growth — 100,000 req/month, 600 req/min
Enterprise — 1M+ req/month, custom burst