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"{
"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;
}
}| Status | Code | What to do |
|---|---|---|
| 400 | invalid_parameter | Fix the parameter named in `message`. Don't retry unchanged. |
| 401 | missing_api_key | Send your key in the Authorization header. |
| 401 | invalid_api_key | Check the key, or create a new one in the dashboard. |
| 429 | rate_limited | Wait `Retry-After` seconds, then retry. Cache responses. |
| 429 | quota_exceeded | Upgrade 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.