REST endpoints

The REST API predates GraphQL and backs the mobile apps’ main flows. All paths are under /v1 and need credentials unless marked public.

Tokens

Method and path	Description
POST /v1/token	Public. Exchange a Facebook token for a user JWT.
POST /v1/token/service	Public. Exchange a service token for a one-hour service JWT.
POST /v1/token/device	Register a device’s push notification token.

Branding

Method and path	Description
GET /v1/branding?host=<host>	Public. The audience that owns a host, with its theme.

The admin console calls this before anyone signs in so it can skin itself. host defaults to the request’s host, and admin. hosts match their audience’s domain. It returns 404 when no audience owns the host.

{
  "audience": { "id": "…", "name": "Hot Mess", "subdomain": "hotmess" },
  "theme": {
    "preset": "hot_mess",
    "tagline": "Queer nights out, all in one place.",
    "light": { "accent": "#b8236f" },
    "dark": {}
  }
}

The signed-in user

Method and path	Description
GET /v1/me	The signed-in user’s ID and name.
POST /v1/me/location	Report the user’s location: { "coordinates": { "latitude": …, "longitude": … } }, optionally with a beacon (major, minor).
GET /v1/now?latitude=…&longitude=…	What’s happening near the user: the venue they’re at, with its events and messages, or the closest locale’s events and nearest venues.

Locales, venues, people and events

Resources nest under locales, and member routes are shallow (for example GET /v1/venues/:id, not /v1/locales/:locale_id/venues/:id).

Method and path	Description
GET /v1/locales	Every locale.
GET /v1/locales/closest?latitude=…&longitude=…	The locale closest to a point.
GET /v1/locales/:id	One locale.
GET /v1/locales/:locale_id/venues?latitude=…&longitude=…	A locale’s visible venues, nearest first.
GET /v1/venues/:id	One venue.
GET /v1/venues/:id/events	A venue’s upcoming events.
GET /v1/locales/:locale_id/events	A locale’s upcoming events, in “Featured” and “Upcoming” sections.
GET /v1/events/:id	One event, with the user’s RSVP.
POST /v1/events/:id/rsvp	RSVP to an event: { "state": … }.
GET /v1/locales/:locale_id/people	A locale’s people.
GET /v1/people/:id	One person.
GET /v1/people/:id/events	A person’s upcoming events.
GET /v1/tracks/:id	One music track linked to a person.
GET /v1/users/:id, GET /v1/photos/:id	A user, or a photo.

Creating, updating and deleting venues requires an admin. Prefer the GraphQL mutations for administration.

Research

Used by the researcher worker with a service JWT. Admins can call them too, naming the audience with ?audience_id=<uuid> or ?audience=<subdomain>.

Method and path	Scope	Description
GET /v1/research/snapshot	research:read	The audience’s locales and venues with their upcoming events. Filter with ?locale=<label>.
POST /v1/research/batch	places:write and events:write	Upsert venues and events with provenance. Add ?dry_run=true to validate without writing.
GET /v1/research/batches	research:read	The 50 most recent batches.

See Automate with service tokens for the batch format.

Alexa

/alexa/events, /alexa/friends, /alexa/token and /alexa/ping back the Hot Mess Alexa skill.