REST API Endpoints Reference Catalog

This living reference document is the exhaustive catalog of all HTTP REST API endpoints exposed by debelu-backend at https://api.debelu.com. Grounded directly in the 38 route modules in [debelu-backend/src/routes](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes), controller implementations, and Zod validator schemas, this catalog specifies request schemas, authorization scopes, rate limits, and response structures.

---

1. Global API Conventions & Protocol Standards

1.1 Base URL & Content Negotiation

• Production Base URL: https://api.debelu.com
• Default Content-Type: application/json; charset=utf-8
• Webhook Payloads: application/json parsed as raw byte buffers (express.raw()) for cryptographic HMAC signature verification.
• Media Uploads: image/jpeg, image/png, image/webp, image/gif up to 5 MB via POST /api/products/images.

1.2 Authentication & Authorization Headers

Except for explicitly marked public and webhook endpoints, all requests require an Authenticated Bearer Token:

Authorization: Bearer <supabase_jwt_access_token>

Privileged administrative actions require Multi-Factor Authenticator Assurance Level 2 (AAL2).

1.3 Request Tracing & Correlation

Every inbound request may provide a client-generated UUID v4 in X-Request-ID. If omitted, the perimeter middleware assigns a secure randomUUID(). The ID is echoed in the response:

X-Request-ID: 7b8971f4-3d02-45e6-8e56-11f879cf1d12

1.4 Rate Limiting Headers (IETF Draft-7)

RateLimit-Limit: 1000
RateLimit-Remaining: 994
RateLimit-Reset: 842

1.5 Idempotency Key Specification

All financial mutations (checkout payment intent creation, escrow releases, wallet refunds, and payout disbursements) require an Idempotency-Key header:

Idempotency-Key: 9a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

1.6 RFC 7807 Problem Details Error Schema

{
  "type": "https://api.debelu.com/errors/validation_failed",
  "title": "Bad Request",
  "status": 400,
  "detail": "Your store name needs at least 3 characters",
  "instance": "/api/vendors/applications",
  "code": "VALIDATION_FAILED",
  "requestId": "7b8971f4-3d02-45e6-8e56-11f879cf1d12",
  "timestamp": "2026-10-05T10:15:30.124Z"
}

---

2. Products, Catalog & Discovery Endpoints

Mounted via [productRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/productRoutes.ts), [catalogRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/catalogRoutes.ts), [flashSaleRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/flashSaleRoutes.ts), [bannerRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/bannerRoutes.ts), and [vibeRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/vibeRoutes.ts).

Method	Endpoint	Auth Level	Rate Limit	Cache TTL	Description / Key Request Params
GET	/api/products	Public	Global	300s	Paginated product listing with campus, category, and price filters.
GET	/api/products/search	Public	60 req/min	None	Full-text product and merchant search.
GET	/api/products/trending	Public	Global	60s	Algorithmic trending products based on 24h view and cart velocity.
GET	/api/products/new-arrivals	Public	Global	60s	Chronological feed of recently published campus listings.
GET	/api/products/exclusives	Public	Global	60s	Verified exclusive student vendor listings.
GET	/api/products/featured	Public	Global	300s	Hand-curated promotional campus products.
GET	/api/products/categories	Public	Global	3600s	Category hierarchy tree with active listing count aggregates.
GET	/api/products/suggestions	Public	Global	900s	Autocomplete search suggestions for search inputs.
POST	/api/products/images	Vendor / Staff	60 req/15m	None	Direct multipart image upload to Cloudflare R2 (limit: 5mb).
POST	/api/products/bulk	Public	Global	None	Bulk retrieval of product entities by array of UUIDs.
GET	/api/products/vendor/paginated	Vendor (Me)	Vendor	None	Authenticated vendor's complete inventory with private status codes.
GET	/api/products/vendor/:id	Optional	Global	60s	Public store inventory for a specific vendor profile ID.
GET	/api/products/:id	Optional	Global	None	Detailed product information, vendor reputation, and related items.
POST	/api/products/:id/stats/:type	Public	120 req/m	None	Atomic counter increment (view, cart_add, share).
POST	/api/products	Vendor / Staff	Vendor	None	Creates a new product listing (validateRequest(addProductSchema)).
PUT	/api/products/:id	Vendor (Owner)	Vendor	None	Updates product details, price, condition, or inventory count.
DELETE	/api/products/:id	Vendor / Staff	Vendor	None	Soft-deletes product listing; revokes search indexing.
DELETE	/api/products/bulk/delete	Admin	30 req/m	None	Administrative batch deletion of violating listings.
GET	/api/flash-sales/active	Public	Global	60s	Lists current active time-bounded campus flash discounts.
GET	/api/banners	Public	Global	300s	Campus marketing hero banners and promotional cards.
GET	/api/vibes	Public	Global	300s	Curated campus aesthetic feeds (e.g., "Hostel Essentials", "Tech Bro").

