Events API

Real-time event feed, detail, time-window and area filtering, event type filtering, geo-sorting, and cache/polling support.

Status

GET /api/v1/events, GET /api/v1/events/:id, GET /api/v1/events/poll, GET /api/v1/events/dashboard, and GET /api/v1/areas are implemented. See Places API and Tours API for their respective dashboard endpoints.

---

List Events

GET /api/v1/events

Real-time events listing, sorted by start time. Supports all filters via query parameters.

Query Parameters

Parameter	Type	Description
window	today | tonight | this_week | weekend | this_month | this_year	Convenience time-window preset
from	ISO 8601	Start of custom time range
to	ISO 8601	End of custom time range
event_type	integer | string	Filter by event type ID or slug
area	integer	Filter by numeric area / town ID
lat	number	Latitude for sort=distance
lng	number	Longitude for sort=distance
sort	time | distance	Sort order (default: time)
page	number	1-based page number (default: 1)
limit	number	Results per page (default: 20, max: 100)

Date-range, area, event-type, and sort filters can be combined. When window is present, it takes precedence over custom from / to values. Related: KUB-131, KUB-133, KUB-134, KUB-137.

Response

{
	"data": [
		{
			"id": "101",
			"title": "Carnival Road March",
			"slug": "carnival-road-march",
			"summary": null,
			"starts_at": "2025-02-10T08:00:00.000Z",
			"ends_at": null,
			"is_all_day": false,
			"timezone": "America/Dominica",
			"event_type": { "id": "1", "name": "Festivals", "slug": "festivals" },
			"area": { "id": "1", "name": "Roseau", "slug": "roseau" },
			"place": null
		}
	],
	"meta": { "page": 1, "limit": 20, "total": 2 }
}

Related: KUB-136, KUB-137.

---

Cache Validation and Polling

List and poll responses include ETag and Last-Modified headers.

For real-time polling clients, use the dedicated poll endpoint:

GET /api/v1/events/poll

The poll endpoint accepts the same query parameters as GET /api/v1/events and returns the same response body shape on 200 OK. Check response status:

• 304 Not Modified — feed unchanged since last poll
• 200 OK — the current page payload is returned together with updated cache validators

Successful and 304 responses both include the standard X-RateLimit-* headers.

Related: KUB-135.

---

Event Detail

GET /api/v1/events/:id

Full event detail.

Detail responses include Cache-Control, ETag, and Last-Modified headers.

Response

{
	"data": {
		"id": "101",
		"title": "Carnival Road March",
		"slug": "carnival-road-march",
		"summary": null,
		"description": null,
		"status": "published",
		"starts_at": "2025-02-10T08:00:00.000Z",
		"ends_at": null,
		"is_all_day": false,
		"timezone": "America/Dominica",
		"source_reference": null,
		"cover_image_url": null,
		"created_at": null,
		"updated_at": "2025-01-15T12:00:00.000Z",
		"area": { "id": "1", "name": "Roseau", "slug": "roseau" },
		"place": null,
		"event_type": { "id": "1", "name": "Festivals", "slug": "festivals" }
	}
}

Related: KUB-132.

---

Areas Listing

GET /api/v1/areas

List of all areas / towns used across events and places.

Response

{
	"data": [
		{ "id": "1", "name": "Roseau", "slug": "roseau" },
		{ "id": "2", "name": "Portsmouth", "slug": "portsmouth" }
	]
}

Cacheable. Related: KUB-133.

---

Events Dashboard

GET /api/v1/events/dashboard

Returns four aggregate sections for the events surface.

Authentication

Optional. Signed-in callers may authenticate with either a bearer JWT or a valid Better Auth session cookie to receive the higher dashboard rate-limit budget.

Rate Limits

Caller type	Requests / minute
Unauthenticated	30
Authenticated	120

Response 200 OK

{
	"data": {
		"categories": [
			{ "id": "1", "name": "Festivals", "slug": "festivals", "event_count": 12 }
		],
		"featured_events": [
			{
				"id": "101",
				"title": "Carnival Road March",
				"slug": "carnival-road-march",
				"summary": "Annual Dominica Carnival celebration",
				"starts_at": "2025-02-10T08:00:00.000Z",
				"ends_at": null,
				"is_all_day": false,
				"timezone": "America/Dominica",
				"area": null,
				"place": null
			}
		],
		"this_week": [],
		"this_month": []
	}
}

Response Sections

Section	Limit	Description
categories	all	Active event type categories with published event count.
featured_events	10	Upcoming published events ordered by start time ascending.
this_week	20	Published events starting within the next 7 days.
this_month	20	Published events starting within the next 30 days.

Response 429 Too Many Requests

Returned when the caller exceeds the dashboard rate limit. Successful and rate-limited responses include the standard X-RateLimit-* headers.

---