Skip to content

Endpoint Reference

The full HTTP surface, grouped by domain. Paths omit the /api/v1 prefix unless noted. This mirrors the router assembled in backend/internal/wiring/router.go and each domain's routes.go under backend/internal/services/<domain>/; those files are authoritative.

For request/response bodies use Swagger / OpenAPI. For the error shape, status codes, and pagination see Conventions.

Auth column legend

Value Meaning
Public No token. Rate-limited per IP; some verify a provider signature.
Optional OptionalJWTAuth: works signed-out, adds viewer-relative fields when a token is present.
JWT JWTAuth: valid bearer token required.
Tomoda account: cap JWT + access.Authorizer.Require for cap, re-reading the caller's role from the database (see Capabilities).
Member / Partner admin / Partner owner JWT + per-partner membership gate (backend/internal/access/partner.go).

Auth

/auth, plus provider webhooks on the API root. Detail: Auth service.

Method Path Auth Behavior
POST /auth/register Public Email/password signup
POST /auth/login Public Email/password login; 202 with a challenge when the account type needs an emailed code
POST /auth/login/code Public Finish a sign-in with the emailed code
POST /auth/google-login Public Google OAuth exchange
POST /auth/apple-login Public Apple OAuth exchange
POST /auth/refresh Public Rotate access token from a refresh token
POST /auth/logout Public Revoke the current session
POST /auth/webauthn/login/begin Public Passkey login challenge
POST /auth/webauthn/login/finish Public Passkey login assertion
POST /auth/reset-password Public Finish an OTP-verified password reset
POST /auth/otp/send Public Send a one-time code
POST /auth/otp/verify Public Verify a one-time code
POST /auth/apple/notifications Public (Apple-signed) Subscription/state webhook
GET /.well-known/webauthn Public (root path) WebAuthn related-origin manifest
GET /auth/profile JWT Current user
PATCH /auth/profile JWT Edit profile fields
DELETE /auth/profile JWT Delete account
POST /auth/email/change JWT Start OTP email change
POST /auth/email/change/confirm JWT Confirm email change
GET /auth/sessions JWT List active sessions
DELETE /auth/sessions/all JWT Sign out everywhere
DELETE /auth/sessions/:id JWT Revoke one session
GET /auth/links JWT Linked accounts and how to switch into each
POST /auth/step-up/begin JWT Open a re-authentication challenge (switch, sensitive with the capability it is for, or link)
POST /auth/step-up/finish JWT Verify the password or passkey; returns a step-up token
POST /auth/links/personal JWT (Tomoda) Link a personal account by signing into it (password, Google or Apple); needs a link step-up
DELETE /auth/links/personal JWT (Tomoda) Remove the Tomoda account's own link; needs a link step-up
POST /auth/links/:id/switch JWT Spend the token when needed; returns a session for the linked account
POST /auth/invites/preview optional JWT What an account invite offers
POST /auth/invites/send-code optional JWT Email a code to the invited address
POST /auth/invites/accept optional JWT Create the account; linked when signed in, with a session when signed out
GET /auth/login-history JWT Recent logins
PUT /auth/profile/password JWT Change password
PUT /auth/profile/name JWT Change display name
PUT /auth/profile/username JWT Change handle
POST /auth/webauthn/register/begin JWT Enroll a passkey (challenge)
POST /auth/webauthn/register/finish JWT Enroll a passkey (attestation)
PUT /users/me/avatar JWT Set avatar from an uploaded storage key
DELETE /users/me/avatar JWT Clear avatar

User

Lean identity card only; the full aggregated profile lives under Discovery. Detail: User service.

Method Path Auth Behavior
GET /users/:userId JWT Lean user card (id, name, username, avatar_url, bio, is_friend)

Discovery

The query/read-aggregation surface: spatial reads, search, taxonomy, the saved-area pin, and the full profile card. Detail: Discovery service.

Method Path Auth Behavior
GET /discovery/profiles/:id Optional Full aggregated user profile card
GET /discovery/map JWT Viewport markers
GET /discovery/radar JWT Nearby-people radar
GET /discovery/locations/:id JWT Location map-card detail
GET /discovery/search JWT Unified NL intent, resolves to events + locations
GET /discovery/search/events JWT Event search near the pin
GET /discovery/search/locations JWT Place search near the pin
GET /discovery/search/users JWT User search
GET /discovery/pin JWT Read the saved area/location pin
PUT /discovery/pin JWT Set the saved area/location pin
GET /discovery/taxonomy JWT Taxonomy vocabulary
GET /discovery/taxonomy/resolve JWT Resolve free text to taxonomy terms

Location