---

3. Cart, Orders & Escrow Lifecycle Endpoints

Mounted via [cartRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/cartRoutes.ts) and [orderRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/orderRoutes.ts).

Method	Endpoint	Auth Level	Rate Limit	Description & Request Invariants
GET	/api/cart	Authenticated	Global	Fetches authenticated user's persistent server cart with stock validation.
POST	/api/cart	Authenticated	60 req/m	Synchronizes client cart items; validates campus origin alignment.
DELETE	/api/cart	Authenticated	Global	Clears active cart state upon successful checkout initiation.
POST	/api/orders	Authenticated	30 req/m	Places order; validates pricing invariants, creates escrow record (pending_payment).
GET	/api/orders	Authenticated	Global	Paginated list of orders placed by authenticated buyer.
GET	/api/orders/vendor	Vendor	Global	Paginated list of inbound customer orders requiring fulfillment.
GET	/api/orders/vendor/counts	Vendor	Global	Status summary counts (pending, processing, shipped, delivered).
GET	/api/orders/:id	Buyer / Vendor / Staff	Global	Order detail view with shipping address and delivery status.
GET	/api/orders/:id/events	Buyer / Vendor / Staff	Global	Chronological audit trail of order state transitions.
POST	/api/orders/:id/accept	Vendor	30 req/m	Vendor acknowledges order; transitions state to processing.
POST	/api/orders/:id/status	Vendor	30 req/m	Updates fulfillment progress (processing $\rightarrow$ shipped).
POST	/api/orders/:id/verify-code	Vendor	10 req/m	Escrow Release Point: Submits buyer's 6-digit delivery PIN (pin: /^\d{6}$/). Unlocks funds upon verification.
POST	/api/orders/:id/cancel	Buyer / Vendor	15 req/m	Cancels unpaid order or initiates automated pre-fulfillment refund.
POST	/api/orders/:id/confirm	Buyer	20 req/m	Buyer manual receipt confirmation fallback.
GET	/api/orders/admin	Admin (canManageOrders)	60 req/m	Global order audit table across all campuses with escrow balances.

---

4. Payments, Financial Ledger & Payout Endpoints

Mounted via [paymentRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/paymentRoutes.ts), [transactionRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/transactionRoutes.ts), [reviewedPayoutBatchRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/reviewedPayoutBatchRoutes.ts), and [payoutTransferReconciliationRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/payoutTransferReconciliationRoutes.ts).

Method	Endpoint	Auth Level	Rate Limit	Invariants & Schema Requirements
POST	/api/payments/webhook	Webhook (Public)	None	Paystack Webhook: Evaluates x-paystack-signature via timing-safe HMAC SHA-512. Enqueues to BullMQ.
POST	/api/payments/initialize	Authenticated	15 req/m	Initializes Paystack checkout transaction; returns authorization URL. Mandatory Idempotency-Key.
POST	/api/payments/verify	Authenticated	30 req/m	Synchronously queries Paystack to confirm charge success (reference: string).
GET	/api/payments/banks	Authenticated	Global	Lists supported Nigerian commercial banks and fintech institutions with NIP codes.
POST	/api/payments/bank/resolve	Authenticated	10 req/m	Resolves 10-digit NUBAN account number against bank code; verifies account name.
POST	/api/payments/virtual-account	Authenticated	5 req/m	Generates dedicated dynamic NUBAN bank transfer virtual account for checkout.
GET	/api/transactions	Authenticated	Global	Double-entry general ledger statements for authenticated member.
POST	/api/payments/order/:orderId/process-refund	Admin (AAL2)	10 req/m	Executes wallet/gateway refund for disputed orders with audit reason.
GET	/api/payouts/batches	Admin (canManageFinances)	30 req/m	Lists staged vendor payout batches awaiting disbursement.
POST	/api/payouts/batches/:id/approve	Admin (AAL2)	5 req/m	Maker-Checker: Second staff officer approves payout batch for transfer dispatch.
POST	/api/payouts/reconcile	Admin (AAL2)	5 req/m	Initiates ledger reconciliation job comparing Paystack balance to escrow liabilities.

