API Docs
The REST API is auto-documented via Swagger (@nestjs/swagger), per
spec Section 0 rule 4. Annotations live in the code; the spec is generated
at runtime.
Interactive docs
With the backend running:
http://localhost:3000/docsThis is the live Swagger UI — every endpoint, DTO, and auth requirement, always in sync with the code. Use Authorize (top-right) to paste a Bearer access token and try authenticated endpoints.
Auth endpoints (Phase 0)
| Method | Path | Purpose |
|---|---|---|
| POST | /api/auth/otp/request |
Send a phone OTP (dev returns the code) |
| POST | /api/auth/otp/verify |
Verify OTP → access + refresh tokens (creates rider on first login) |
| POST | /api/auth/register |
Register with phone/email + password |
| POST | /api/auth/login |
Password login |
| POST | /api/auth/refresh |
Rotate refresh token → new pair |
| POST | /api/auth/logout |
Revoke all refresh tokens (auth required) |
| GET | /api/auth/me |
Current principal: id, roles, permissions (auth required) |
| GET | /api/health |
Readiness (DB + Redis) |
Gap-closure endpoints
All are in the live Swagger (/docs); listed here for discoverability.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/rides (stops[]) |
Book with up to 3 intermediate stops (multi-leg fare) |
| POST | /api/pricing/estimate (stops[]) |
Multi-leg fare estimate |
| POST | /api/driver/rides/:id/stops/:index/arrive |
Mark an intermediate stop reached |
| GET | /api/rides/:id/call-number |
Masked/direct number to reach the other party |
| GET | /api/driver/quests |
Driver's incentive quests + live progress (awards on completion) |
| GET/POST/PATCH/DELETE | /api/admin/incentives |
Incentive campaign CRUD (promo.manage) |
| GET | /api/settings/presets |
Country presets for the onboarding picker |
| POST | /api/settings/onboard |
Apply + activate a country preset |
| GET/POST/DELETE | /api/settings/providers/credentials |
Encrypted provider credentials (settings.manage) |
| POST | /api/tax/invoices/issue-for-ride |
Issue a tax invoice (live filing when creds set, else local) |
| GET | /api/referral/me, POST /api/referral/apply |
Referral code + apply |
Generating a static OpenAPI file
For publishing into the docs site, export the spec from the running app's
/docs-json endpoint (Swagger JSON) and feed it to a renderer like
redocusaurus.
source: docs/api/README.md (ships identically in the product zip)