API Reference — Conventions
The REST API is served by apps/api under the base path /api/v1/. This section documents the conventions and the major endpoint groups. The live, always-accurate reference is the auto-generated Swagger UI:
- Swagger UI:
http://localhost:3000/api/docs - OpenAPI JSON:
http://localhost:3000/api/docs.json
Response envelope
jsonc
// success
{ "success": true, "data": { /* ... */ } }
// error
{ "success": false, "error": { "code": "SOME_CODE", "message": "Human readable" } }HTTP status codes
| Code | Meaning |
|---|---|
| 200 | OK |
| 201 | Created |
| 400 | Bad request |
| 401 | Unauthorized (missing/invalid JWT) |
| 403 | Forbidden (wrong role / not owner) |
| 404 | Not found (also used to avoid existence leaks) |
| 422 | Unprocessable entity (validation / business-rule violation) |
| 429 | Too many requests (rate limited) |
| 500 | Internal error |
| 503 | Degraded (pool saturated / dependency down) |
Pagination
List endpoints accept ?page=1&limit=20 and return:
jsonc
{ "data": [ /* ... */ ], "pagination": { "page": 1, "limit": 20, "total": 84, "totalPages": 5 } }Auth
Send the access token as Authorization: Bearer <jwt> — never as a query parameter. See Authentication.
Middleware gating vocabulary
Endpoint tables use this shorthand:
| Token | Meaning |
|---|---|
requireAuth | Valid JWT required |
requireActiveUser | profileComplete === true (all writes) |
ownership | The resource must belong to the caller (checked in the service) |
sellQuota / buyQuota | Consumes a post-axis quota unit |
engagementQuota | Consumes an engagement-axis quota unit |
mustHaveViewed | A prior LeadView must exist (else 422 MUST_VIEW_FIRST) |
authorize('admin') | Admin role (some grievance routes also allow sub-admin) |
Endpoint groups
| Group | Base | Page |
|---|---|---|
| Auth | /auth | Authentication |
| Sell / Buy leads, offers, bids | /sell-leads, /buy-leads | Leads, Offers & Bids |
| Products, batches, inventory | /products, /batches | Products & Inventory |
| Deals, orders, grievances | /deals, /orders, /grievances | Deals, Orders & Grievances |
| Search, quota, inquiries, messaging, notifications, profiles, reports, dashboard, admin, public | various | Supporting Endpoints |
Rate limits
| Limiter | Default | Axis reported on 429 |
|---|---|---|
| OTP | 5 / 10 min per phone | otp |
| Login (phone) | 10 failures / 15 min | phone |
| Login (device) | 20 failures / 15 min | device |
| Login (IP) | 300 failures / 15 min | ip |
| Search | 120 / window | search |
Login limiters count failures only; a success refunds and clears the phone + device counters. Every 429 names the axis that rejected it in error.details.axis.