Source document · API/docs/API_REFERENCE.md
API contract and endpoint inventory
The interactive endpoint index lists the complete route set from the OpenAPI contract. It is regenerated whenever the documentation is synchronized. Every method/path has an authentication label, operation summary, parameters, JSON fields when specified, and response status descriptions. There are 88 operations across 10 groups; all method/path pairs in the router match the OpenAPI paths as of 2026-10-12.
Contract sources
The Go route registration is in internal/platform/httpserver/router.go. Handler DTOs and validation live under internal/app/. The OpenAPI contract is openapi/openapi.yaml; the docs build copies it to the site’s public openapi.yaml. The endpoint index is generated from that contract and is not maintained as a second manual route list.
The interactive OpenAPI explorer is for browsing operations and schemas. The raw contract can be imported into API clients and code generators. Do not put production credentials into a public docs site.
Groups
| Group | What it covers |
|---|---|
| System | Liveness, readiness, metrics, and API version. |
| Authentication | Registration, email OTP, sessions, profile, password reset, and account deletion. |
| Catalog and providers | Services, listing categories/search/detail/contact, providers, listings, menus, and provider dashboard/sales. |
| Orders and payments | Guest/member booking, order reads/transitions, subscription/order payment attempts, submission, evidence, confirmation, and rejection. |
| Notifications | Device registration, inbox reads, and acknowledgement. |
| Chat | Conversations, messages, read state, and authenticated realtime WebSocket. |
| Media | Signed upload initialization and authorized signed reads. |
| Community | Moments/feed, reactions, counters, comments, reports, and block controls. |
| Lifestyle | Dating profiles/browse, curated content, and LiveKit meeting membership. |
| Administration and reporting | Overview/search, status/role operations, provider approval, accountant service scope, moderation, announcements, reports, audit, and CSV export. |
Contract limitations
The endpoint index distinguishes missing OpenAPI details from a route that does not exist. Some currently implemented handler inputs are not yet described by a request-body schema in OpenAPI, including portions of provider, menu, chat, media, community, and lifestyle operations. For those routes, treat the handler and API SRS as the detailed behavior source until their schemas are added to the contract. The index surfaces this by showing no request schema rather than inventing one.
OpenAPI’s operation-level bearer declaration is not a complete authorization policy. Guest order creation is actually optional bearer; resource ownership, staff role, subscription state, accountant scope, and state transitions are checked in application code. See authentication and access control and end-to-end workflows.