Place search and geocoding. Detail: Locations service.

Method Path Auth Behavior
GET /locations/nearby JWT Places near a point
GET /locations/nearby/autocomplete JWT Typeahead place search (kinds allowlist)
GET /locations/reverse JWT Coordinates to city
GET /locations/countries JWT Country reference list
GET /locations/countries/:code JWT One country by ISO code
POST /locations/resolve JWT Resolve a picked place to a Location
POST /locations/:id/report-outdated JWT Flag stale place data

Maps

Map cards plus per-user personalization. Detail: Discovery service.

Method Path Auth Behavior
GET /map/location/:id Optional Location map card
GET /map/event/:id Optional Event map card
POST /map/location/:id/dismiss JWT Hide a place from my map
POST /map/location/:id/save JWT Bookmark a place
DELETE /map/location/:id/save JWT Remove a bookmark

Event

/events plus shareable public pages. Detail: Events service.

Method Path Auth Behavior
GET /events/:id Optional Shareable detail (privileged fields for host/participants)
GET /events/:id/public Public Sanitized public payload
GET /share/events/:id Public OG/share landing page
GET /events/timezone JWT Resolve a venue's timezone
GET /events/search JWT Taxonomy-aware event search
POST /events JWT Create an event
GET /events JWT List (ranked feed)
GET /events/:id/detail JWT Viewer-projected detail
GET /events/:id/items JWT Read-only board snapshot (taken at plan promotion)
PATCH /events/:id JWT Edit an event
DELETE /events/:id JWT Delete an event
POST /events/:id/join JWT Join
GET /events/:id/participants JWT Roster
POST /events/:id/participants/:userId/approve JWT Host approves a participant
DELETE /events/:id/participants/:userId JWT Remove a participant
POST /events/:id/start JWT Start early
POST /events/:id/cancel JWT Cancel
POST /events/:id/transfer-ownership JWT Hand off ownership
POST /events/:id/messages JWT Send an event-chat message
GET /events/:id/messages JWT Event-chat history
GET /events/active/nearby JWT Proximity poll for the dock check-in button
POST /events/:id/checkin JWT Explicit arrival check-in
GET /users/:userId/events JWT A user's visible events

Plan

Plan canvas and item board. Detail: Plans service.

Method Path Auth Behavior
POST /plans JWT Create a plan
GET /plans JWT List the caller's plans
GET /plans/:id JWT Plan detail
PATCH /plans/:id JWT Edit plan fields
DELETE /plans/:id JWT Delete (owner)
POST /plans/:id/leave JWT Leave a shared plan
POST /plans/:id/archive JWT Archive
POST /plans/:id/restore JWT Unarchive
GET /plans/:id/place-cards JWT Grouped place cards
PUT /plans/:id/place-cards/:plid/vote JWT Vote for the leading place
PUT /plans/:id/rsvp JWT Set attendance intent
POST /plans/:id/promote JWT Promote the plan to an event
GET /plans/:id/poll JWT Read the when-poll
POST /plans/:id/poll/options JWT Propose a day/time option
PUT /plans/:id/poll/:axis JWT Vote on the day or time axis
GET /plans/:id/members JWT Roster
POST /plans/:id/members JWT Add a collaborator
DELETE /plans/:id/members/:userId JWT Remove a collaborator
POST /plans/:id/share-link JWT Mint a join link
POST /plans/join/:token JWT Join via a link token
POST /items JWT Capture an item
POST /items/save-location JWT Save a found place to stash/plan
GET /items JWT List stash/plan items
GET /items/badge JWT Needs-triage badge count
GET /items/locations JWT Distinct locations for the picker
GET /items/:id JWT Item detail
PATCH /items/:id JWT Edit an item
DELETE /items/:id JWT Delete an item
POST /items/:id/triage JWT Resolve the "is this X?" prompt
POST /items/:id/copy JWT Duplicate into another plan/stash
POST /items/:id/create-plan JWT Spin a plan off an item
POST /items/:id/dismiss JWT Hide from the stash
POST /items/:id/restore JWT Un-dismiss
DELETE /items/:id/links/:linkId JWT Remove a link child
DELETE /items/:id/typed-links JWT Clear a resolved typed link
POST /items/:id/reparse JWT Re-run the parse pipeline
POST /items/:id/photos JWT Attach a photo
DELETE /items/:id/photos/:photoId JWT Remove a photo
GET /items/:id/notes JWT List notes
POST /items/:id/notes JWT Add a note
DELETE /items/:id/notes/:noteId JWT Delete a note
GET /users/:userId/plans JWT A user's visible plans

Friend

Friendship graph, close friends, and friend location sharing. Detail: Friends service.