---

5. Users, Identity & Vendor Management Endpoints

Mounted via [userRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/userRoutes.ts) and [vendorRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/vendorRoutes.ts).

Method	Endpoint	Auth Level	Rate Limit	Description / Payload Schema
GET	/api/users/me	Authenticated	Global	Fetches member profile, campus affiliation, role, and verification badges.
PUT	/api/users/me	Authenticated	30 req/m	Updates name, phone number, campus, and avatar URL.
GET	/api/users/me/addresses	Authenticated	Global	Lists saved campus delivery addresses (hostel, hall, room number).
POST	/api/users/me/addresses	Authenticated	20 req/m	Creates a new delivery location (addAddressSchema).
PUT	/api/users/me/addresses/:id	Authenticated	20 req/m	Updates existing address coordinates or delivery instructions.
DELETE	/api/users/me/addresses/:id	Authenticated	20 req/m	Removes saved delivery address.
GET	/api/users/favorites	Authenticated	Global	Fetches bookmarked/favorited products.
POST	/api/users/favorites/toggle	Authenticated	60 req/m	Toggles product favorite state (productId: uuid).
POST	/api/users/content-flags	Authenticated	20 req/h	Submits Trust & Safety report on listing, review, or member.
GET	/api/users/me/account-status	Restricted / Suspended	Global	Allows restricted accounts to inspect suspension reason and appeal status.
POST	/api/vendors/applications	Authenticated	5 req/h	Submits student vendor merchant application with private student ID path.
GET	/api/vendors/applications/me	Authenticated	Global	Checks active vendor onboarding verification status.
GET	/api/vendors/profile/:id	Public	Global	Public vendor profile, reputation rating, and business policies.
PUT	/api/vendors/profile/:id	Vendor (Owner)	20 req/m	Updates store description, policies, vacation mode, and NUBAN bank account.
GET	/api/vendors/:id/analytics	Vendor (Owner)	30 req/m	Comprehensive sales revenue, visitor traffic, and order conversion metrics.
GET	/api/vendors/slug/:slug/available	Public	60 req/m	Verifies whether custom vendor store URL handle is available.

---

6. AI Assistant (Nduzi) & Communication Endpoints

Mounted via [geminiRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/geminiRoutes.ts), [chatRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/chatRoutes.ts), [conversationRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/conversationRoutes.ts), and [whatsappWebhookRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/whatsappWebhookRoutes.ts).

Method	Endpoint	Auth Level	Rate Limit	Description / Technical Behavior
POST	/api/gemini/stream	Authenticated	20 req/m (aiRateLimiter)	Nduzi AI Streaming: SSE connection executing multi-turn tool calling and contextual campus product recommendations (limit: 8mb).
POST	/api/gemini/session-title	Authenticated	30 req/m	Generates a 3-5 word semantic title for an AI conversational thread.
POST	/api/gemini/support-reply	Staff (requireStaff)	20 req/m	Generates AI-assisted suggested replies for customer support agents.
GET	/api/conversations	Authenticated	Global	Lists active buyer-to-vendor direct message threads.
GET	/api/conversations/:id/messages	Authenticated (Participant)	Global	Paginated message history for a specific conversation.
POST	/api/chat/send	Authenticated	60 req/m	Sends buyer-vendor message. Enforces ChatGuard regex inspection (blocks off-platform phone/bank leaks).
GET	/api/whatsapp/webhook	Webhook (Public)	Global	Meta WhatsApp Cloud API verification challenge handshake (hub.challenge).
POST	/api/whatsapp/webhook	Webhook (Public)	None	Inbound WhatsApp customer replies and delivery status notifications.
GET	/api/notifications	Authenticated	Global	Real-time member in-app push and transaction notification feed.
PUT	/api/notifications/:id/read	Authenticated	Global	Marks notification item as read.

---

