Surfaces
Why every website request needs `?surface=web`, and what happens without it.
Examples use a fictional festival, summer-fest. Sign in at events.grofomo.com and they switch to your own events.
Almost every endpoint takes a surface parameter. Websites must send ?surface=web.
https://api.grofomo.com/v1/events/summer-fest/lineup?surface=webWhy it exists
The same feeds serve two very different consumers: the Grofomo mobile app, and websites like yours. Organisers control those independently — an event can be live in the app while its website content is still being prepared, or the reverse. surface says which of those two visibility settings applies to your request.
Why omitting it bites
The parameter defaults to app, not web. So a request without it is not "unscoped", it is a mobile-app request. If the organiser has published the event to the web but not to the app, that request gets 404 not_found — for an event you can see is live, with a key you know is valid, at a URL you know is right.
If a call 404s and you cannot see why, check for ?surface=web before checking anything else.
Where it is not needed
A few endpoints are web-only by nature and ignore the parameter — the news feeds, for instance, always serve web content. Each reference page states whether surface is required. Sending it where it is not needed is harmless, so the simplest correct habit is to send it every time.