Method Path Auth Behavior
POST /friends/request JWT Send a friend request
POST /friends/accept JWT Accept a request
POST /friends/reject JWT Reject/cancel a request
DELETE /friends/:id JWT Unfriend
GET /friends JWT List friends
GET /friends/requests JWT Incoming pending
GET /friends/sent JWT Outgoing pending
GET /friends/close JWT List close friends
POST /friends/:id/close JWT Add a close friend
DELETE /friends/:id/close JWT Remove a close friend
POST /location/update JWT Publish my coordinates to friends
GET /location/friends JWT Read where my friends are

Presence

App-wide presence and check-ins. Detail: Presence service.

Method Path Auth Behavior
POST /presence/heartbeat JWT Keep-alive ping
POST /presence/active/start JWT Begin sharing live location
POST /presence/active/stop JWT Stop sharing
GET /presence/active/status JWT Current sharing state
POST /checkins JWT Create a check-in (companion tagging friend-gated, 6h throttle per place)
GET /checkins/me JWT My check-ins
GET /checkins/recent JWT Recent check-ins
GET /checkins/:id JWT Check-in detail
DELETE /checkins/:id/companions/:userID JWT Untag a companion

Chat

REST resources; real-time transport is the /ws group below. Detail: Chat service.

Method Path Auth Behavior
GET /chats JWT List chats
GET /chats/unread_total JWT Total unread count
GET /chats/search JWT Search chats
GET /chats/:id JWT Chat by id
GET /chats/dm/:userId JWT Open-or-create a 1:1 chat
POST /chats/group JWT Create a group chat
GET /chats/:id/settings JWT Chat settings
PATCH /chats/:id JWT Rename/update chat
POST /chats/:id/members JWT Add a member
DELETE /chats/:id/members/:userId JWT Remove a member
PATCH /chats/:id/nickname JWT Set my per-chat nickname
PATCH /chats/:id/mute JWT Mute/unmute
PUT /chats/:id/avatar JWT Set the group avatar
GET /chats/:id/messages JWT Message history (cursor)
GET /chats/:id/messages/search JWT Search messages
POST /chats/:id/messages JWT Send a message
POST /chats/:id/read JWT Mark read
POST /chats/:id/messages/:messageId/react JWT React to a message

Moment

Ephemeral shares. Detail: Moments service.

Method Path Auth Behavior
POST /moments JWT Create (with the pre-uploaded AssetKey)
GET /moments/:id JWT Detail
POST /moments/:id/like JWT Like/unlike
DELETE /moments/:id/tags/:userID JWT Remove a tagged companion
DELETE /moments/:id JWT Delete (creator only)
PATCH /moments/:id/visibility JWT Change audience
PATCH /moments/:id/my-tag-visibility JWT Hide my tag from my own feed

Notification

Inbox and push tokens. Detail: Notifications service.

Method Path Auth Behavior
GET /notifications JWT Inbox (cursor)
GET /notifications/unread JWT Unread count
POST /notifications/seen JWT Mark seen up to a cursor
POST /push-tokens JWT Register a device push token
DELETE /push-tokens JWT Drop a device push token ({platform, token} in the body)

Media

Presigned upload starters, the link-preview proxy, and the GIF/sticker proxy. Detail: Media and Link capture.

Method Path Auth Behavior
POST /uploads/avatar JWT Presigned avatar upload
POST /uploads/group-avatar JWT Presigned group-avatar upload
POST /uploads/chat-image JWT Presigned chat-image upload
POST /uploads/chat-image/batch JWT Presigned batch chat-image upload
POST /uploads/moment JWT Presigned moment upload
POST /uploads/item-image JWT Presigned item-image upload
POST /uploads/event-cover JWT Presigned event-cover upload
POST /uploads/plan-cover JWT Presigned plan-cover upload
POST /uploads/geo-cover JWT Presigned upload of a photo offered as a place cover
GET /link-preview JWT SSRF-protected, cached link preview
GET /klipy/config JWT Klipy API key, per-user customer id and ads flag for direct client calls

Billing

Stripe billing plus the webhook. Detail: Billing service.

Method Path Auth Behavior
POST /payment/webhook Public (Stripe-signed) Stripe webhook
POST /auth/payment/create-checkout-session JWT Start a Stripe Checkout session
POST /auth/payment/create-portal-session JWT Open the billing portal

Backstage

The Backstage API, under /backstage. Detail: Backstage service.