7. Customer Support & Dispute Arbitration Endpoints

Mounted via [supportRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/supportRoutes.ts) and [disputeRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/disputeRoutes.ts).

Method	Endpoint	Auth Level	Rate Limit	Description / Schema
POST	/api/support	Authenticated	10 req/h	Opens support ticket (subject, message, category, orderId).
GET	/api/support/:id/messages	Ticket Creator / Staff	Global	Conversation log between user and Debelu customer support.
POST	/api/support/:id/messages	Ticket Creator / Staff	30 req/m	Appends message or signed attachment URL to support ticket.
PUT	/api/support/:id/rate	Ticket Creator	10 req/m	Submits Customer Satisfaction (CSAT) rating (1-5 stars) upon resolution.
POST	/api/disputes	Buyer / Vendor	5 req/d	Escalates order issue to formal escrow dispute (DisputeService).
POST	/api/disputes/:id/evidence	Buyer / Vendor	10 req/m	Uploads unboxing video, photo evidence, or campus hub waybill.
POST	/api/disputes/:id/resolve	Staff (AAL2)	10 req/m	Arbitrates dispute; executes either buyer refund or vendor escrow payout.

---

8. Data Privacy & Statutory Compliance Endpoints (NDPA / GDPR)

Mounted via [subjectPrivacyExportRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/subjectPrivacyExportRoutes.ts), [privacyExportArtifactRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/privacyExportArtifactRoutes.ts), [privacyErasurePlanRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/privacyErasurePlanRoutes.ts), and [privacyErasureExecutionRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/privacyErasureExecutionRoutes.ts).

Method	Endpoint	Auth Level	Rate Limit	Description / Compliance SLA
POST	/api/users/me/privacy-exports	Authenticated	5 req/h (exportLimiter)	Initiates NDPA Data Subject Access Request (DSAR) export job.
GET	/api/users/me/privacy-exports	Authenticated	Global	Lists status of generated personal data export archives.
GET	/api/users/me/privacy-exports/:id/artifact	Authenticated	10 req/h	Downloads encrypted ZIP package containing user PII JSON documents.
POST	/api/users/me/request-deletion	Authenticated	1 req/d	Submits Right to be Forgotten (RTBF) erasure request (30-day grace period).
POST	/api/users/me/cancel-deletion	Restricted / Suspended	Global	Cancels pending account deletion during statutory 30-day grace period.
POST	/api/privacy/erasure-plans	Compliance Staff	10 req/m	Assembles data erasure impact assessment plan for account deletion.
POST	/api/privacy/erasure-executions	Compliance Staff (AAL2)	5 req/m	Executes permanent data scrubbing across all erasable database tables.

---

9. Platform Governance, Observability & Health Endpoints

Mounted via [server.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/server.ts), [campusOperationsRouter.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/campusOperationsRouter.ts), and [platformConfigurationProposalRoutes.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/routes/platformConfigurationProposalRoutes.ts).

Method	Endpoint	Auth Level	Cache Policy	Description / Key Capabilities
GET	/health/live	Public	No-Store	Fast liveness probe returning HTTP 200 { status: "live" }.
GET	/health/ready	Public	No-Store	Deep readiness probe (checks live Postgres connection & Redis ping). Returns 503 if down.
GET	/health	Public	No-Store	Comprehensive SRE diagnostic dashboard checking 7 upstream dependencies.
GET	/api/status	Public	Memory (30s)	Non-sensitive platform maintenance state and operational component statuses.
POST	/api/csp-report	Public	30 req/15m	Ingests Content Security Policy (CSP) violation reports from browsers.
GET	/api/campus/operations/hubs	Campus Rep / Staff	Global	Lists physical campus pickup locations, hours, and appointed student reps.
POST	/api/platform/proposals	Staff (requireAdmin)	10 req/m	4-Eyes Governance: Proposes platform fee or category commission adjustments.
POST	/api/platform/proposals/:id/approve	Staff (AAL2)	5 req/m	Second administrative officer approves and activates platform configuration change.

---

10. Document Revision History

Revision	Date	Lead Author	Scope of Changes	Status
1.0.0	2026-10-05	Principal API Architect	Complete, exhaustive REST API endpoint catalog covering 38 route modules, authentication levels, rate limit quotas, and schemas.	Active Living Standard