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.
Admin	JWT + access.Require(access.TomodaAdmin) (account_type=tomoda, role=admin).
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
POST	/auth/google-login	Public	Google OAuth exchange
POST	/auth/line-login	Public	LINE 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/phone	JWT	Set/verify phone
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/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/user/webhook/test	JWT	Fire a test webhook delivery
POST	/auth/webauthn/register/begin	JWT	Enroll a passkey (challenge)
POST	/auth/webauthn/register/finish	JWT	Enroll a passkey (attestation)
POST	/auth/api-keys	JWT	Mint an API key
GET	/auth/api-keys	JWT	List API keys
DELETE	/auth/api-keys/:id	JWT	Revoke an API key
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

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
GET	/link-preview	JWT	SSRF-protected, cached link preview
GET	/klipy/:type/search	JWT	GIF/sticker search proxy
GET	/klipy/:type/trending	JWT	Trending GIF/sticker proxy
POST	/klipy/:type/share/:slug	JWT	Share-tracking proxy

Payment

Stripe billing plus the webhook. Detail: Payments 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

Admin

Console and async operations. Detail: Admin service.

Method	Path	Auth	Behavior
GET	/admin/stats/system	Admin	System-wide counters
GET	/admin/stats/users	Admin	User growth stats
GET	/admin/stats/daily	Admin	Daily activity series
GET	/admin/users	Admin	Paginated user directory
PATCH	/admin/users/:id/status	Admin	Ban/suspend/activate
PATCH	/admin/users/:id/subscription	Admin	Override plan
POST	/admin/locations/merge	Admin	Merge duplicate places
GET	/admin/async/queues	Admin	Asynq queue overview
GET	/admin/async/queues/:queue/archived	Admin	Dead/archived tasks
POST	/admin/async/queues/:queue/archived/:id/run	Admin	Requeue one task
DELETE	/admin/async/queues/:queue/archived/:id	Admin	Drop one task
POST	/admin/async/queues/:queue/archived/run-all	Admin	Requeue all archived
POST	/admin/async/s3-orphan-sweep	Admin	Sweep orphaned object-storage keys
POST	/admin/async/replay/challenge/:id	Admin	Re-evaluate a challenge
POST	/admin/async/replay/stamp/:id	Admin	Re-evaluate a stamp

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
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.