Method Path Auth Behavior
GET /backstage/me Tomoda account: backstage.session.read Caller and capabilities
GET /backstage/stats/system Tomoda account: backstage.today.read System-wide counters
GET /backstage/stats/daily Tomoda account: backstage.today.read Daily activity series
POST /backstage/locations/merge Tomoda account: backstage.catalog.action.merge Merge duplicate places
GET /backstage/people Tomoda account: backstage.people.read Find by id, email or handle (audited)
GET /backstage/people/:id Tomoda account: backstage.people.read Person detail (audited)
POST /backstage/people/:id/suspend Tomoda account: backstage.people.action.suspend Suspend and end sessions
POST /backstage/people/:id/restore Tomoda account: backstage.people.action.restore Lift a suspension
POST /backstage/people/:id/sign-out Tomoda account: backstage.people.action.sign_out End every session
GET /backstage/reports Tomoda account: backstage.reports.read Report queue by status (audited)
GET /backstage/reports/:id Tomoda account: backstage.reports.read Report group detail (audited)
POST /backstage/reports/:id/resolve Tomoda account: backstage.reports.action.resolve Dismiss or act on a report group
GET /backstage/geo-covers Tomoda account: backstage.reports.read Cover photo review queue by status and area or place target (audited)
GET /backstage/geo-covers/:id Tomoda account: backstage.reports.read One submission with the place's current cover and open reports (audited)
POST /backstage/geo-covers/:id/decide Tomoda account: backstage.reports.action.resolve Approve or reject a cover photo
POST /backstage/geo-covers/:id/favourite Tomoda account: backstage.reports.action.resolve Pick or clear an approved photo as its target's favourite
GET /backstage/reviews Tomoda account: backstage.reports.read Open review requests (audited)
POST /backstage/reviews/:id/keep Tomoda account: backstage.reports.action.resolve Close a review request and keep the action
POST /backstage/enforcement/:id/undo Tomoda account: backstage.reports.action.resolve (backstage.people.action.suspend for a suspension) Undo an enforcement action with a reason
GET /backstage/cases Tomoda account: backstage.cases.read Support case console (audited)
GET /backstage/cases/:id Tomoda account: backstage.cases.read Case thread with notes (audited)
POST /backstage/cases/:id/messages Tomoda account: backstage.cases.action.reply Reply or internal note
POST /backstage/cases/:id/status Tomoda account: backstage.cases.action.reply Set status
POST /backstage/cases/:id/assignee Tomoda account: backstage.cases.action.reply Take or release
GET /backstage/data/entities Tomoda account: backstage.data.read Data console registry
POST /backstage/data/query Tomoda account: backstage.data.read Read rows (private fields need backstage.data.read_private + reason)
POST /backstage/data/actions/preview Tomoda account: backstage.data.action Preview a change
POST /backstage/data/actions Tomoda account: backstage.data.action Apply or hold a change
GET /backstage/data/actions Tomoda account: backstage.data.read Recent changes
POST /backstage/data/actions/:id/{approve,reject} Tomoda account: backstage.data.action.approve Second admin decides
POST /backstage/data/actions/:id/undo Tomoda account: backstage.data.action Revert a change
GET /backstage/insights Tomoda account: backstage.insights.read Daily platform totals
GET /backstage/insights/members/:id Tomoda account: backstage.insights.read_member One member's engagement (audited)
GET /backstage/crashes Tomoda account: backstage.crashes.read Top crash issues (read-only)
GET /backstage/audit Tomoda account: backstage.audit.read Search the audit log
GET /backstage/accounts/tomoda Tomoda account: backstage.accounts.read Tomoda accounts
GET /backstage/accounts/tomoda/invites Tomoda account: backstage.accounts.read Tomoda invites
POST /backstage/accounts/tomoda/invites Tomoda account: backstage.accounts.action.manage (step-up header) Invite a Tomoda account
POST /backstage/accounts/tomoda/invites/:id/revoke Tomoda account: backstage.accounts.action.manage (step-up header) Withdraw an invite
PATCH /backstage/accounts/tomoda/:id/role Tomoda account: backstage.accounts.action.manage (step-up header) Change a Tomoda role
POST /backstage/accounts/tomoda/:id/revoke Tomoda account: backstage.accounts.action.manage (step-up header) Revoke Tomoda access
GET /backstage/accounts/partners Tomoda account: backstage.partners.read Partner workspaces
GET /backstage/accounts/partners/:id Tomoda account: backstage.partners.read One workspace with members and invites (audited)
POST /backstage/accounts/partners/:id/invites Tomoda account: backstage.partners.action.manage (step-up header) Invite an owner
POST /backstage/accounts/partners/:id/invites/:invite_id/revoke Tomoda account: backstage.partners.action.manage (step-up header) Withdraw an invite
PATCH /backstage/accounts/partners/:id/members/:user_id/role Tomoda account: backstage.partners.action.manage (step-up header) Change a member's role
POST /backstage/accounts/partners/:id/suspend, /restore Tomoda account: backstage.partners.action.manage (step-up header) Suspend or restore a workspace
GET /backstage/async/queues Tomoda account: backstage.ops.queues Asynq queue overview
GET /backstage/async/queues/:queue/archived Tomoda account: backstage.ops.queues Dead/archived tasks
POST /backstage/async/queues/:queue/archived/:id/run Tomoda account: backstage.ops.action.replay Requeue one task
DELETE /backstage/async/queues/:queue/archived/:id Tomoda account: backstage.ops.action.replay Drop one task
POST /backstage/async/queues/:queue/archived/run-all Tomoda account: backstage.ops.action.replay Requeue all archived
POST /backstage/async/s3-orphan-sweep Tomoda account: backstage.ops.action.replay Sweep orphaned object-storage keys
POST /backstage/async/replay/challenge/:id Tomoda account: backstage.ops.action.replay Re-evaluate a challenge
POST /backstage/async/replay/stamp/:id Tomoda account: backstage.ops.action.replay Re-evaluate a stamp
GET /backstage/announcements Tomoda account: backstage.announcements.read Recent announcements and languages
POST /backstage/announcements Tomoda account: backstage.announcements.action.publish Schedule an announcement
PUT /backstage/announcements/:id Tomoda account: backstage.announcements.action.publish Edit copy or window
POST /backstage/announcements/:id/withdraw Tomoda account: backstage.announcements.action.publish Take an announcement down
GET /backstage/switches Tomoda account: backstage.switches.read Feature switches and values
PUT /backstage/switches/:name Tomoda account: backstage.switches.action.set Override a switch, with a reason

