Skip to content
Docs · Quickstart

Developer quickstart

Your first Kindred events in 5 minutes.

Four steps from an empty terminal to a list of upcoming events you can show on your site.

Base URL
https://www.kindredoo.com/api/v1
Auth
Authorization: Bearer
Key format
kd_live_…
Snippets in
cURL · JavaScript · Python

Step 1: Create an API key

Log in with your Kindred account (or create one: the same login works across Kindred), open the dashboard and press Create key. The key is shown once: copy it somewhere safe. Treat it like a password: keep it on your server, never in a public repository.

Then put it in an environment variable so the examples below can read it:

export KINDRED_API_KEY="kd_live_YOUR_API_KEY"

Step 2: See what's available

Categories and countries tell you which filters have events right now. Read them from the API instead of hard-coding.

curl "https://www.kindredoo.com/api/v1/categories" \
  -H "Authorization: Bearer $KINDRED_API_KEY"

Step 3: List upcoming events

Filter by country, city, category, a date window (from, to) or text (q). Without a window you get the next 90 days.

curl "https://www.kindredoo.com/api/v1/events?country=NG&category=music&limit=10" \
  -H "Authorization: Bearer $KINDRED_API_KEY"
200Response
{
  "data": [
    {
      "id": "dx-mi3k2a-7f2q1c",
      "slug": "futurefest-26-convergence-lagos-2026-12-11",
      "title": "FutureFest '26 Convergence",
      "category": "festival",
      "category_label": "Festivals",
      "start": "2026-12-11T16:00:00+01:00",
      "end": "2026-12-20T23:00:00+01:00",
      "time_known": true,
      "timezone": "Africa/Lagos",
      "venue": "Eko Atlantic",
      "city": "Lagos",
      "region": null,
      "country": "NG",
      "country_name": "Nigeria",
      "summary": "Ten days of music, tech talks and art installations by the Atlantic.",
      "price": "From ₦25,000",
      "images": {
        "card": "https://www.kindredoo.com/events/futurefest-26-convergence-lagos-2026-12-11/image/card-k3f9.webp",
        "og": "https://www.kindredoo.com/events/futurefest-26-convergence-lagos-2026-12-11/image/og-k3f9.jpg"
      },
      "kindred_url": "https://www.kindredoo.com/events/futurefest-26-convergence-lagos-2026-12-11",
      "ticket_url": "https://app.futurefest.live/tickets",
      "official_url": "https://app.futurefest.live/",
      "source": "discovered",
      "updated_at": "2026-11-16T14:53:14.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  },
  "filters": {
    "country": "NG",
    "city": null,
    "category": "music",
    "q": null,
    "from": "2026-11-18T12:00:00.000Z",
    "to": "2027-02-16T12:00:00.000Z",
    "sort": "start"
  },
  "attribution": "Powered by Kindred (https://www.kindredoo.com)"
}

Show the time where the event happens

start carries the event's own UTC offset (2026-12-11T16:00:00+01:00) and timezone its IANA zone. When time_known is false, show the date only.

Step 4: Page through, cache and handle errors

Pages hold up to 100 events; keep going while pagination.has_more is true. Responses carry an ETag: send it back as If-None-Match and an unchanged list answers 304. On 429, wait Retry-After seconds.

async function allEvents(country) {
  const events = [];
  for (let page = 1; ; page++) {
    const res = await fetch(`https://www.kindredoo.com/api/v1/events?country=${country}&limit=100&page=${page}`, {
      headers: { Authorization: `Bearer ${process.env.KINDRED_API_KEY}` },
    });
    if (res.status === 429) {
      await new Promise((r) => setTimeout(r, Number(res.headers.get("Retry-After") ?? 60) * 1000));
      page--;
      continue;
    }
    const body = await res.json();
    if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
    events.push(...body.data);
    if (!body.pagination.has_more) return events;
  }
}
StatusCodeWhat to do
400invalid_parameterFix the parameter named in `message`. Don't retry unchanged.
401missing_api_keySend your key in the Authorization header.
401invalid_api_keyCheck the key, or create a new one in the dashboard.
429rate_limitedWait `Retry-After` seconds, then retry. Cache responses.
429quota_exceededUpgrade to Pro, or wait for the 1st of next month (UTC).

You're live

That's the whole loop: key, request, page, cache. Next, explore every parameter or check the plans.