App & Onboarding API

Cacheable app-configuration and onboarding content endpoints. All supported by admin-managed settings — see KUB-89, KUB-90, KUB-91.

Status

Implemented in apps/api. Tracked under KUB-120, KUB-121, KUB-122, KUB-123.

The payloads below describe the current contract exposed by apps/api.

---

Home Screen Content

GET /api/v1/app/home

Returns hero image, featured sections, and CTAs for the mobile home screen.

Response

{
	"data": {
		"hero": {
			"image_url": "https://cdn.kubuli.com/home/hero.jpg",
			"headline": "Discover Dominica",
			"subheadline": "Events, places & culture",
			"cta_label": "Explore Now"
		},
		"featured_sections": [
			{ "type": "events", "title": "Happening Tonight", "limit": 5 },
			{ "type": "places", "title": "Top Spots", "limit": 6 }
		],
		"ctas": [
			{
				"label": "Map",
				"target_route": "/map",
				"icon": "map",
				"color": "#ffffff"
			}
		]
	}
}

Cacheable — consumers should respect Cache-Control and ETag headers. Related: KUB-24 (US_13).

---

App Config

GET /api/v1/app/config

Feature flags, section ordering, and branding tokens.

Response

{
	"data": {
		"features": {
			"culture_explorer": true,
			"community_photos": false,
			"map_view": true
		},
		"section_order": ["events", "places", "culture"],
		"branding": {
			"primary_color": "#007A5E",
			"logo_url": "https://cdn.kubuli.com/brand/logo.svg"
		}
	}
}

Long TTL (24 h). ETag supported for conditional requests. Related: KUB-120.

---

Tour Slides

GET /api/v1/app/tour

Ordered multi-screen product tour content for the onboarding flow.

Response

{
	"data": [
		{
			"order": 1,
			"headline": "Discover Events",
			"body": "Find what's happening around you in real time.",
			"image_url": "https://cdn.kubuli.com/tour/slide-1.jpg",
			"cta_label": "Next"
		}
	]
}

Cacheable. Related: KUB-21 (US_10), KUB-122.

---

Intro Video / Animation

GET /api/v1/app/intro

Intro video or animation metadata for the splash/loading screen.

Response

{
	"data": {
		"enabled": true,
		"video_url": "https://cdn.kubuli.com/intro/intro.mp4",
		"thumbnail_url": "https://cdn.kubuli.com/intro/thumb.jpg",
		"duration_seconds": 12,
		"fallback_animation": "lottie",
		"fallback_url": "https://cdn.kubuli.com/intro/fallback.json"
	}
}

Returns sensible defaults when no video is configured. ETag supported. Related: KUB-20 (US_09), KUB-123.

---

User Preferences

Get Preferences

GET /api/v1/me/preferences
Authorization: Bearer <token>

Retrieve current user preferences.

Response

{
	"data": {
		"tour_completed": true,
		"notifications_enabled": true,
		"preferred_area_id": "area_123"
	}
}

Returns 401 for unauthenticated requests and for tokens that refer to deleted users.

---

Update Preferences

PUT /api/v1/me/preferences
Authorization: Bearer <token>
Content-Type: application/json

Body

{
	"tour_completed": true,
	"notifications_enabled": false
}

Response

200 OK with the updated preferences object. Unknown keys are ignored. Returns 401 for unauthenticated requests and for tokens that refer to deleted users. Related: KUB-22 (US_11 – Skip Tour), KUB-23 (US_12 – Replay Tour), KUB-121.