[
  {
    "method": "GET",
    "path": "/health",
    "controller": "Health Check",
    "middleware": [],
    "request": {},
    "response": {
      "200": {
        "status": "OK",
        "timestamp": "ISO string",
        "environment": "string"
      }
    },
    "used_models": [],
    "notes": "Public health check endpoint"
  },
  {
    "method": "POST",
    "path": "/api/auth/signup",
    "controller": "AuthController.signup",
    "middleware": ["validation"],
    "request": {
      "body": {
        "email": "string",
        "password": "string",
        "business_name": "string (optional)"
      }
    },
    "response": {
      "201": {
        "success": true,
        "data": {
          "user": "Supabase user object",
          "vendor": "Vendor profile",
          "access_token": "string",
          "refresh_token": "string"
        },
        "message": "User registered successfully"
      },
      "400": {
        "success": false,
        "error": "Email and password are required"
      },
      "409": {
        "success": false,
        "error": "User already exists"
      },
      "500": {
        "success": false,
        "error": "Registration failed"
      }
    },
    "used_models": ["User", "Vendor"],
    "notes": "Creates user account and vendor profile automatically"
  },
  {
    "method": "POST",
    "path": "/api/auth/login",
    "controller": "AuthController.login",
    "middleware": ["validation"],
    "request": {
      "body": {
        "email": "string",
        "password": "string"
      }
    },
    "response": {
      "200": {
        "success": true,
        "data": {
          "user": "Supabase user object",
          "vendor": "Vendor profile",
          "access_token": "string",
          "refresh_token": "string"
        },
        "message": "Login successful"
      },
      "400": {
        "success": false,
        "error": "Email and password are required"
      },
      "401": {
        "success": false,
        "error": "Invalid credentials"
      },
      "500": {
        "success": false,
        "error": "Login failed"
      }
    },
    "used_models": ["User", "Vendor"],
    "notes": "Authenticates user and returns session tokens"
  },
  {
    "method": "GET",
    "path": "/api/auth/profile",
    "controller": "AuthController.getProfile",
    "middleware": ["auth"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": {
          "user": "Supabase user object",
          "vendor": "Vendor profile"
        }
      },
      "401": {
        "success": false,
        "error": "Authentication required"
      },
      "500": {
        "success": false,
        "error": "Failed to retrieve profile"
      }
    },
    "used_models": ["User", "Vendor"],
    "notes": "Requires valid Bearer token"
  },
  {
    "method": "POST",
    "path": "/api/auth/logout",
    "controller": "AuthController.logout",
    "middleware": ["auth"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "message": "Logged out successfully"
      },
      "500": {
        "success": false,
        "error": "Logout failed"
      }
    },
    "used_models": [],
    "notes": "Requires valid Bearer token"
  },
  {
    "method": "GET",
    "path": "/api/vendors/me",
    "controller": "VendorController.getMyProfile",
    "middleware": ["auth", "requireVendor"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Vendor profile"
      }
    },
    "used_models": ["Vendor"],
    "notes": "Requires vendor role"
  },
  {
    "method": "POST",
    "path": "/api/vendors/onboarding",
    "controller": "VendorController.completeOnboarding",
    "middleware": ["auth", "requireVendor", "validation"],
    "request": {
      "body": {
        "business_name": "string (2-100 chars)",
        "profile_picture_url": "string (optional, URL)"
      }
    },
    "response": {
      "200": {
        "success": true,
        "data": "Updated vendor profile"
      }
    },
    "used_models": ["Vendor"],
    "notes": "Requires vendor role, completes onboarding"
  },
  {
    "method": "PUT",
    "path": "/api/vendors/profile",
    "controller": "VendorController.updateProfile",
    "middleware": ["auth", "requireVendor", "validation"],
    "request": {
      "body": {
        "business_name": "string (optional, 2-100 chars)",
        "profile_picture_url": "string (optional, URL)",
        "subscription_plan": "string (optional, enum)"
      }
    },
    "response": {
      "200": {
        "success": true,
        "data": "Updated vendor profile"
      }
    },
    "used_models": ["Vendor"],
    "notes": "Requires vendor role"
  },
  {
    "method": "GET",
    "path": "/api/vendors/:id",
    "controller": "VendorController.getVendorById",
    "middleware": ["auth", "requireAdmin"],
    "request": {
      "params": {
        "id": "string (UUID)"
      }
    },
    "response": {
      "200": {
        "success": true,
        "data": "Vendor profile"
      }
    },
    "used_models": ["Vendor"],
    "notes": "Requires admin role"
  },
  {
    "method": "GET",
    "path": "/api/vendors",
    "controller": "VendorController.getAllVendors",
    "middleware": ["auth", "requireAdmin"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Array of vendor profiles"
      }
    },
    "used_models": ["Vendor"],
    "notes": "Requires admin role"
  },
  {
    "method": "GET",
    "path": "/api/customers",
    "controller": "CustomersController.list",
    "middleware": ["auth", "requireVendor", "featureGate:customer_management"],
    "request": {
      "query": {
        "search": "string (optional)",
        "tag": "string (optional)"
      }
    },
    "response": {
      "200": {
        "success": true,
        "data": "Array of customers"
      },
      "403": {
        "error": "Customer management not available on your plan"
      }
    },
    "used_models": ["Customer"],
    "notes": "Requires vendor role and customer_management feature"
  },
  {
    "method": "POST",
    "path": "/api/customers",
    "controller": "CustomersController.addOrLink",
    "middleware": ["auth", "requireVendor", "featureGate:customer_management"],
    "request": {
      "body": "Customer data"
    },
    "response": {
      "201": {
        "success": true,
        "data": "Created customer"
      },
      "403": {
        "error": "Customer management not available on your plan"
      }
    },
    "used_models": ["Customer"],
    "notes": "Requires vendor role and customer_management feature"
  },
  {
    "method": "GET",
    "path": "/api/customers/:customerId",
    "controller": "CustomersController.getProfile",
    "middleware": ["auth", "requireVendor", "featureGate:customer_management"],
    "request": {
      "params": {
        "customerId": "string (UUID)"
      }
    },
    "response": {
      "200": {
        "success": true,
        "data": "Customer profile"
      },
      "403": {
        "error": "Customer management not available on your plan"
      },
      "404": {
        "error": "Customer not found"
      }
    },
    "used_models": ["Customer"],
    "notes": "Requires vendor role and customer_management feature"
  },
  {
    "method": "PUT",
    "path": "/api/customers/:customerId",
    "controller": "CustomersController.update",
    "middleware": ["auth", "requireVendor", "featureGate:customer_management"],
    "request": {
      "params": {
        "customerId": "string (UUID)"
      },
      "body": "Customer update data"
    },
    "response": {
      "200": {
        "success": true,
        "data": "Updated customer"
      },
      "403": {
        "error": "Customer management not available on your plan"
      }
    },
    "used_models": ["Customer"],
    "notes": "Requires vendor role and customer_management feature"
  },
  {
    "method": "POST",
    "path": "/api/customers/:customerId/measurements",
    "controller": "CustomersController.upsertMeasurements",
    "middleware": ["auth", "requireVendor", "featureGate:customer_management"],
    "request": {
      "params": {
        "customerId": "string (UUID)"
      },
      "body": "Measurements data"
    },
    "response": {
      "200": {
        "success": true,
        "data": "Updated measurements"
      },
      "403": {
        "error": "Customer management not available on your plan"
      }
    },
    "used_models": ["Customer", "Measurement"],
    "notes": "Requires vendor role and customer_management feature"
  },
  {
    "method": "DELETE",
    "path": "/api/customers/:customerId",
    "controller": "CustomersController.unlink",
    "middleware": ["auth", "requireVendor", "featureGate:customer_management"],
    "request": {
      "params": {
        "customerId": "string (UUID)"
      }
    },
    "response": {
      "200": {
        "success": true
      },
      "403": {
        "error": "Customer management not available on your plan"
      }
    },
    "used_models": ["Customer"],
    "notes": "Requires vendor role and customer_management feature"
  },
  {
    "method": "POST",
    "path": "/api/invoices",
    "controller": "InvoicesController.create",
    "middleware": ["auth", "requireVendor", "featureGate:invoicing_enabled"],
    "request": {
      "body": "Invoice data"
    },
    "response": {
      "201": {
        "success": true,
        "data": "Created invoice"
      },
      "403": {
        "error": "Invoicing not available on your plan"
      }
    },
    "used_models": ["Invoice"],
    "notes": "Requires vendor role and invoicing_enabled feature"
  },
  {
    "method": "GET",
    "path": "/api/invoices/view/:public_code",
    "controller": "InvoicesController.viewPublic",
    "middleware": [],
    "request": {
      "params": {
        "public_code": "string"
      }
    },
    "response": {
      "200": {
        "success": true,
        "data": "Invoice data"
      }
    },
    "used_models": ["Invoice"],
    "notes": "Public endpoint for viewing invoices"
  },
  {
    "method": "POST",
    "path": "/api/invoices/:id/mark-paid",
    "controller": "InvoicesController.markPaid",
    "middleware": [],
    "request": {
      "params": {
        "id": "string (UUID)"
      }
    },
    "response": {
      "200": {
        "success": true
      }
    },
    "used_models": ["Invoice"],
    "notes": "Webhook endpoint for payment confirmation"
  },
  {
    "method": "GET",
    "path": "/api/invoices",
    "controller": "InvoicesController.list",
    "middleware": ["auth", "requireVendor", "featureGate:invoicing_enabled"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Array of invoices"
      },
      "403": {
        "error": "Invoicing not available on your plan"
      }
    },
    "used_models": ["Invoice"],
    "notes": "Requires vendor role and invoicing_enabled feature"
  },
  {
    "method": "GET",
    "path": "/api/invoices/:id/download",
    "controller": "InvoicesController.downloadPdf",
    "middleware": ["auth", "requireVendor", "featureGate:invoicing_enabled"],
    "request": {
      "params": {
        "id": "string (UUID)"
      }
    },
    "response": {
      "200": "PDF file",
      "403": {
        "error": "Invoicing not available on your plan"
      }
    },
    "used_models": ["Invoice"],
    "notes": "Requires vendor role and invoicing_enabled feature"
  },
  {
    "method": "DELETE",
    "path": "/api/invoices/:id",
    "controller": "InvoicesController.delete",
    "middleware": ["auth", "requireVendor", "featureGate:invoicing_enabled"],
    "request": {
      "params": {
        "id": "string (UUID)"
      }
    },
    "response": {
      "200": {
        "success": true
      },
      "403": {
        "error": "Invoicing not available on your plan"
      }
    },
    "used_models": ["Invoice"],
    "notes": "Requires vendor role and invoicing_enabled feature"
  },
  {
    "method": "GET",
    "path": "/api/invoices/transactions",
    "controller": "InvoicesController.listTransactions",
    "middleware": ["auth", "requireVendor", "featureGate:invoicing_enabled"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Array of transactions"
      },
      "403": {
        "error": "Invoicing not available on your plan"
      }
    },
    "used_models": ["Invoice", "Payment"],
    "notes": "Requires vendor role and invoicing_enabled feature"
  },
  {
    "method": "POST",
    "path": "/api/reminders/create",
    "controller": "RemindersController.create",
    "middleware": ["auth", "requireVendor", "featureGate:reminders"],
    "request": {
      "body": "Reminder data"
    },
    "response": {
      "200": {
        "success": true,
        "data": "Created reminder"
      },
      "403": {
        "error": "Reminders not available on your plan"
      }
    },
    "used_models": ["Reminder"],
    "notes": "Requires vendor role and reminders feature"
  },
  {
    "method": "GET",
    "path": "/api/reminders/list",
    "controller": "RemindersController.list",
    "middleware": ["auth", "requireVendor", "featureGate:reminders"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Array of reminders"
      },
      "403": {
        "error": "Reminders not available on your plan"
      }
    },
    "used_models": ["Reminder"],
    "notes": "Requires vendor role and reminders feature"
  },
  {
    "method": "POST",
    "path": "/api/reminders/send/:id",
    "controller": "RemindersController.send",
    "middleware": ["auth", "requireVendor", "featureGate:reminders"],
    "request": {
      "params": {
        "id": "string (UUID)"
      }
    },
    "response": {
      "200": {
        "success": true
      },
      "403": {
        "error": "Reminders not available on your plan"
      }
    },
    "used_models": ["Reminder"],
    "notes": "Requires vendor role and reminders feature"
  },
  {
    "method": "GET",
    "path": "/api/subscriptions/plans",
    "controller": "SubscriptionsController.getPlans",
    "middleware": [],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Array of subscription plans"
      }
    },
    "used_models": ["Plan"],
    "notes": "Public endpoint for viewing available plans"
  },
  {
    "method": "GET",
    "path": "/api/subscriptions/my-plan",
    "controller": "SubscriptionsController.getMyPlan",
    "middleware": ["auth"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Current subscription plan"
      }
    },
    "used_models": ["Plan", "Subscription"],
    "notes": "Requires authentication"
  },
  {
    "method": "POST",
    "path": "/api/subscriptions/activate",
    "controller": "SubscriptionsController.activatePlan",
    "middleware": ["auth"],
    "request": {
      "body": "Plan activation data"
    },
    "response": {
      "200": {
        "success": true,
        "data": "Activated plan"
      }
    },
    "used_models": ["Plan", "Subscription"],
    "notes": "Requires authentication"
  },
  {
    "method": "GET",
    "path": "/api/subscriptions/trial-offer",
    "controller": "SubscriptionsController.getTrialOffer",
    "middleware": ["auth"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Trial offer details"
      }
    },
    "used_models": ["Plan"],
    "notes": "Requires authentication"
  },
  {
    "method": "POST",
    "path": "/api/subscriptions/accept-trial",
    "controller": "SubscriptionsController.acceptTrial",
    "middleware": ["auth"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Trial activated"
      }
    },
    "used_models": ["Plan", "Subscription"],
    "notes": "Requires authentication"
  },
  {
    "method": "GET",
    "path": "/api/subscriptions/my-features",
    "controller": "SubscriptionsController.getAvailableFeatures",
    "middleware": ["auth"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Array of available features"
      }
    },
    "used_models": ["Feature"],
    "notes": "Requires authentication"
  },
  {
    "method": "POST",
    "path": "/api/kyc/submit",
    "controller": "KYCController.submit",
    "middleware": ["auth", "requireVendor"],
    "request": {
      "body": "KYC submission data"
    },
    "response": {
      "200": {
        "success": true,
        "data": "KYC submission"
      }
    },
    "used_models": ["KYC"],
    "notes": "Requires vendor role"
  },
  {
    "method": "GET",
    "path": "/api/kyc/status",
    "controller": "KYCController.status",
    "middleware": ["auth", "requireVendor"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "KYC status"
      }
    },
    "used_models": ["KYC"],
    "notes": "Requires vendor role"
  },
  {
    "method": "GET",
    "path": "/api/kyc/admin/pending",
    "controller": "KYCController.adminListPending",
    "middleware": ["auth", "requireAdmin"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Array of pending KYC submissions"
      }
    },
    "used_models": ["KYC"],
    "notes": "Requires admin role"
  },
  {
    "method": "POST",
    "path": "/api/kyc/admin/:vendorId/review",
    "controller": "KYCController.adminReview",
    "middleware": ["auth", "requireAdmin"],
    "request": {
      "params": {
        "vendorId": "string (UUID)"
      },
      "body": "Review decision"
    },
    "response": {
      "200": {
        "success": true,
        "data": "Review result"
      }
    },
    "used_models": ["KYC"],
    "notes": "Requires admin role"
  },
  {
    "method": "POST",
    "path": "/api/market-prices",
    "controller": "MarketPricesController.submit",
    "middleware": ["auth"],
    "request": {
      "body": "Market price data"
    },
    "response": {
      "200": {
        "success": true,
        "data": "Submitted price"
      }
    },
    "used_models": ["PriceReport"],
    "notes": "Requires authentication"
  },
  {
    "method": "GET",
    "path": "/api/market-prices",
    "controller": "MarketPricesController.list",
    "middleware": ["auth"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Array of market prices"
      }
    },
    "used_models": ["PriceReport"],
    "notes": "Requires authentication"
  },
  {
    "method": "GET",
    "path": "/api/market-prices/suggestions",
    "controller": "MarketPricesController.suggestions",
    "middleware": ["auth"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Price suggestions"
      }
    },
    "used_models": ["PriceReport"],
    "notes": "Requires authentication"
  },
  {
    "method": "PATCH",
    "path": "/api/market-prices/admin/users/:id/pricing-access",
    "controller": "MarketPricesController.updatePricingAccess",
    "middleware": ["auth", "requireAdmin"],
    "request": {
      "params": {
        "id": "string (UUID)"
      },
      "body": "Pricing access update"
    },
    "response": {
      "200": {
        "success": true,
        "data": "Updated access"
      }
    },
    "used_models": ["User"],
    "notes": "Requires admin role"
  },
  {
    "method": "GET",
    "path": "/api/admin/users",
    "controller": "AdminController.listAdmins",
    "middleware": ["auth", "requireAdmin"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Array of admin users"
      }
    },
    "used_models": ["User"],
    "notes": "Requires admin role"
  },
  {
    "method": "POST",
    "path": "/api/admin/users",
    "controller": "AdminController.createAdmin",
    "middleware": ["auth", "requireAdmin"],
    "request": {
      "body": "Admin user data"
    },
    "response": {
      "200": {
        "success": true,
        "data": "Created admin user"
      }
    },
    "used_models": ["User"],
    "notes": "Requires admin role"
  },
  {
    "method": "PATCH",
    "path": "/api/admin/users/:id/permissions",
    "controller": "AdminController.updateAdminPermissions",
    "middleware": ["auth", "requireAdmin"],
    "request": {
      "params": {
        "id": "string (UUID)"
      },
      "body": "Permissions update"
    },
    "response": {
      "200": {
        "success": true,
        "data": "Updated permissions"
      }
    },
    "used_models": ["User"],
    "notes": "Requires admin role"
  },
  {
    "method": "GET",
    "path": "/api/admin/settings",
    "controller": "AdminController.getSettings",
    "middleware": ["auth", "requireAdmin"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Admin settings"
      }
    },
    "used_models": ["AdminSettings"],
    "notes": "Requires admin role"
  },
  {
    "method": "PATCH",
    "path": "/api/admin/settings",
    "controller": "AdminController.updateSettings",
    "middleware": ["auth", "requireAdmin"],
    "request": {
      "body": "Settings update"
    },
    "response": {
      "200": {
        "success": true,
        "data": "Updated settings"
      }
    },
    "used_models": ["AdminSettings"],
    "notes": "Requires admin role"
  },
  {
    "method": "GET",
    "path": "/api/admin/logs",
    "controller": "AdminController.getLogs",
    "middleware": ["auth", "requireAdmin"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "System logs"
      }
    },
    "used_models": [],
    "notes": "Requires admin role"
  },
  {
    "method": "PATCH",
    "path": "/api/admin/feature-flags",
    "controller": "AdminController.updateFeatureFlags",
    "middleware": ["auth", "requireAdmin"],
    "request": {
      "body": "Feature flags update"
    },
    "response": {
      "200": {
        "success": true,
        "data": "Updated feature flags"
      }
    },
    "used_models": ["Feature"],
    "notes": "Requires admin role"
  },
  {
    "method": "PATCH",
    "path": "/api/admin/kyc/:id",
    "controller": "AdminController.approveKYCOrPricing",
    "middleware": ["auth", "requireAdmin"],
    "request": {
      "params": {
        "id": "string (UUID)"
      },
      "body": "Approval decision"
    },
    "response": {
      "200": {
        "success": true,
        "data": "Approval result"
      }
    },
    "used_models": ["KYC"],
    "notes": "Requires admin role"
  },
  {
    "method": "POST",
    "path": "/api/admin/impersonate",
    "controller": "AdminController.impersonate",
    "middleware": ["auth", "requireAdmin"],
    "request": {
      "body": "Impersonation data"
    },
    "response": {
      "200": {
        "success": true,
        "data": "Impersonation session"
      }
    },
    "used_models": ["User"],
    "notes": "Requires admin role"
  },
  {
    "method": "GET",
    "path": "/api/admin/audit-trail",
    "controller": "AdminController.getAuditTrail",
    "middleware": ["auth", "requireAdmin"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Audit trail"
      }
    },
    "used_models": [],
    "notes": "Requires admin role"
  },
  {
    "method": "GET",
    "path": "/api/admin/support-tickets",
    "controller": "AdminController.getSupportTickets",
    "middleware": ["auth", "requireAdmin"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Array of support tickets"
      }
    },
    "used_models": ["SupportTicket"],
    "notes": "Requires admin role"
  },
  {
    "method": "PATCH",
    "path": "/api/admin/support-tickets/:id",
    "controller": "AdminController.updateSupportTicket",
    "middleware": ["auth", "requireAdmin"],
    "request": {
      "params": {
        "id": "string (UUID)"
      },
      "body": "Ticket update"
    },
    "response": {
      "200": {
        "success": true,
        "data": "Updated ticket"
      }
    },
    "used_models": ["SupportTicket"],
    "notes": "Requires admin role"
  },
  {
    "method": "GET",
    "path": "/api/admin/notifications",
    "controller": "AdminController.getAdminNotifications",
    "middleware": ["auth", "requireAdmin"],
    "request": {},
    "response": {
      "200": {
        "success": true,
        "data": "Array of admin notifications"
      }
    },
    "used_models": ["Notification"],
    "notes": "Requires admin role"
  }
]
