API Reference

Next.js App Router on Vercel. 45+ endpoints powering quests, snaps, taste memory, notifications, and the public discovery map.

Quest Generation

Endpoints that produce the quest deck: live events, daily picks, tailored recommendations, local LLM quests for non-Barcelona cities, and the chat game master.

Method	Endpoint	Purpose
GET	/api/quests/live	Live event quest (time-sensitive, one per city)
GET	/api/quests/daily	Daily quest deck from curated library (Barcelona)
GET	/api/quests/tailored	Taste-memory-personalised quest for a user
GET	/api/quests/local	LLM-generated quests for non-Barcelona cities
POST	/api/quests/chat	Conversational game master (custom quest via chat)

Quest Lifecycle

Accept, track progress, validate snaps, complete, or abandon a quest.

Method	Endpoint	Purpose
POST	/api/quest/accept	Accept a quest (creates user_quests row)
GET	/api/quest/active	Fetch user's currently active quest
GET	/api/quest/progress	Current snap/visit progress for active quest
POST	/api/quest/validate-snap	AI validates a snap against quest theme
POST	/api/quest/complete	Mark quest as complete (awards XP + badge check)
POST	/api/quest/abandon	Abandon active quest

Daily Community Quest

One community-wide quest per day. Separate from the personal quest deck.

Method	Endpoint	Purpose
GET	/api/daily-quest	Get today's daily community quest
POST	/api/daily-quest/accept	Accept the daily quest
POST	/api/daily-quest/complete	Claim daily quest completion
GET	/api/daily-quest/feed	Public feed of daily quest snaps

Photos + Snaps

Upload, classify, and query walk photos. AI classifies themes for collection badge progress.

Method	Endpoint	Purpose
POST	/api/photos/upload	Upload a snap photo (compressed, with location)
GET	/api/photos/theme-counts	Cumulative theme counts for collection badges

Public Discovery Map

Community snap map: publish, browse, bookmark, and unpublish snaps.

Method	Endpoint	Purpose
GET	/api/public-map	Fetch public snaps within map bounds
POST	/api/public-map/publish	Publish a snap to the public map
POST	/api/public-map/unpublish	Remove a snap from the public map
POST	/api/public-map/save	Bookmark a public snap
POST	/api/public-map/unsave	Remove bookmark
GET	/api/public-map/saved	Fetch user's saved/bookmarked snaps

Collection Map

Shareable collection quest photo maps (public link via token).

Method	Endpoint	Purpose
POST	/api/collection-map/share	Create a shareable collection map link
GET	/api/collection-map/[token]	Public view of a shared collection
GET	/api/collection-map/photos	Fetch photos for a collection theme

Taste Memory

User taste profile: seed from onboarding, update from walk behaviour, query for personalisation.

Method	Endpoint	Purpose
POST	/api/taste/seed	Seed initial taste profile from onboarding answers
GET	/api/taste/profile	Fetch user's current taste profile
POST	/api/taste/batch-update	Batch update taste dimensions from walk data

Wander

Free-form wandering: direction generation and bloom data for the compass ring.

Method	Endpoint	Purpose
GET	/api/wander	Generate a wander direction + vibe
GET	/api/wander/bloom	Bloom ring data (nearby POI density)

Places + POIs

Google Places integration for POI details, photos, and autocomplete.

Method	Endpoint	Purpose
GET	/api/place-detail	Fetch Google Place details by place_id
GET	/api/place-photo	Proxy a Google Place photo
GET	/api/poi-photo	Single POI photo lookup
GET	/api/poi-photos	Batch POI photos for map pins
GET	/api/autocomplete	Google Places autocomplete suggestions
GET	/api/autocomplete/geocode	Geocode a place prediction to lat/lng

Diary + Sharing

Walk history and social sharing.

Method	Endpoint	Purpose
GET	/api/diary	Fetch user's walk diary (completed walks + snaps)
POST	/api/share	Generate a shareable walk summary image

Routing

Walking route generation for visit quests.

Method	Endpoint	Purpose
GET	/api/route	Walking route between quest stops (Google Directions)

Notifications

Push notification registration, preferences, and cron-triggered nudge endpoints.

Method	Endpoint	Purpose
POST	/api/notifications/register	Register a push token (Expo push)
POST	/api/notifications/preferences	Update notification settings
POST	/api/notifications/heartbeat	App open heartbeat (updates activity log)
GET	/api/notifications/streak-nudge	Cron: streak reminder for active walkers
GET	/api/notifications/comeback-nudge	Cron: re-engagement nudge for inactive users
GET	/api/notifications/quest-reminder	Cron: remind users of accepted but incomplete quests
GET	/api/notifications/weather-window	Cron: good weather walking nudge
GET	/api/notifications/live-event	Cron: notify users of new live events

Maintenance

Method	Endpoint	Purpose
GET	/api/cleanup	Cron: expire old walks, prune orphaned data

Deprecated

Legacy endpoints kept for backwards compatibility. Do not use in new code.

Method	Endpoint	Purpose
POST	/api/destination-resolve	(deprecated) Resolve a destination string to coordinates
POST	/api/vibe-extract	(deprecated) Extract vibe keywords from free text
POST	/api/suggest	(deprecated) Early quest suggestion endpoint