admin/goodgo-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a6d1ef307c014e777832fe08230edfc51f50fd44
goodgo-platform/docs/api-endpoints.md
Ho Ngoc Hai 18b5980f29 docs: consolidate and update project documentation 
- Fix port numbers across all docs (API :3001, Web :3000)
- Add 6 missing modules to README, CLAUDE.md, and architecture doc
  (agents, health, inquiries, leads, reviews, metrics/web-vitals)
- Add Swagger UI reference and /api/v1 prefix notes
- Create docs/api-endpoints.md with complete REST API reference
- Create docs/README.md as documentation index
- Update deployment guide with Loki, Promtail, pg-backup services
- Update health check table with all current endpoints

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-04-10 23:32:00 +07:00

253 lines
9.3 KiB
Markdown
Raw Blame History

# API Endpoints Reference
All routes are prefixed with `/api/v1/` except health checks. Authentication uses Bearer JWT tokens.
> **Interactive docs**: Swagger UI is available at `http://localhost:3001/api/v1/docs` when running the API locally.
## Auth (`/auth`)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/auth/register` | Public | Register a new user |
| POST | `/auth/login` | Public | Login with phone and password |
| POST | `/auth/refresh` | Cookie | Refresh access token using httpOnly refresh cookie |
| POST | `/auth/logout` | JWT | Logout and clear auth cookies |
| POST | `/auth/exchange-token` | Public | Exchange OAuth token pair for httpOnly cookies |
| GET | `/auth/profile` | JWT | Get current user profile |
| GET | `/auth/profile/agent` | JWT | Get agent profile for current user |
| PATCH | `/auth/kyc` | Admin | Verify user KYC status |
### OAuth
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/auth/google` | Public | Initiate Google OAuth2 login |
| GET | `/auth/google/callback` | Public | Google OAuth2 callback |
| GET | `/auth/zalo` | Public | Initiate Zalo OAuth2 login |
| GET | `/auth/zalo/callback` | Public | Zalo OAuth2 callback |
### User Data (GDPR)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| DELETE | `/users/me` | JWT | Request account deletion (30-day grace period) |
| POST | `/users/me/cancel-deletion` | JWT | Cancel pending account deletion |
| GET | `/users/me/export` | JWT | Export user data (GDPR Article 20) |
| DELETE | `/users/:id/force` | Admin | Force-delete user immediately |
---
## Listings (`/listings`)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/listings` | JWT + Quota | Create a new property listing |
| GET | `/listings` | Public | Search and filter property listings |
| GET | `/listings/pending` | Admin | Get listings pending moderation |
| GET | `/listings/:id` | Public | Get listing details by ID |
| PATCH | `/listings/:id/status` | JWT | Update listing status |
| POST | `/listings/:id/media` | JWT | Upload media (multipart file upload) |
| PATCH | `/listings/:id/moderate` | Admin | Moderate a listing |
---
## Search (`/search`)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/search` | Public | Full-text and faceted property search |
| GET | `/search/geo` | Public | Geographic radius search |
| POST | `/search/reindex` | Admin | Reindex all properties in Typesense |
### Saved Searches (`/saved-searches`)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/saved-searches` | JWT | Save search filters |
| GET | `/saved-searches` | JWT | List saved searches |
| GET | `/saved-searches/:id` | JWT | Get saved search details |
| PATCH | `/saved-searches/:id` | JWT | Update saved search |
| DELETE | `/saved-searches/:id` | JWT | Delete saved search |
---
## Payments (`/payments`)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/payments` | JWT | Create a new payment |
| GET | `/payments` | JWT | List transactions for authenticated user |
| GET | `/payments/:id` | JWT | Get payment status by ID |
| POST | `/payments/:id/refund` | Admin | Refund a payment |
| POST | `/payments/callback/:provider` | Public | Payment provider webhook (VNPay, MoMo, ZaloPay) |
---
## Subscriptions (`/subscriptions`)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/subscriptions/plans` | Public | List all subscription plans |
| GET | `/subscriptions/plans/:tier` | Public | Get subscription plan by tier |
| POST | `/subscriptions` | JWT | Create a new subscription |
| PUT | `/subscriptions/upgrade` | JWT | Upgrade existing subscription |
| DELETE | `/subscriptions` | JWT | Cancel active subscription |
| POST | `/subscriptions/usage` | JWT | Record metered usage |
| GET | `/subscriptions/quota/:metric` | JWT | Check remaining quota for a metric |
| GET | `/subscriptions/billing` | JWT | Get billing history |
---
## Admin (`/admin`)
### User Management
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/admin/users` | Admin | List users with optional filters |
| GET | `/admin/users/:id` | Admin | Get user details by ID |
| PATCH | `/admin/users/status` | Admin | Update user active status |
| POST | `/admin/users/ban` | Admin | Ban or unban a user |
| POST | `/admin/subscriptions/adjust` | Admin | Adjust user subscription plan |
| GET | `/admin/dashboard` | Admin | Get admin dashboard statistics |
| GET | `/admin/revenue` | Admin | Get revenue statistics by date range |
| GET | `/admin/audit-logs` | Admin | Get admin audit logs |
### Moderation
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/admin/moderation` | Admin | Get listing moderation queue |
| POST | `/admin/moderation/approve` | Admin | Approve a listing |
| POST | `/admin/moderation/reject` | Admin | Reject a listing |
| POST | `/admin/moderation/bulk` | Admin | Bulk approve or reject listings |
| GET | `/admin/kyc` | Admin | Get KYC verification queue |
| POST | `/admin/kyc/approve` | Admin | Approve KYC verification |
| POST | `/admin/kyc/reject` | Admin | Reject KYC verification |
---
## Notifications (`/notifications`)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/notifications/history` | JWT | Get notification history |
| GET | `/notifications/preferences` | JWT | Get notification preferences |
| PUT | `/notifications/preferences` | JWT | Update notification preferences |
| GET | `/notifications/unread` | JWT | Get unread notifications |
| PATCH | `/notifications/:id/read` | JWT | Mark notification as read |
| PATCH | `/notifications/read-all` | JWT | Mark all notifications as read |
| GET | `/notifications/templates` | JWT | Get available notification templates |
---
## Analytics (`/analytics`)
All analytics endpoints require JWT and are quota-guarded.
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/analytics/market-report` | JWT + Quota | Get market report for a city |
| GET | `/analytics/price-trend` | JWT + Quota | Get price trend for a district |
| GET | `/analytics/heatmap` | JWT + Quota | Get price heatmap for a city |
| GET | `/analytics/district-stats` | JWT + Quota | Get statistics by district |
| GET | `/analytics/valuation` | JWT + Quota | Get automated property valuation (AVM) |
---
## Agents (`/agents`)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/agents/me/dashboard` | Agent | Get agent dashboard stats |
| POST | `/agents/:agentId/recalculate-score` | Admin | Recalculate agent quality score |
---
## Inquiries (`/inquiries`)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/inquiries` | JWT | Create inquiry for a listing |
| GET | `/inquiries/listing/:listingId` | JWT | List inquiries by listing |
| GET | `/inquiries/agent/me` | Agent | List inquiries for current agent |
| PATCH | `/inquiries/:id/read` | Agent | Mark inquiry as read |
---
## Leads (`/leads`)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/leads` | Agent | Create lead |
| GET | `/leads` | Agent | List leads for agent |
| GET | `/leads/stats` | Agent | Get lead statistics |
| PATCH | `/leads/:id/status` | Agent | Update lead status |
| DELETE | `/leads/:id` | Agent | Delete lead |
---
## Reviews (`/reviews`)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/reviews` | JWT | Create a review |
| GET | `/reviews` | Public | List reviews by target |
| GET | `/reviews/stats` | Public | Get aggregate rating stats for a target |
| GET | `/reviews/me` | JWT | Get reviews by authenticated user |
| DELETE | `/reviews/:id` | JWT | Delete own review |
---
## Health (`/health`)
Health endpoints are **not** prefixed with `/api/v1/`.
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/health` | Public | Liveness probe |
| GET | `/health/ready` | Public | Readiness probe (DB + Redis) |
| GET | `/health/db` | Public | Database connectivity check |
| GET | `/health/redis` | Public | Redis connectivity check |
---
## MCP (`/mcp`)
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/mcp/servers` | JWT | List available MCP servers |
| GET | `/mcp/:serverName/sse` | JWT | Open SSE connection to MCP server |
| POST | `/mcp/:serverName/messages` | JWT | Send message to MCP server session |
---
## Metrics
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/web-vitals` | Public | Ingest Core Web Vitals metrics |
---
## Authentication Summary
| Auth Type | Description |
|-----------|-------------|
| **Public** | No authentication required |
| **JWT** | Requires `Authorization: Bearer <token>` header |
| **Admin** | JWT + `ADMIN` role required |
| **Agent** | JWT + `AGENT` role required |
| **Quota** | JWT + subscription quota enforcement |
| **Cookie** | Uses httpOnly refresh token cookie |
## Rate Limiting
The following endpoints have stricter rate limits:
- Auth endpoints (register, login, refresh): `10 req/60s`
- OAuth callbacks: `10 req/60s`
- Payment callbacks: `60 req/60s`
- MCP endpoints: `30 req/60s`
- Default: `60 req/60s`
Reference in New Issue View Git Blame Copy Permalink