{"openapi":"3.0.3","info":{"title":"Pamoja Bima API","version":"1.0.0","description":"REST API for the Pamoja Bima insurance app.\n\n**Authentication:** most endpoints need a JWT. Call `POST /api/auth/login` (e.g. a sample admin), copy the `token`, click **Authorize** above, paste it, then use **Try it out**.\n\nResponses are raw JSON; errors are `{ \"error\": string, \"code\"?: string }`."},"servers":[{"url":"https://pamojabima-backend.vercel.app","description":"Production (Vercel)"},{"url":"http://localhost:3000","description":"Local dev"}],"tags":[{"name":"System","description":"Health & version (public)."},{"name":"Auth","description":"Registration, login, OTP, password reset."},{"name":"Onboarding","description":"Client KYC steps (client role)."},{"name":"Catalog","description":"Providers & packages."},{"name":"Policies","description":"Client policies, drafts, payment, card."},{"name":"Payments","description":"Payment status."},{"name":"Agent","description":"Agent-assisted sales & wallet (agent role)."},{"name":"Admin","description":"Reviews, issuance, people, finance, catalog (admin role)."},{"name":"Notifications","description":"In-app notifications."},{"name":"Webhooks","description":"Snippe payment gateway callbacks."},{"name":"Dev","description":"Dev-only helpers (disabled in production)."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","nullable":true}}},"AuthResult":{"type":"object","properties":{"token":{"type":"string","description":"JWT bearer token"},"user":{"type":"object","description":"User DTO (id, phoneNumber, role, fullName, …)"},"profile":{"type":"object","nullable":true,"description":"Client profile (clients only)"}}}}},"paths":{"/api/health":{"get":{"tags":["System"],"summary":"Health check","operationId":"get_api_health","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/app/version":{"get":{"tags":["System"],"summary":"Latest app version + download URL","operationId":"get_api_app_version","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/register":{"post":{"tags":["Auth"],"summary":"Register a client (sends an email OTP)","operationId":"post_api_auth_register","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","minLength":9},"password":{"type":"string","minLength":6},"email":{"type":"string","format":"email"}},"required":["phoneNumber","password","email"],"additionalProperties":false}}}}}},"/api/auth/login":{"post":{"tags":["Auth"],"summary":"Sign in (returns a JWT + user)","operationId":"post_api_auth_login","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResult"}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","minLength":9},"password":{"type":"string","minLength":1}},"required":["phoneNumber","password"],"additionalProperties":false}}}}}},"/api/auth/verify-otp":{"post":{"tags":["Auth"],"summary":"Verify an OTP (registration → session; reset → ok)","operationId":"post_api_auth_verify-otp","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResult"}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","minLength":9},"code":{"type":"string","minLength":4},"purpose":{"type":"string","enum":["registration","password_reset"],"default":"registration"}},"required":["phoneNumber","code"],"additionalProperties":false}}}}}},"/api/auth/forgot-password":{"post":{"tags":["Auth"],"summary":"Request a password-reset code (email or SMS)","operationId":"post_api_auth_forgot-password","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","minLength":9},"channel":{"type":"string","enum":["sms","email"],"default":"email"}},"required":["phoneNumber"],"additionalProperties":false}}}}}},"/api/auth/reset-password":{"post":{"tags":["Auth"],"summary":"Reset the password with a verified code","operationId":"post_api_auth_reset-password","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","minLength":9},"code":{"type":"string","minLength":4},"newPassword":{"type":"string","minLength":6}},"required":["phoneNumber","code","newPassword"],"additionalProperties":false}}}}}},"/api/auth/me":{"get":{"tags":["Auth"],"summary":"Current user + profile (refresh session) (any signed-in user)","operationId":"get_api_auth_me","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResult"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/onboarding/status":{"get":{"tags":["Onboarding"],"summary":"Onboarding status (client)","operationId":"get_api_onboarding_status","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/onboarding/demographics":{"post":{"tags":["Onboarding"],"summary":"Submit step 1 — demographics (client)","operationId":"post_api_onboarding_demographics","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":1},"middleName":{"type":"string","default":""},"lastName":{"type":"string","minLength":1},"fullName":{"type":"string","minLength":2},"dateOfBirth":{"type":"string","minLength":4},"gender":{"type":"string","minLength":1},"maritalStatus":{"type":"string","minLength":1},"occupation":{"type":"string","minLength":1}},"required":["firstName","lastName","dateOfBirth","gender","maritalStatus","occupation"],"additionalProperties":false}}}}}},"/api/onboarding/contact":{"post":{"tags":["Onboarding"],"summary":"Submit step 2 — contact (client)","operationId":"post_api_onboarding_contact","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"anyOf":[{"anyOf":[{"not":{}},{"type":"string","format":"email"}]},{"type":"string","enum":[""]}]},"country":{"type":"string","minLength":1},"region":{"type":"string","minLength":1},"district":{"type":"string","minLength":1},"address":{"type":"string","minLength":1}},"required":["country","region","district","address"],"additionalProperties":false}}}}}},"/api/onboarding/identity/nin":{"post":{"tags":["Onboarding"],"summary":"Submit step 3 — NIN verification (client)","operationId":"post_api_onboarding_identity_nin","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nin":{"type":"string","pattern":"^\\d{8,20}$"}},"required":["nin"],"additionalProperties":false}}}}}},"/api/onboarding/identity/manual":{"post":{"tags":["Onboarding"],"summary":"Submit step 3 — manual ID (client)","operationId":"post_api_onboarding_identity_manual","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idType":{"type":"string","enum":["national_id","passport","driver_license","student_id","voter_id"]},"idNumber":{"type":"string","minLength":3},"idFrontImageUri":{"type":"string"},"idBackImageUri":{"type":"string"},"supportingDocUri":{"type":"string"},"birthCertificateUri":{"type":"string"},"marriageCertificateUri":{"type":"string"},"profileImageUri":{"type":"string"}},"required":["idType","idNumber"],"additionalProperties":false}}}}}},"/api/onboarding/upload":{"post":{"tags":["Onboarding"],"summary":"Upload ID/supporting images → Blob URLs (client)","operationId":"post_api_onboarding_upload","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"front":{"type":"string","format":"binary"},"back":{"type":"string","format":"binary"},"supporting":{"type":"string","format":"binary"}}}}}}}},"/api/providers":{"get":{"tags":["Catalog"],"summary":"List active providers (any signed-in user)","operationId":"get_api_providers","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/providers/{id}/packages":{"get":{"tags":["Catalog"],"summary":"List a provider's active packages (any signed-in user)","operationId":"get_api_providers__id__packages","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/packages/{id}":{"get":{"tags":["Catalog"],"summary":"Package detail (any signed-in user)","operationId":"get_api_packages__id","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/policies":{"get":{"tags":["Policies"],"summary":"List the client's policies (client)","operationId":"get_api_policies","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Policies"],"summary":"Create a draft policy (self-service) (client)","operationId":"post_api_policies","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clientProfileId":{"type":"string","minLength":1},"packageId":{"type":"string","minLength":1},"purchasedVia":{"type":"string","enum":["client_self","agent"]},"agentId":{"type":"string"},"type":{"type":"string","enum":["new_policy","renewal"],"default":"new_policy"},"renewedFromId":{"type":"string"}},"required":["clientProfileId","packageId","purchasedVia"],"additionalProperties":false}}}}}},"/api/policies/renewable":{"get":{"tags":["Policies"],"summary":"List renewable policies (client)","operationId":"get_api_policies_renewable","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/policies/{id}":{"get":{"tags":["Policies"],"summary":"Policy detail (any signed-in user)","operationId":"get_api_policies__id","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/policies/{id}/payment/initiate":{"post":{"tags":["Policies"],"summary":"Start a payment for a policy (client) (agent)","operationId":"post_api_policies__id__payment_initiate","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paymentType":{"type":"string","enum":["mobile","card"]},"amountGross":{"type":"integer","exclusiveMinimum":true,"minimum":0},"phoneNumber":{"type":"string"}},"required":["paymentType","amountGross"],"additionalProperties":false}}}}}},"/api/policies/{id}/card":{"get":{"tags":["Policies"],"summary":"Virtual card (issued policies) (any signed-in user)","operationId":"get_api_policies__id__card","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/payments/{id}/status":{"get":{"tags":["Payments"],"summary":"Poll payment status (any signed-in user)","operationId":"get_api_payments__id__status","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/agent/clients/find":{"get":{"tags":["Agent"],"summary":"Find a client by phone (agent)","operationId":"get_api_agent_clients_find","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"phone","in":"query","required":true,"description":"Client phone number","schema":{"type":"string"}}]}},"/api/agent/clients/quick-create":{"post":{"tags":["Agent"],"summary":"Quick-create an assisted client (agent)","operationId":"post_api_agent_clients_quick-create","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fullName":{"type":"string","minLength":2},"phoneNumber":{"type":"string","minLength":9}},"required":["fullName","phoneNumber"],"additionalProperties":false}}}}}},"/api/agent/clients":{"get":{"tags":["Agent"],"summary":"List assisted clients (agent)","operationId":"get_api_agent_clients","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/agent/policies":{"get":{"tags":["Agent"],"summary":"List assisted policies (agent)","operationId":"get_api_agent_policies","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Agent"],"summary":"Create a draft policy for a client (agent)","operationId":"post_api_agent_policies","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clientProfileId":{"type":"string","minLength":1},"packageId":{"type":"string","minLength":1},"purchasedVia":{"type":"string","enum":["client_self","agent"]},"agentId":{"type":"string"},"type":{"type":"string","enum":["new_policy","renewal"],"default":"new_policy"},"renewedFromId":{"type":"string"}},"required":["clientProfileId","packageId","purchasedVia"],"additionalProperties":false}}}}}},"/api/agent/policies/{id}/payment/initiate":{"post":{"tags":["Agent"],"summary":"Start an agent-assisted payment (agent)","operationId":"post_api_agent_policies__id__payment_initiate","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paymentType":{"type":"string","enum":["mobile","card"]},"amountGross":{"type":"integer","exclusiveMinimum":true,"minimum":0},"phoneNumber":{"type":"string"}},"required":["paymentType","amountGross"],"additionalProperties":false}}}}}},"/api/agent/dashboard":{"get":{"tags":["Agent"],"summary":"Agent dashboard metrics (agent)","operationId":"get_api_agent_dashboard","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/agent/wallet":{"get":{"tags":["Agent"],"summary":"Wallet balance (agent)","operationId":"get_api_agent_wallet","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/agent/wallet/transactions":{"get":{"tags":["Agent"],"summary":"Wallet transactions (agent)","operationId":"get_api_agent_wallet_transactions","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/agent/wallet/withdraw":{"post":{"tags":["Agent"],"summary":"Request a withdrawal (agent)","operationId":"post_api_agent_wallet_withdraw","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":true,"minimum":0},"destination":{"type":"string","minLength":3},"destinationType":{"type":"string","enum":["mobile","bank"],"default":"mobile"}},"required":["amount","destination"],"additionalProperties":false}}}}}},"/api/admin/onboarding/pending":{"get":{"tags":["Admin"],"summary":"Onboarding review queue (admin)","operationId":"get_api_admin_onboarding_pending","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/admin/onboarding/{clientId}/review":{"post":{"tags":["Admin"],"summary":"Approve/reject onboarding (admin)","operationId":"post_api_admin_onboarding__clientId__review","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["approved","rejected"]},"reason":{"type":"string"}},"required":["decision"],"additionalProperties":false}}}}}},"/api/admin/policies/pending-issuance":{"get":{"tags":["Admin"],"summary":"Issuance queue (admin)","operationId":"get_api_admin_policies_pending-issuance","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/admin/policies/{id}/issue":{"post":{"tags":["Admin"],"summary":"Issue a policy (admin)","operationId":"post_api_admin_policies__id__issue","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/admin/policies/{id}/reject":{"post":{"tags":["Admin"],"summary":"Reject issuance (admin)","operationId":"post_api_admin_policies__id__reject","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1}},"required":["reason"],"additionalProperties":false}}}}}},"/api/admin/agents":{"get":{"tags":["Admin"],"summary":"List agents (admin)","operationId":"get_api_admin_agents","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Admin"],"summary":"Create an agent (emails/SMS credentials) (admin)","operationId":"post_api_admin_agents","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fullName":{"type":"string","minLength":2},"phoneNumber":{"type":"string","minLength":9},"email":{"type":"string","format":"email"}},"required":["fullName","phoneNumber","email"],"additionalProperties":false}}}}}},"/api/admin/agents/{id}":{"get":{"tags":["Admin"],"summary":"Agent detail (admin)","operationId":"get_api_admin_agents__id","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/admin/admins":{"get":{"tags":["Admin"],"summary":"List admins (admin)","operationId":"get_api_admin_admins","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/admin/admins/invite":{"post":{"tags":["Admin"],"summary":"Invite an admin (admin)","operationId":"post_api_admin_admins_invite","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fullName":{"type":"string","minLength":2},"phoneNumber":{"type":"string","minLength":9},"email":{"type":"string","format":"email"}},"required":["fullName","phoneNumber","email"],"additionalProperties":false}}}}}},"/api/admin/users/{id}/status":{"post":{"tags":["Admin"],"summary":"Set user status (admin)","operationId":"post_api_admin_users__id__status","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","suspended","disabled"]}},"required":["status"],"additionalProperties":false}}}}}},"/api/admin/finance/overview":{"get":{"tags":["Admin"],"summary":"Finance overview (admin)","operationId":"get_api_admin_finance_overview","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["month","3m","6m","all"],"default":"all"}}]}},"/api/admin/finance/agents-performance":{"get":{"tags":["Admin"],"summary":"Agent leaderboard (admin)","operationId":"get_api_admin_finance_agents-performance","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["month","3m","6m","all"],"default":"all"}}]}},"/api/admin/finance/reconciliation":{"get":{"tags":["Admin"],"summary":"Reconciliation report (admin)","operationId":"get_api_admin_finance_reconciliation","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/admin/audit":{"get":{"tags":["Admin"],"summary":"Audit log (admin)","operationId":"get_api_admin_audit","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"string","default":"20"}}]}},"/api/admin/dashboard":{"get":{"tags":["Admin"],"summary":"Admin dashboard (admin)","operationId":"get_api_admin_dashboard","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/admin/providers":{"get":{"tags":["Admin"],"summary":"List all providers (admin)","operationId":"get_api_admin_providers","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Admin"],"summary":"Create a provider (admin)","operationId":"post_api_admin_providers","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2},"tagline":{"type":"string"}},"required":["name"],"additionalProperties":false}}}}}},"/api/admin/providers/{id}":{"patch":{"tags":["Admin"],"summary":"Update a provider (admin)","operationId":"patch_api_admin_providers__id","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"tagline":{"type":"string"},"logoUri":{"type":"string"},"isActive":{"type":"boolean"}},"additionalProperties":false}}}}}},"/api/admin/providers/{id}/packages":{"get":{"tags":["Admin"],"summary":"List all packages for a provider (admin)","operationId":"get_api_admin_providers__id__packages","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/admin/packages":{"post":{"tags":["Admin"],"summary":"Create a package (admin)","operationId":"post_api_admin_packages","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"providerId":{"type":"string","minLength":1},"name":{"type":"string","minLength":2},"description":{"type":"string","minLength":1},"coverage":{"type":"string","default":""},"exclusions":{"type":"string","default":""},"price":{"type":"integer","minimum":0},"durationDays":{"type":"integer","exclusiveMinimum":true,"minimum":0,"default":365}},"required":["providerId","name","description","price"],"additionalProperties":false}}}}}},"/api/admin/packages/{id}":{"patch":{"tags":["Admin"],"summary":"Update a package (admin)","operationId":"patch_api_admin_packages__id","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"coverage":{"type":"string"},"exclusions":{"type":"string"},"price":{"type":"integer","minimum":0},"durationDays":{"type":"integer","exclusiveMinimum":true,"minimum":0},"isActive":{"type":"boolean"}},"additionalProperties":false}}}}}},"/api/notifications":{"get":{"tags":["Notifications"],"summary":"List notifications (any signed-in user)","operationId":"get_api_notifications","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/notifications/unread-count":{"get":{"tags":["Notifications"],"summary":"Unread count (any signed-in user)","operationId":"get_api_notifications_unread-count","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/notifications/{id}/read":{"post":{"tags":["Notifications"],"summary":"Mark one as read (any signed-in user)","operationId":"post_api_notifications__id__read","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/notifications/read-all":{"post":{"tags":["Notifications"],"summary":"Mark all as read (any signed-in user)","operationId":"post_api_notifications_read-all","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (wrong role or suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]}]}},"/api/webhooks/snippe":{"post":{"tags":["Webhooks"],"summary":"Snippe payment/payout webhook (HMAC-signed)","operationId":"post_api_webhooks_snippe","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"x-snippe-signature","in":"header","required":true,"description":"HMAC-SHA256 of `${timestamp}.${rawBody}`","schema":{"type":"string"}},{"name":"x-snippe-timestamp","in":"header","required":true,"description":"Unix seconds","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["payment.completed","payment.failed","payment.voided","payment.expired","payout.completed","payout.failed","payout.voided"]},"data":{"type":"object","properties":{"reference":{"type":"string"},"status":{"type":"string"},"failureReason":{"type":"string","nullable":true}}}}}}}}}},"/api/dev/test-email":{"post":{"tags":["Dev"],"summary":"Send a test email (dev only)","operationId":"post_api_dev_test-email","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","format":"email"}},"required":["to"],"additionalProperties":false}}}}}},"/api/dev/reset":{"post":{"tags":["Dev"],"summary":"Wipe + re-seed the database (dev only)","operationId":"post_api_dev_reset","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}