Reports

Member reports and enforcement notices. Detail: Report service.

Method Path Auth Description
POST /reports JWT Report an account, moment, message, event or a place cover
GET /me/moderation/:id JWT One action
POST /moderation/review-request None (limited per IP) A suspended member's one review request, with the token from the refused sign-in
POST /me/moderation/:id/review JWT Ask for a review of a warning, hidden or removed content, once

Announcements and switches

Notices written in Backstage and feature switch values. Detail: Backstage service.

Method Path Auth Description
GET /announcements JWT Live announcements in the caller's language, for accounts created before the window started
GET /switches none Public feature switch values

Support

Support cases. Detail: Support service.

Method Path Auth Description
POST /support/cases JWT Open a case
GET /me/support/cases JWT The caller's cases
GET /me/support/cases/:id JWT One case and its thread
POST /me/support/cases/:id/messages JWT Reply
POST /support/contact none (IP-limited) Public contact form
POST /support/inbound HMAC signature Inbound email from the edge worker

Geo covers

Member photos offered for countries, regions, cities and single places. Detail: Geo cover service.

Method Path Auth Description
GET /geo-covers/moments?kind=&key= JWT The caller's own photos at a place
GET /geo-covers/photos?kind=&key= JWT A target's approved photos
GET /geo-covers/mine?kind=&key= JWT The caller's own submissions for a target
POST /geo-covers/submissions JWT Offer an uploaded photo or one of the caller's moments for review
POST /geo-covers/submissions/:id/withdraw JWT Withdraw the caller's own approved photo

Partner

Multi-tenant partner scoping. Detail: Partner service.

Method Path Auth Behavior
POST /partners JWT Create a partner (caller becomes owner)
GET /me/partners JWT Partners I belong to
GET /partner/:partner_id Member Partner detail
GET /partner/:partner_id/members Member Roster
PATCH /partner/:partner_id Partner admin Edit partner
POST /partner/:partner_id/members Partner admin Invite a member
PATCH /partner/:partner_id/members/:user_id Partner admin Change a member's role
DELETE /partner/:partner_id/members/:user_id Partner admin Remove a member
DELETE /partner/:partner_id Partner owner Delete the partner

WebSocket and ops (not under /api/v1)

Method Path Auth Behavior
GET /ws/chats/:id JWT Per-chat SessionHub socket
GET /ws/client JWT Per-user ClientHub socket (notifications, presence, profile sync)
GET /health Public Liveness probe. No dependency calls; 200 whenever the process is up
GET /ready Public Readiness probe. Pings Postgres and Redis (800ms budget); 503 names the failing dependency
GET /metrics Public Prometheus metrics (when observability.metrics is on)
GET /swagger/*any Public (non-prod) Swagger UI

Domains without an HTTP surface

content, gameengine, and passport expose no routes. They are read/written by other domains (the game engine reads content and writes passport state), so they never appear in this table.