Endpoint
OpenAPI spec
This API as an OpenAPI 3.1 document. No key needed.
GET
https://www.kindredoo.com/api/v1/openapi.jsonImport it into Postman, Insomnia or a code generator. It is public and needs no API key.
No key needed
This endpoint is public and doesn't count against your limits.
Parameters
This endpoint takes no parameters.
Request
curl "https://www.kindredoo.com/api/v1/openapi.json"Response
200openapi.json
{
"openapi": "3.1.0",
"info": {
"title": "Kindred Events API",
"version": "1.0.0",
"summary": "Upcoming public events from Kindred, for your website or app.",
"description": "Read Kindred's upcoming public events: Kindred-curated events and events verified on the organiser's own page. Authenticate with `Authorization: Bearer <key>` (create keys at https://www.kindredoo.com/developers/dashboard). Free: 1000 requests a month, 60 a minute, non-commercial, show \"Powered by Kindred\". Pro: 100000 a month, 600 a minute, commercial use.",
"termsOfService": "https://www.kindredoo.com/legal/terms",
"contact": {
"name": "Kindred developers",
"url": "https://www.kindredoo.com/developers"
}
},
"servers": [
{
"url": "https://www.kindredoo.com/api/v1",
"description": "Production"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Events",
"description": "Public events, categories and countries."
}
],
"paths": {
"/events": {
"get": {
"operationId": "listEvents",
"summary": "List events",
"description": "Upcoming public events, soonest first, with filters and pagination. Returns published, upcoming events that are on at some point between `from` and `to` (by default now to 90 days ahead). An event that has started but not ended yet is included. Results are sorted by start time.",
"tags": [
"Events"
],
"parameters": [
{
"name": "country",
"in": "query",
"required": false,
"description": "Two-letter ISO 3166-1 country code.",
"schema": {
"type": "string"
},
"example": "NG"
},
{
"name": "city",
"in": "query",
"required": false,
"description": "City name or id, case-insensitive (\"Lagos\", \"buenos-aires\").",
"schema": {
"type": "string"
},
"example": "Lagos"
},
{
"name": "category",
"in": "query",
"required": false,
"description": "One category id from GET /categories.",
"schema": {
"type": "string",
"enum": [
"music",
"art",
"food",
"sport",
"comedy",
"culture",
"market",
"festival",
"tech",
"community"
]
},
"example": "music"
},
{
"name": "from",
"in": "query",
"required": false,
"description": "Start of the window: an ISO 8601 date (2026-12-01, the start of that day UTC) or a date-time with a zone (2026-12-01T18:00:00+01:00). Defaults to now; earlier values are treated as now.",
"schema": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,3})?)?(Z|[+-]\\d{2}:?\\d{2}))?$"
},
"example": "2026-12-01"
},
{
"name": "to",
"in": "query",
"required": false,
"description": "End of the window: an ISO 8601 date or a date-time with a zone. A date alone means the end of that day (UTC). Defaults to 90 days after `from`; at most 366 days after it.",
"schema": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,3})?)?(Z|[+-]\\d{2}:?\\d{2}))?$"
},
"example": "2026-12-31"
},
{
"name": "q",
"in": "query",
"required": false,
"description": "Text search (case-insensitive, 2 to 100 characters) in the title, description, venue and organiser.",
"schema": {
"type": "string"
},
"example": "afrobeats"
},
{
"name": "page",
"in": "query",
"required": false,
"description": "Page number, 1 to 10,000.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 10000,
"default": 1
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Results per page, 1 to 100.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "`start` (soonest first) or `-start` (latest first).",
"schema": {
"type": "string",
"enum": [
"start",
"-start"
],
"default": "start"
}
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests allowed per minute for this key (or `unlimited`).",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left this minute.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset": {
"description": "When the minute window resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit-Month": {
"description": "Requests allowed this calendar month (UTC) for the account.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining-Month": {
"description": "Requests left this month.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset-Month": {
"description": "When the month resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-Kindred-Plan": {
"description": "The plan the key's account is on: `free`, `pro` or `unlimited`.",
"schema": {
"type": "string",
"enum": [
"free",
"pro",
"unlimited"
]
}
},
"ETag": {
"description": "Send it back as If-None-Match to get 304 Not Modified.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EventList"
},
"example": {
"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)"
}
}
}
},
"304": {
"description": "Not modified",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests allowed per minute for this key (or `unlimited`).",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left this minute.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset": {
"description": "When the minute window resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit-Month": {
"description": "Requests allowed this calendar month (UTC) for the account.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining-Month": {
"description": "Requests left this month.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset-Month": {
"description": "When the month resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-Kindred-Plan": {
"description": "The plan the key's account is on: `free`, `pro` or `unlimited`.",
"schema": {
"type": "string",
"enum": [
"free",
"pro",
"unlimited"
]
}
},
"ETag": {
"description": "Send it back as If-None-Match to get 304 Not Modified.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"WWW-Authenticate": {
"description": "`Bearer realm=\"kindred\"`.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Too many requests",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit": {
"description": "Requests allowed per minute for this key (or `unlimited`).",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left this minute.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset": {
"description": "When the minute window resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit-Month": {
"description": "Requests allowed this calendar month (UTC) for the account.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining-Month": {
"description": "Requests left this month.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset-Month": {
"description": "When the month resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-Kindred-Plan": {
"description": "The plan the key's account is on: `free`, `pro` or `unlimited`.",
"schema": {
"type": "string",
"enum": [
"free",
"pro",
"unlimited"
]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/events/{idOrSlug}": {
"get": {
"operationId": "getEvent",
"summary": "Get an event",
"description": "One upcoming public event by its id or slug. Look an event up by the `id` or `slug` from a list response. Events that are over, unpublished or removed answer 404 `not_found`.",
"tags": [
"Events"
],
"parameters": [
{
"name": "idOrSlug",
"in": "path",
"required": true,
"description": "The event's `id` or `slug`.",
"schema": {
"type": "string"
},
"example": "futurefest-26-convergence-lagos-2026-12-11"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests allowed per minute for this key (or `unlimited`).",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left this minute.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset": {
"description": "When the minute window resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit-Month": {
"description": "Requests allowed this calendar month (UTC) for the account.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining-Month": {
"description": "Requests left this month.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset-Month": {
"description": "When the month resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-Kindred-Plan": {
"description": "The plan the key's account is on: `free`, `pro` or `unlimited`.",
"schema": {
"type": "string",
"enum": [
"free",
"pro",
"unlimited"
]
}
},
"ETag": {
"description": "Send it back as If-None-Match to get 304 Not Modified.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EventResponse"
},
"example": {
"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"
},
"attribution": "Powered by Kindred (https://www.kindredoo.com)"
}
}
}
},
"304": {
"description": "Not modified",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests allowed per minute for this key (or `unlimited`).",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left this minute.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset": {
"description": "When the minute window resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit-Month": {
"description": "Requests allowed this calendar month (UTC) for the account.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining-Month": {
"description": "Requests left this month.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset-Month": {
"description": "When the month resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-Kindred-Plan": {
"description": "The plan the key's account is on: `free`, `pro` or `unlimited`.",
"schema": {
"type": "string",
"enum": [
"free",
"pro",
"unlimited"
]
}
},
"ETag": {
"description": "Send it back as If-None-Match to get 304 Not Modified.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"WWW-Authenticate": {
"description": "`Bearer realm=\"kindred\"`.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Too many requests",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit": {
"description": "Requests allowed per minute for this key (or `unlimited`).",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left this minute.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset": {
"description": "When the minute window resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit-Month": {
"description": "Requests allowed this calendar month (UTC) for the account.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining-Month": {
"description": "Requests left this month.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset-Month": {
"description": "When the month resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-Kindred-Plan": {
"description": "The plan the key's account is on: `free`, `pro` or `unlimited`.",
"schema": {
"type": "string",
"enum": [
"free",
"pro",
"unlimited"
]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/categories": {
"get": {
"operationId": "listCategories",
"summary": "List categories",
"description": "Every event category, with the number of upcoming events in each. Use a category `id` as the `category` filter on GET /events.",
"tags": [
"Events"
],
"parameters": [],
"responses": {
"200": {
"description": "OK",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests allowed per minute for this key (or `unlimited`).",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left this minute.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset": {
"description": "When the minute window resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit-Month": {
"description": "Requests allowed this calendar month (UTC) for the account.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining-Month": {
"description": "Requests left this month.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset-Month": {
"description": "When the month resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-Kindred-Plan": {
"description": "The plan the key's account is on: `free`, `pro` or `unlimited`.",
"schema": {
"type": "string",
"enum": [
"free",
"pro",
"unlimited"
]
}
},
"ETag": {
"description": "Send it back as If-None-Match to get 304 Not Modified.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CategoryList"
},
"example": {
"data": [
{
"id": "music",
"label": "Music",
"upcoming_events": 42
},
{
"id": "art",
"label": "Art",
"upcoming_events": 7
},
{
"id": "food",
"label": "Food",
"upcoming_events": 13
}
]
}
}
}
},
"304": {
"description": "Not modified",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests allowed per minute for this key (or `unlimited`).",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left this minute.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset": {
"description": "When the minute window resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit-Month": {
"description": "Requests allowed this calendar month (UTC) for the account.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining-Month": {
"description": "Requests left this month.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset-Month": {
"description": "When the month resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-Kindred-Plan": {
"description": "The plan the key's account is on: `free`, `pro` or `unlimited`.",
"schema": {
"type": "string",
"enum": [
"free",
"pro",
"unlimited"
]
}
},
"ETag": {
"description": "Send it back as If-None-Match to get 304 Not Modified.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"WWW-Authenticate": {
"description": "`Bearer realm=\"kindred\"`.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Too many requests",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit": {
"description": "Requests allowed per minute for this key (or `unlimited`).",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left this minute.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset": {
"description": "When the minute window resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit-Month": {
"description": "Requests allowed this calendar month (UTC) for the account.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining-Month": {
"description": "Requests left this month.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset-Month": {
"description": "When the month resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-Kindred-Plan": {
"description": "The plan the key's account is on: `free`, `pro` or `unlimited`.",
"schema": {
"type": "string",
"enum": [
"free",
"pro",
"unlimited"
]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/countries": {
"get": {
"operationId": "listCountries",
"summary": "List countries",
"description": "Countries with upcoming events, with counts per country and city. Only countries that have at least one upcoming public event are listed, sorted by name.",
"tags": [
"Events"
],
"parameters": [],
"responses": {
"200": {
"description": "OK",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests allowed per minute for this key (or `unlimited`).",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left this minute.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset": {
"description": "When the minute window resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit-Month": {
"description": "Requests allowed this calendar month (UTC) for the account.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining-Month": {
"description": "Requests left this month.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset-Month": {
"description": "When the month resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-Kindred-Plan": {
"description": "The plan the key's account is on: `free`, `pro` or `unlimited`.",
"schema": {
"type": "string",
"enum": [
"free",
"pro",
"unlimited"
]
}
},
"ETag": {
"description": "Send it back as If-None-Match to get 304 Not Modified.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountryList"
},
"example": {
"data": [
{
"code": "NG",
"name": "Nigeria",
"upcoming_events": 18,
"cities": [
{
"name": "Lagos",
"upcoming_events": 14
},
{
"name": "Abuja",
"upcoming_events": 4
}
]
}
]
}
}
}
},
"304": {
"description": "Not modified",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests allowed per minute for this key (or `unlimited`).",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left this minute.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset": {
"description": "When the minute window resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit-Month": {
"description": "Requests allowed this calendar month (UTC) for the account.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining-Month": {
"description": "Requests left this month.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset-Month": {
"description": "When the month resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-Kindred-Plan": {
"description": "The plan the key's account is on: `free`, `pro` or `unlimited`.",
"schema": {
"type": "string",
"enum": [
"free",
"pro",
"unlimited"
]
}
},
"ETag": {
"description": "Send it back as If-None-Match to get 304 Not Modified.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Unauthorized",
"headers": {
"WWW-Authenticate": {
"description": "`Bearer realm=\"kindred\"`.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Too many requests",
"headers": {
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit": {
"description": "Requests allowed per minute for this key (or `unlimited`).",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left this minute.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset": {
"description": "When the minute window resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Limit-Month": {
"description": "Requests allowed this calendar month (UTC) for the account.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Remaining-Month": {
"description": "Requests left this month.",
"schema": {
"type": "string"
}
},
"X-RateLimit-Reset-Month": {
"description": "When the month resets (Unix seconds).",
"schema": {
"type": "integer"
}
},
"X-Kindred-Plan": {
"description": "The plan the key's account is on: `free`, `pro` or `unlimited`.",
"schema": {
"type": "string",
"enum": [
"free",
"pro",
"unlimited"
]
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/openapi.json": {
"get": {
"operationId": "getOpenApi",
"summary": "OpenAPI spec",
"description": "This API as an OpenAPI 3.1 document. No key needed. Import it into Postman, Insomnia or a code generator. It is public and needs no API key.",
"tags": [
"Events"
],
"security": [],
"parameters": [],
"responses": {
"200": {
"description": "OK",
"headers": {
"ETag": {
"description": "Send it back as If-None-Match to get 304 Not Modified.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpenApiDocument"
},
"example": {
"openapi": "3.1.0",
"info": {
"title": "Kindred Events API",
"version": "1.0.0"
},
"paths": {
"/events": {}
}
}
}
}
},
"304": {
"description": "Not modified",
"headers": {
"ETag": {
"description": "Send it back as If-None-Match to get 304 Not Modified.",
"schema": {
"type": "string"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "kd_live_<32 characters>",
"description": "Your API key from the developer dashboard."
}
},
"schemas": {
"Event": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"slug",
"title",
"category",
"category_label",
"start",
"end",
"time_known",
"timezone",
"venue",
"city",
"region",
"country",
"country_name",
"summary",
"price",
"images",
"kindred_url",
"ticket_url",
"official_url",
"source",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"description": "Stable id."
},
"slug": {
"type": [
"string",
"null"
],
"description": "URL slug (verified events); use with GET /events/{idOrSlug}."
},
"title": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"music",
"art",
"food",
"sport",
"comedy",
"culture",
"market",
"festival",
"tech",
"community"
]
},
"category_label": {
"type": "string"
},
"start": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 with the event's UTC offset."
},
"end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"time_known": {
"type": "boolean",
"description": "false: only the date is known (start is local midnight)."
},
"timezone": {
"type": "string",
"description": "IANA time zone of the event."
},
"venue": {
"type": [
"string",
"null"
]
},
"city": {
"type": "string"
},
"region": {
"type": [
"string",
"null"
],
"description": "State, province or region when known."
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2."
},
"country_name": {
"type": "string"
},
"summary": {
"type": [
"string",
"null"
]
},
"price": {
"type": [
"string",
"null"
],
"description": "Price as the organiser states it."
},
"images": {
"type": "object",
"additionalProperties": false,
"required": [
"card",
"og"
],
"properties": {
"card": {
"type": "string",
"format": "uri",
"description": "Card picture (1200x675 WebP for discovered events; the event's own picture or its category cover for curated ones)."
},
"og": {
"type": "string",
"format": "uri",
"description": "Social picture (1200x630 JPEG for discovered events; the same as `card` for curated ones)."
}
}
},
"kindred_url": {
"type": "string",
"format": "uri",
"description": "The event on Kindred."
},
"ticket_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"official_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "The organiser's page the event was verified on."
},
"source": {
"type": "string",
"enum": [
"curated",
"discovered"
]
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
},
"Pagination": {
"type": "object",
"required": [
"page",
"limit",
"total",
"total_pages",
"has_more"
],
"properties": {
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"total": {
"type": "integer"
},
"total_pages": {
"type": "integer"
},
"has_more": {
"type": "boolean"
}
}
},
"EventList": {
"type": "object",
"required": [
"data",
"pagination",
"filters",
"attribution"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
},
"filters": {
"type": "object",
"description": "The filters as applied (defaults filled in)."
},
"attribution": {
"type": "string"
}
}
},
"EventResponse": {
"type": "object",
"required": [
"data",
"attribution"
],
"properties": {
"data": {
"$ref": "#/components/schemas/Event"
},
"attribution": {
"type": "string"
}
}
},
"CategoryList": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"label",
"upcoming_events"
],
"properties": {
"id": {
"type": "string",
"enum": [
"music",
"art",
"food",
"sport",
"comedy",
"culture",
"market",
"festival",
"tech",
"community"
]
},
"label": {
"type": "string"
},
"upcoming_events": {
"type": "integer"
}
}
}
}
}
},
"CountryList": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"name",
"upcoming_events",
"cities"
],
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"upcoming_events": {
"type": "integer"
},
"cities": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"upcoming_events"
],
"properties": {
"name": {
"type": "string"
},
"upcoming_events": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"OpenApiDocument": {
"type": "object",
"description": "This document."
},
"Error": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_parameter",
"missing_api_key",
"invalid_api_key",
"account_unavailable",
"key_paused",
"not_found",
"method_not_allowed",
"rate_limited",
"quota_exceeded",
"server_error"
]
},
"message": {
"type": "string"
}
}
}
}
}
}
},
"externalDocs": {
"description": "Kindred developer docs",
"url": "https://www.kindredoo.com/developers"
}
}