{"openapi":"3.0.3","info":{"title":"FUSE Brand API (External)","version":"1.0.0","description":"Server-to-server API exposing the FUSE brand-admin surface so a single brand/tenant can build its own admin frontend. Every request is authenticated with an API key bound to exactly one clinic; all data is auto-scoped to that clinic and cannot reach another brand's data. Isolation is enforced by application-layer clinic filtering on every query.\n\nCOVERAGE: 215 operations across 177 paths, and EVERY ONE is available to every brand. There is no per-clinic enablement step and no `403 ENDPOINT_NOT_ENABLED` — that gate was removed on 2026-09-18 (KAN-1996). Until then 112 of these operations were held behind per-clinic, per-group flags that nothing in the product could set; the `Pending` tag, the `x-fuse-pending` extension and the `x-fuse-pending-group` extension described that scheme and have been removed with it. What still governs access is unchanged: your API key and its scopes, the clinic the key belongs to (every read and write is filtered to it), your plan's entitlements for the two commercially-gated areas — Affiliates (`AFFILIATES_TIER_REQUIRED`) and CRM Connect (`CRM_TIER_REQUIRED`) — and rate limits.\n\nAUTH: the external /api/v1 surface uses an API key (`x-api-key`, ApiKeyAuth). Key management (/api-keys) and /auth/signin live at the API root and use a brand-admin JWT (BearerAuth); /auth/signin itself is unauthenticated.\n\nSCOPES: every key carries scopes; read-only is the default and mutating endpoints require the `write` scope (403 INSUFFICIENT_SCOPE otherwise). Keys default to a 1-year expiry.\n\nRATE LIMITING: every endpoint may additionally return `429 Too Many Requests` with a `Retry-After` header; 429 is not repeated on each operation below."},"servers":[{"url":"https://api-dev.fusehealth.com","description":"Development"},{"url":"https://api.fusehealth.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Auth & Key Management","description":"Key management uses a brand-admin JWT (from /auth/signin), NOT an API key. Everything else uses x-api-key."},{"name":"Orders"},{"name":"Customers"},{"name":"Programs","description":"Modern KAN-414 program surface. Every /:id path is scoped to the key's clinic (404 on anything it does not own)."},{"name":"Program Templates & Titration","description":"Shared FUSE catalogues (global by design — same posture as GET /config/fees). No clinic filter, no PHI."},{"name":"Products & Catalog"},{"name":"Payouts & Refunds"},{"name":"Billing"},{"name":"Organization"},{"name":"Onboarding"},{"name":"Page Builder"},{"name":"Refund Requests","description":"Incoming patient-initiated refund-request triage. PENDING — approve moves real money; gated behind per-clinic enablement (ask your FUSE contact)."},{"name":"Treatments","description":"Legacy treatment surface (programs are the modern surface). Writes are pending a product decision."},{"name":"Dashboard & Analytics","description":"Clinic-level aggregates only (recent-activity is HIPAA-scrubbed). Reads take clinicId from the key, never the query."},{"name":"CRM · Contacts"},{"name":"CRM · Tags"},{"name":"CRM · Sequences"},{"name":"CRM · Templates"},{"name":"CRM · Connection","description":"Connect the brand's OWN CRM (GoHighLevel). PENDING (third-party secret custody) + tier-gated (hasCrmIntegration)."},{"name":"Affiliate Program","description":"Affiliate/referral module. PENDING (money movement) + tier-gated (Affiliates plan entitlement resolved from the key's clinic)."},{"name":"Team & Users","description":"Brand-staff management. PENDING — exposes staff identity/2FA and grants/revokes FUSE-platform access."},{"name":"Organization & Clinic","description":"Clinic settings. GET /clinic and GET /config/fees are live; org profile + SendGrid email-domain auth + logo upload are PENDING (shared-infra/DNS + org writes)."},{"name":"Custom Website","description":"Storefront/portal config (CustomWebsite). No PHI. logo-proxy is a pending CORS-convenience byte proxy."},{"name":"Support & Conversations","description":"Patient support threads + tickets. PENDING — contains patient PHI (authors + messages). Every handler 404s anything outside the key's clinic."},{"name":"Forms & Global Products","description":"Global-product intake-form builder (TenantProductForm rows). PENDING — builder surface behind per-clinic enablement (ask your FUSE contact)."},{"name":"Intake Requests"},{"name":"Misc / Uploads"}],"paths":{"/api/v1/products/{id}/upload-image":{"post":{"tags":["Products & Catalog"],"summary":"Upload or remove a product's image.","operationId":"postApiV1ProductsIdUploadImage","description":"Uploads (multipart) or removes a product image for one of the key clinic's own products. Write-scoped, S3-backed. Gated per-clinic (v1_products_writes).","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"type":"object","properties":{"removeImage":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/public/products/{productId}/pharmacy-coverages":{"get":{"tags":["Products & Catalog"],"summary":"List a product's pharmacy coverages (clinic-scoped).","operationId":"getApiV1PublicProductsProductIdPharmacyCoverages","description":"Pharmacy coverages for a product owned by the key's clinic (or a shared platform product). 404 for unknown/cross-brand/non-UUID id. Gated per-clinic (v1_products_writes).","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"productId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/programs/copilot/draft":{"post":{"tags":["Programs"],"summary":"Draft a program with FUSE Copilot (AI).","operationId":"postApiV1ProgramsCopilotDraft","description":"Generates a draft program for the key's clinic via the AI copilot. External LLM dependency; returns 503 when copilot is unconfigured. Write-scoped. Gated per-clinic (v1_copilot).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"description":"Copilot unavailable."}}}},"/api/v1/organization/sms/twilio":{"get":{"tags":["Organization"],"summary":"Get the clinic's Twilio SMS config.","operationId":"getApiV1OrganizationSmsTwilio","description":"Returns the clinic's stored Twilio config (auth token never returned). Gated per-clinic (v1_org_sms).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"put":{"tags":["Organization"],"summary":"Set the clinic's Twilio SMS config.","operationId":"putApiV1OrganizationSmsTwilio","description":"Stores the clinic's Twilio account SID / auth token (encrypted) / from-number. Write-scoped. Gated per-clinic (v1_org_sms).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"accountSid":{"type":"string"},"authToken":{"type":"string"},"phoneNumber":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"delete":{"tags":["Organization"],"summary":"Remove the clinic's Twilio SMS config.","operationId":"deleteApiV1OrganizationSmsTwilio","description":"Clears the clinic's stored Twilio config. Write-scoped. Gated per-clinic (v1_org_sms).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/organization/sms/status":{"get":{"tags":["Organization"],"summary":"SMS provisioning status (AWS Pinpoint).","operationId":"getApiV1OrganizationSmsStatus","description":"Toll-free number + free-tier usage for the clinic. External AWS Pinpoint dependency. Gated per-clinic (v1_org_sms).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/organization/sms/activate":{"post":{"tags":["Organization"],"summary":"Provision a toll-free SMS number (AWS Pinpoint).","operationId":"postApiV1OrganizationSmsActivate","description":"Provisions a billable toll-free number for the clinic via AWS Pinpoint. Write-scoped, external + billable. Gated per-clinic (v1_org_sms).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/organization/sms/release":{"delete":{"tags":["Organization"],"summary":"Release the clinic's toll-free SMS number.","operationId":"deleteApiV1OrganizationSmsRelease","description":"Releases the clinic's provisioned toll-free number (AWS Pinpoint teardown). Write-scoped, external. Gated per-clinic (v1_org_sms).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/clinic/custom-domain/start":{"post":{"tags":["Organization"],"summary":"Begin custom-domain setup (ACM cert request).","operationId":"postApiV1ClinicCustomDomainStart","description":"Requests an ACM certificate for the clinic's custom domain. Mutates SHARED ACM/ALB infra. Write-scoped, external. Gated per-clinic (v1_custom_domain).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/clinic/custom-domain/verify":{"post":{"tags":["Organization"],"summary":"Verify custom-domain DNS/ACM validation.","operationId":"postApiV1ClinicCustomDomainVerify","description":"Checks ACM/DNS validation for the clinic's custom domain. Shared infra. Write-scoped, external. Gated per-clinic (v1_custom_domain).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/clinic/custom-domain/finalize":{"post":{"tags":["Organization"],"summary":"Finalize custom-domain (attach to ALB).","operationId":"postApiV1ClinicCustomDomainFinalize","description":"Attaches the validated custom domain to the ALB listener. Shared infra. Write-scoped, external. Gated per-clinic (v1_custom_domain).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/clinic/custom-domain/remove":{"post":{"tags":["Organization"],"summary":"Remove the clinic's custom domain.","operationId":"postApiV1ClinicCustomDomainRemove","description":"Detaches + tears down the clinic's custom domain (ACM/ALB). Shared infra. Write-scoped, external. Gated per-clinic (v1_custom_domain).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/organization/update":{"put":{"tags":["Organization"],"summary":"Update organization/clinic profile.","operationId":"putApiV1OrganizationUpdate","description":"Updates the key clinic's organization profile. A customDomain change triggers ACM. Write-scoped. Gated per-clinic (v1_org_clinic).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/clinic/{id}":{"put":{"tags":["Organization"],"summary":"Update the key's clinic (clinic-scoped).","operationId":"putApiV1ClinicById","description":"Updates the clinic identified by id — which MUST equal the key's clinic, else 404. Write-scoped. Gated per-clinic (v1_org_clinic).","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/clinic/check-slug/{slug}":{"get":{"tags":["Organization"],"summary":"Check clinic-slug availability.","operationId":"getApiV1ClinicCheckSlugBySlug","description":"Returns whether a clinic slug is available. Gated per-clinic (v1_org_clinic).","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"available":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/stripe/connect/status":{"get":{"tags":["Billing"],"summary":"Stripe Connect account status.","operationId":"getApiV1StripeConnectStatus","description":"Returns the clinic's Stripe Connect (payout account) status. External Stripe API, clinic-scoped, 5-min cache. Gated per-clinic (v1_billing).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/page-builder/upload-image":{"post":{"tags":["Page Builder"],"summary":"Upload a page-builder image.","operationId":"postApiV1PageBuilderUploadImage","description":"Uploads an image (S3) for the clinic's page builder and records a BrandPageImage. Write-scoped, external. Gated per-clinic (v1_page_builder).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/page-builder/pages":{"get":{"tags":["Page Builder"],"summary":"List the key clinic's pages.","operationId":"getApiV1PageBuilderPages","description":"Lists this brand's page-builder pages. Gated per-clinic (v1_page_builder).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"tags":["Page Builder"],"summary":"Create a new draft page.","operationId":"postApiV1PageBuilderPages","description":"Creates a new draft page for the clinic. Write-scoped. Gated per-clinic (v1_page_builder).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string"},"pageType":{"type":"string"},"isHomepage":{"type":"boolean"},"draftContent":{"type":"object"},"seoTitle":{"type":"string"},"seoDescription":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Slug already in use for this clinic."}}}},"/api/v1/page-builder/pages/{id}":{"get":{"tags":["Page Builder"],"summary":"Fetch one page (clinic-scoped).","operationId":"getApiV1PageBuilderPagesId","description":"Fetch a single page owned by the key's clinic. 404 for unknown/cross-clinic/non-UUID id. Gated per-clinic (v1_page_builder).","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["Page Builder"],"summary":"Save page draft (autosave).","operationId":"putApiV1PageBuilderPagesId","description":"Saves the page draft. Write-scoped. Gated per-clinic (v1_page_builder).","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"draftContent":{"type":"object"},"isHomepage":{"type":"boolean"},"seoTitle":{"type":"string"},"seoDescription":{"type":"string"},"seoOgImage":{"type":"string"},"seoCanonical":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Slug already in use for this clinic."}}},"delete":{"tags":["Page Builder"],"summary":"Soft-delete a page.","operationId":"deleteApiV1PageBuilderPagesId","description":"Soft-deletes a page owned by the key's clinic. Write-scoped. Gated per-clinic (v1_page_builder).","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/page-builder/pages/{id}/publish":{"post":{"tags":["Page Builder"],"summary":"Publish a page (promote draft to published).","operationId":"postApiV1PageBuilderPagesIdPublish","description":"Atomically promotes the draft to published and snapshots a new version. Write-scoped. Gated per-clinic (v1_page_builder).","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/page-builder/navigation":{"get":{"tags":["Page Builder"],"summary":"Get the clinic's header/footer menus.","operationId":"getApiV1PageBuilderNavigation","description":"Returns the clinic's navigation menus (empty shape if none). Gated per-clinic (v1_page_builder).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"put":{"tags":["Page Builder"],"summary":"Upsert the clinic's navigation menus.","operationId":"putApiV1PageBuilderNavigation","description":"Upserts the clinic's header/footer menus. Write-scoped. Gated per-clinic (v1_page_builder).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"headerMenu":{"type":"array","items":{"type":"object"}},"footerMenu":{"type":"array","items":{"type":"object"}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/onboarding/status":{"get":{"tags":["Onboarding"],"summary":"Onboarding status for the key's clinic.","operationId":"getApiV1OnboardingStatus","description":"Full onboarding status for the clinic's brand owner. Gated per-clinic (v1_onboarding).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/onboarding/request-name-change":{"post":{"tags":["Onboarding"],"summary":"One-time brand-owner name change.","operationId":"postApiV1OnboardingRequestNameChange","description":"One-time name change before identity verification. Write-scoped. Gated per-clinic (v1_onboarding).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["firstName","lastName"],"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/onboarding/confirm-signature-declaration":{"post":{"tags":["Onboarding"],"summary":"Confirm the electronic-signature declaration.","operationId":"postApiV1OnboardingConfirmSignatureDeclaration","description":"Records the brand owner's typed-name signature declaration and advances onboarding. Write-scoped. Gated per-clinic (v1_onboarding).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["typedName"],"properties":{"typedName":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/onboarding/save-business-details":{"post":{"tags":["Onboarding"],"summary":"Save brand business details.","operationId":"postApiV1OnboardingSaveBusinessDetails","description":"Saves the brand owner's business details (EIN, address, entity type, legal name). Write-scoped. Gated per-clinic (v1_onboarding).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ein":{"type":"string"},"stateOfRegistration":{"type":"string"},"address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zipCode":{"type":"string"},"phoneNumber":{"type":"string"},"businessType":{"type":"string"},"companyName":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/billing/validate-coupon":{"get":{"tags":["Billing"],"summary":"Validate a subscription coupon code.","operationId":"getApiV1BillingValidateCoupon","description":"Look up an active coupon by code. Gated per-clinic (v1_billing).","security":[{"ApiKeyAuth":[]}],"parameters":[{"in":"query","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/billing/plans":{"get":{"tags":["Billing"],"summary":"List active brand subscription plans.","operationId":"getApiV1BillingPlans","description":"Public plan catalogue (invite-only plans hidden). Gated per-clinic (v1_billing).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"plans":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/billing/current":{"get":{"tags":["Billing"],"summary":"Current subscription (stub, always null).","operationId":"getApiV1BillingCurrent","description":"Returns success with subscription null. Gated per-clinic (v1_billing).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"subscription":{"nullable":true,"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/billing/basic-info":{"get":{"tags":["Billing"],"summary":"Basic subscription info for the key's clinic.","operationId":"getApiV1BillingBasicInfo","description":"Status/tutorial/onboarding summary for the clinic's brand owner. Gated per-clinic (v1_billing).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/billing/preview-upgrade":{"post":{"tags":["Billing"],"summary":"Preview proration for a plan change.","operationId":"postApiV1BillingPreviewUpgrade","description":"Computes Stripe proration credit/charge for a plan change. Read-only (writes nothing). Gated per-clinic (v1_billing).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["newPlanId"],"properties":{"newPlanId":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Subscription expired, sync required."}}}},"/api/v1/billing/cancel":{"post":{"tags":["Billing"],"summary":"Cancel the clinic's active subscription.","operationId":"postApiV1BillingCancel","description":"Cancels the Stripe subscription and deactivates the clinic. Write-scoped. Gated per-clinic (v1_billing).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/billing/change":{"post":{"tags":["Billing"],"summary":"Change the clinic's subscription plan.","operationId":"postApiV1BillingChange","description":"Upgrades/downgrades via Stripe proration or schedule update. Write-scoped. Gated per-clinic (v1_billing).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["newPlanId"],"properties":{"newPlanId":{"type":"string"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/auth/signin":{"servers":[{"url":"https://api-dev.fusehealth.com","description":"Development (root — no /api/v1 prefix)"},{"url":"https://api.fusehealth.com","description":"Production (root — no /api/v1 prefix)"}],"post":{"tags":["Auth & Key Management"],"summary":"Obtain a brand-admin JWT (to manage keys).","operationId":"postAuthSignin","description":"Obtain a brand-admin JWT (to manage keys).","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"password":{"type":"string"}}},"example":{"email":"you@brand.com","password":"..."}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api-keys":{"servers":[{"url":"https://api-dev.fusehealth.com","description":"Development (root — no /api/v1 prefix)"},{"url":"https://api.fusehealth.com","description":"Production (root — no /api/v1 prefix)"}],"post":{"tags":["Auth & Key Management"],"summary":"Issue a key. Default scope read-only + 1yr expiry; pass scopes:[\"write\"] for full. Raw key returned once.","operationId":"postApikeys","description":"Issue a key. Default scope read-only + 1yr expiry; pass scopes:[\"write\"] for full. Raw key returned once.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["secret","publishable"],"default":"secret","description":"\"secret\" (default) — server-side management key, governed by scopes. \"publishable\" — fuse_pk_… key for the browser; may call ONLY POST /api/v1/checkout/sessions (everything else answers 403 KEY_KIND_NOT_ALLOWED). scopes are ignored for a publishable key and forced to read+write so that one route passes requireWrite.\n"},"scopes":{"type":"array","items":{"type":"string","enum":["read","write"]}},"expiresAt":{"type":["string","null"],"format":"date-time","description":"Omit for the 1-year default; null opts out of expiry; a past date is 400."}}},"example":{"name":"My integration","kind":"secret","scopes":["read"]}}}},"responses":{"201":{"description":"Success — data.apiKey is the raw key, returned exactly once; data.kind echoes the key type.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"get":{"tags":["Auth & Key Management"],"summary":"List this clinic's keys (metadata only — no secret).","operationId":"getApikeys","description":"List this clinic's keys (metadata only — no secret).","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api-keys/{id}":{"servers":[{"url":"https://api-dev.fusehealth.com","description":"Development (root — no /api/v1 prefix)"},{"url":"https://api.fusehealth.com","description":"Production (root — no /api/v1 prefix)"}],"delete":{"tags":["Auth & Key Management"],"summary":"Revoke a key (immediate).","operationId":"deleteApikeysById","description":"Revoke a key (immediate).","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/me":{"get":{"tags":["Auth & Key Management"],"summary":"Identify the key: clinic, name, scopes. Smoke-test connectivity.","operationId":"getApiV1Me","description":"Identify the key: clinic, name, scopes. Smoke-test connectivity.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/orders":{"get":{"tags":["Orders"],"summary":"Paginated orders. Each row includes the per-order feeBreakdown.","operationId":"getApiV1Orders","description":"Paginated orders. Each row includes the per-order feeBreakdown.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"example":"1"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25},"example":"25"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/orders/stats":{"get":{"tags":["Orders"],"summary":"Aggregate order + earnings stats.","operationId":"getApiV1OrdersStats","description":"Aggregate order + earnings stats.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"startDate","in":"query","required":false,"schema":{"type":"string"},"example":"2026-01-01"},{"name":"endDate","in":"query","required":false,"schema":{"type":"string"},"example":"2026-12-31"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/orders/summary":{"get":{"tags":["Orders"],"summary":"Aggregate order breakdowns — by status, program, shipping state, and refunds (no per-order rows).","operationId":"getApiV1OrdersSummary","description":"Counts and sums only (KAN-2107): orders by status, orders and paid sales by program, orders by shipping state, and refund requests by status with the approved total. Never returns an order id, order number, date, patient or medication. A shipping state with fewer than 5 orders is never named; all such states are reported together in `otherStates`. Safe for the AI connector.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"startDate","in":"query","required":false,"schema":{"type":"string"},"example":"2026-01-01"},{"name":"endDate","in":"query","required":false,"schema":{"type":"string"},"example":"2026-12-31"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"window":{"type":"object","properties":{"startDate":{"type":"string","nullable":true},"endDate":{"type":"string","nullable":true}}},"totalOrders":{"type":"integer"},"byStatus":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"orders":{"type":"integer"}}}},"byProgram":{"type":"array","items":{"type":"object","properties":{"programId":{"type":"string","nullable":true},"programName":{"type":"string","nullable":true},"orders":{"type":"integer"},"paidSales":{"type":"number"}}}},"byState":{"type":"array","description":"Only states with 5 or more orders.","items":{"type":"object","properties":{"state":{"type":"string"},"orders":{"type":"integer"}}}},"otherStates":{"type":"object","nullable":true,"description":"States with fewer than 5 orders, unnamed — how many, and their orders together.","properties":{"states":{"type":"integer"},"orders":{"type":"integer"}}},"refunds":{"type":"object","properties":{"byStatus":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"requests":{"type":"integer"}}}},"approvedAmount":{"type":"number"}}}}}}}}}},"400":{"description":"Invalid startDate or endDate"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/orders/{id}":{"get":{"tags":["Orders"],"summary":"Order detail with the full fee waterfall (matches the brand-admin UI).","operationId":"getApiV1OrdersById","description":"Order detail with the full fee waterfall (matches the brand-admin UI).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/OrderBrandView"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/orders/{id}/events":{"get":{"tags":["Orders"],"summary":"Chronological status/event timeline for one order.","operationId":"getApiV1OrdersByIdEvents","description":"Chronological status/event timeline for one order.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"eventType":{"type":"string"},"actorType":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"metadata":{"type":"object"}}}},"hasPrescriptionPdf":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/orders/{id}/lab-status":{"get":{"tags":["Orders"],"summary":"Lab lifecycle state and lab-kit tracking for one order.","operationId":"getApiV1OrdersByIdLabStatus","description":"Lab lifecycle STATE for one of the key clinic's orders: the current stage, a stage-by-stage timeline with timestamps, and the lab-kit shipment carrier/tracking numbers for both legs (FUSE to patient, patient to lab).\n\nThis endpoint deliberately exposes NO lab result content — no analyte values, reference ranges, interpretations, result documents, requisition PDFs, or results-review booking links. `resultsAvailableAt` is a timestamp only: it tells you the lab has reported, not what it reported.\n\nRequires the `v1_fulfillment` endpoint group to be enabled for your clinic (contact FUSE). Returns 404 for an unknown, malformed, or another clinic's order id.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Order id (UUID). Must belong to the API key's clinic.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"isLabGated":{"type":"boolean","description":"Whether this order uses the lab-gated split-payment flow."},"orderStatus":{"type":"string","nullable":true,"description":"The order's overall status. Lab-related values include `awaiting_lab_results`, `awaiting_renewal_lab`, `authorization_failed`, `authorized_awaiting_review`."},"stage":{"type":"string","nullable":true,"description":"Current lab lifecycle stage; `null` when the order has no lab leg yet.","enum":["requisition_created","shipped_to_patient","delivered_to_patient","shipped_to_lab","received_by_lab","results"]},"timeline":{"type":"array","description":"All six stages in lifecycle order. `reached` is true for the current stage and every stage before it. `occurredAt` is null for unreached stages and for the two shipment stages, which carry carrier/tracking but no dedicated timestamp.","items":{"type":"object","properties":{"stage":{"type":"string","enum":["requisition_created","shipped_to_patient","delivered_to_patient","shipped_to_lab","received_by_lab","results"]},"reached":{"type":"boolean"},"occurredAt":{"type":"string","format":"date-time","nullable":true}}}},"kitShipmentToPatient":{"type":"object","description":"Outbound leg — lab kit shipped to the patient.","properties":{"carrier":{"type":"string","nullable":true},"trackingNumber":{"type":"string","nullable":true},"deliveredAt":{"type":"string","format":"date-time","nullable":true}}},"kitShipmentToLab":{"type":"object","description":"Return leg — patient's sample shipped to the lab.","properties":{"carrier":{"type":"string","nullable":true},"trackingNumber":{"type":"string","nullable":true},"receivedAt":{"type":"string","format":"date-time","nullable":true}}},"resultsAvailableAt":{"type":"string","format":"date-time","nullable":true,"description":"When the lab reported results. TIMESTAMP ONLY — the result content itself is never exposed on this API."}}}}},"example":{"success":true,"data":{"orderId":"8f14e45f-ceea-467a-9b2b-1c0a1d0e2f30","isLabGated":true,"orderStatus":"awaiting_lab_results","stage":"received_by_lab","timeline":[{"stage":"requisition_created","reached":true,"occurredAt":"2026-04-01T10:00:00.000Z"},{"stage":"shipped_to_patient","reached":true,"occurredAt":null},{"stage":"delivered_to_patient","reached":true,"occurredAt":"2026-04-03T10:00:00.000Z"},{"stage":"shipped_to_lab","reached":true,"occurredAt":null},{"stage":"received_by_lab","reached":true,"occurredAt":"2026-04-07T10:00:00.000Z"},{"stage":"results","reached":false,"occurredAt":null}],"kitShipmentToPatient":{"carrier":"UPS","trackingNumber":"1Z999AA10123456784","deliveredAt":"2026-04-03T10:00:00.000Z"},"kitShipmentToLab":{"carrier":"FedEx","trackingNumber":"774899999999","receivedAt":"2026-04-07T10:00:00.000Z"},"resultsAvailableAt":null}}}}},"403":{"description":"The `v1_fulfillment` endpoint group is not enabled for your clinic"},"404":{"description":"Order not found. Returned for an unknown id, a malformed (non-UUID) id, and an id belonging to another clinic — the three are deliberately indistinguishable."}}}},"/api/v1/orders/{id}/visit-status":{"get":{"tags":["Orders"],"summary":"Telehealth visit status and appointment time for one order.","operationId":"getApiV1OrdersByIdVisitStatus","description":"Whether the patient has booked their live (synchronous) visit, has not booked yet, or did not attend — plus the appointment time when one is scheduled. This is the read side of the `appointment.scheduled` / `appointment.cancelled` webhooks: those notify you that something changed and carry ids only, and this endpoint tells you what the state now is.\n\n`visitStatus` is a FUSE-defined value, deliberately independent of any doctor network's internal naming, so it is stable across changes FUSE makes behind the scenes. Treat it as a closed set and handle an unrecognised value defensively.\n\nBefore chasing a patient to book, check `bookingRequired`. Asynchronous treatments never require a live appointment and rest permanently at `not_booked` — that is normal, not an outstanding task. `bookingRequired` is `null` when the order predates visit-type resolution (unknown, not \"no appointment needed\").\n\nThis endpoint exposes NO clinical content: no prescriber name, NPI or phone, no prescribed medications, no visit outcome, and no lab results. A referred visit is already visible via the order's own `status`.\n\nRequires the `v1_fulfillment` endpoint group to be enabled for your clinic (contact FUSE). Returns 404 for an unknown, malformed, or another clinic's order id.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Order id (UUID). Must belong to the API key's clinic.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"visitStatus":{"type":"string","description":"`not_booked` — no live appointment is confirmed. Either the patient has not booked yet, or the treatment is asynchronous in their state and never requires one (check `bookingRequired`).\n`booked` — a live visit is confirmed; see `scheduledAt`.\n`no_show` — the patient did not attend the confirmed appointment.\n`concluded` — the visit is complete (consult finished and/or prescription written); no further patient action is needed.\n`cancelled` — the visit was cancelled; FUSE cancels the order alongside it, so the order's own status reflects it too.","enum":["not_booked","booked","no_show","concluded","cancelled"]},"bookingRequired":{"type":"boolean","nullable":true,"description":"Whether this order's visit type requires a live appointment at all. `false` for asynchronous treatments. `null` when the order predates visit-type resolution — unknown, NOT \"no appointment needed\"."},"scheduledAt":{"type":"string","format":"date-time","nullable":true,"description":"The appointment time, when the doctor network supplied one. Retained after a `no_show` (it is the appointment that was missed). `null` whenever no appointment has been scheduled."},"lastSyncedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the doctor network last sent FUSE any update about this visit. Use it to tell \"no appointment has been booked\" apart from \"we have not heard anything recently\" — a stale value on an order you expect to be progressing is worth raising with FUSE."}}}}},"example":{"success":true,"data":{"orderId":"8f14e45f-ceea-467a-9b2b-1c0a1d0e2f30","visitStatus":"booked","bookingRequired":true,"scheduledAt":"2026-08-03T15:30:00.000Z","lastSyncedAt":"2026-08-01T09:00:00.000Z"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The `v1_fulfillment` endpoint group is not enabled for your clinic"},"404":{"description":"Order not found. Returned for an unknown id, a malformed (non-UUID) id, and an id belonging to another clinic — the three are deliberately indistinguishable."}}}},"/api/v1/customers":{"get":{"tags":["Customers"],"summary":"Patient directory with order count, revenue, tags.","operationId":"getApiV1Customers","description":"Patient directory with order count, revenue, tags.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"example":"1"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25},"example":"25"},{"name":"search","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/programs":{"get":{"tags":["Programs"],"summary":"List the clinic's programs.","operationId":"getApiV1Programs","description":"List the clinic's programs.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Program"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Programs"],"summary":"Create a program.","operationId":"postApiV1Programs","description":"Create a program.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}},"example":{"name":"New program"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Program"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/programs/overview":{"get":{"tags":["Programs"],"summary":"Dashboard stats + attention items.","operationId":"getApiV1ProgramsOverview","description":"Dashboard stats + attention items.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/ProgramsOverview"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/programs/copilot/suggestions":{"get":{"tags":["Programs"],"summary":"AI copilot suggestions for improving the clinic's programs.","operationId":"getApiV1ProgramsCopilotSuggestions","description":"AI copilot suggestions for improving the clinic's programs.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/programs/{id}":{"get":{"tags":["Programs"],"summary":"Program detail.","operationId":"getApiV1ProgramsById","description":"Program detail.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Program"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["Programs"],"summary":"Update a program.","operationId":"putApiV1ProgramsById","description":"Update a program.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}},"example":{"name":"Renamed"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Program"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Programs"],"summary":"Delete one of the clinic's programs.","operationId":"deleteApiV1ProgramsById","description":"Delete one of the clinic's programs.\n\nRemoves the program outright only when nothing is in flight. If work\nremains (active orders, enrollments) the program is *retired* instead:\nit stops being offered to new patients, while patients already on it\ncontinue their treatment. A retired program is removed once all of its\nin-flight work has finished; note that a patient who keeps renewing has\nno natural end, so do not build automation that assumes the program will\ndisappear on its own.\n\n**Returns 409 `WINDDOWN_CONSENT_REQUIRED` when the program still has\npatients on it (KAN-1327).** This endpoint carries no wind-down opt-in,\nso it can only retire passively — which for an enrolled program means\nthe patients are never told and their subscriptions keep billing, so it\nis refused rather than done silently.\n\n**Ending a program that still has patients is not currently available\nover this API.** The wind-down opt-in\n(`POST /programs/{id}/retire-with-winddown`) is exposed only on the\nauthenticated brand-admin portal, not on this API-key surface — a\ndeliberate limit, because it emails patients and cancels their\nsubscriptions. Use the brand admin portal for that action. Over this\nAPI, `deactivate` stops the program being offered to new patients but\ndoes not stop billing anyone already enrolled.\n","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Program"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The program still has patients on it. Ending it requires the explicit\nwind-down opt-in — see `POST /programs/{id}/retire-with-winddown`.\n","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"code":{"type":"string","example":"WINDDOWN_CONSENT_REQUIRED"},"error":{"type":"string"},"data":{"type":"object","properties":{"patients":{"type":"integer","description":"How many patients are still on the program."}}}}}}}}}}},"/api/v1/programs/{id}/global-products":{"get":{"tags":["Programs"],"summary":"Fee-adjusted product pool for a program.","operationId":"getApiV1ProgramsByIdGlobalproducts","description":"Fee-adjusted product pool for a program.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/programs/{id}/duplicate":{"post":{"tags":["Programs"],"summary":"Clone a program (deep copy of its product config).","operationId":"postApiV1ProgramsByIdDuplicate","description":"Clone a program (deep copy of its product config).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/programs/{id}/products":{"get":{"tags":["Programs"],"summary":"Effective per-product patient pricing for a program.","operationId":"getApiV1ProgramsByIdProducts","description":"The price a patient is actually shown and charged for each product in this program, after the authoritative fee resolution (clinic override -> program base fee -> tenant placeholder). Mirror `displayPrice` on your own website to stay in sync with FUSE checkout — do NOT add `nonMedicalServiceFee` to it, and do NOT multiply it by a number of months (it prices one PACK — see `packDurationMonths`). `hasResolvedPrice` means a price and a pharmacy cost resolve; it is NOT an activation gate, and no /api/v1 endpoint answers \"safe to publish\" today (see that field's description). To CHANGE a price, PUT /api/v1/programs/{id} with `productPricing[globalProductId].programFee` and re-read this endpoint.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ProgramPricingRead"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["Programs"],"summary":"Replace the program's product set.","operationId":"putApiV1ProgramsByIdProducts","description":"Replace the program's product set.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"}}}}}},"example":{"products":[{"productId":"<global-product-uuid>"}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/programs/{id}/upload-image":{"post":{"tags":["Programs"],"summary":"Upload a program cover image (multipart, field `image`).","operationId":"postApiV1ProgramsByIdUploadimage","description":"Upload a program cover image (multipart, field `image`).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","format":"binary","description":"Upload file field"}},"required":["image"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/programs/sync-all":{"post":{"tags":["Programs"],"summary":"Re-sync ALL of the clinic's template-derived programs against their source templates.","operationId":"postApiV1ProgramsSyncall","description":"Re-sync ALL of the clinic's template-derived programs against their source templates.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Program"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/programs/{id}/sync":{"post":{"tags":["Programs"],"summary":"Re-sync one derived program against its source template.","operationId":"postApiV1ProgramsByIdSync","description":"Re-sync one derived program against its source template.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"KAN-1641 — the sync would leave this program lab-gated with zero live lab options, a state checkout cannot serve. Refused rather than propagated, so the program is never left hard-refusing every buyer. `code` is `LAB_CONFIG_REQUIRED` and `message` names the missing configuration. Fix the template's lab options and retry — a bare retry cannot succeed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"code":{"type":"string","example":"LAB_CONFIG_REQUIRED"},"message":{"type":"string"}}}}}}}}},"/api/v1/programs/{id}/sync-status":{"get":{"tags":["Programs"],"summary":"Whether a derived program is behind its source template.","operationId":"getApiV1ProgramsByIdSyncstatus","description":"Whether a derived program is behind its source template.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/programs/{id}/products/activation-status":{"get":{"tags":["Programs"],"summary":"Per-product activation state within a program.","operationId":"getApiV1ProgramsByIdProductsActivationstatus","description":"Per-product activation state within a program.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/programs/{id}/products/visibility-status":{"get":{"tags":["Programs"],"summary":"Per-product patient-visibility state within a program.","operationId":"getApiV1ProgramsByIdProductsVisibilitystatus","description":"Per-product patient-visibility state within a program.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/programs/{id}/products/{productId}/activate":{"patch":{"tags":["Programs"],"summary":"Activate/deactivate a product in the program.","operationId":"patchApiV1ProgramsByIdProductsByProductIdActivate","description":"Activate/deactivate a product in the program.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"isActive":{"type":"boolean"}}},"example":{"isActive":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/programs/{id}/products/{productId}/visibility":{"patch":{"tags":["Programs"],"summary":"Toggle a product's patient visibility.","operationId":"patchApiV1ProgramsByIdProductsByProductIdVisibility","description":"Toggle a product's patient visibility.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"isPatientVisible":{"type":"boolean"}}},"example":{"isPatientVisible":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/programs/{id}/titration-protocols":{"get":{"tags":["Programs"],"summary":"Titration protocols attached to a program.","operationId":"getApiV1ProgramsByIdTitrationprotocols","description":"Titration protocols attached to a program.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["Programs"],"summary":"Attach a titration protocol to a program.","operationId":"postApiV1ProgramsByIdTitrationprotocols","description":"Attach a titration protocol to a program.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"titrationProtocolId":{"type":"string"},"flatFee":{"type":"integer"},"allowedBillingMonths":{"type":"array","items":{"type":"integer"}},"position":{"type":"integer"}}},"example":{"titrationProtocolId":"<protocol-uuid>","flatFee":0,"allowedBillingMonths":[1,3],"position":0}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/programs/{id}/titration-protocols/{attachmentId}":{"put":{"tags":["Programs"],"summary":"Update a program's titration-protocol attachment.","operationId":"putApiV1ProgramsByIdTitrationprotocolsByAttachmentId","description":"Update a program's titration-protocol attachment.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"attachmentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"flatFee":{"type":"integer"},"allowedBillingMonths":{"type":"array","items":{"type":"integer"}},"position":{"type":"integer"}}},"example":{"flatFee":25,"allowedBillingMonths":[1,3,6],"position":1}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Programs"],"summary":"Detach a titration protocol from a program.","operationId":"deleteApiV1ProgramsByIdTitrationprotocolsByAttachmentId","description":"Detach a titration protocol from a program.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"attachmentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/titration-schedule/fulfillment-held":{"get":{"tags":["Program Templates & Titration"],"summary":"List titration schedules held for fulfillment (awaiting revisit).","operationId":"getApiV1TitrationscheduleFulfillmentheld","description":"\nLists this clinic's titration schedules currently held for fulfillment (reason `awaiting_revisit`, status active/maintenance), clinic-scoped by the API key. PHI: response includes patient first/last name only (email omitted). Read-only (read scope).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"currentLevel":{"type":"integer"},"maxLevel":{"type":"integer"},"status":{"type":"string"},"nextRevisitDueAt":{"type":"string","format":"date-time","nullable":true},"lastRevisitAt":{"type":"string","format":"date-time","nullable":true},"heldSince":{"type":"string","format":"date-time"},"daysOverdue":{"type":"integer","nullable":true},"order":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"orderNumber":{"type":"string"},"status":{"type":"string"}}},"user":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"}}},"program":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"titrationProtocol":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"maxLevel":{"type":"integer"}}}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/program-templates":{"get":{"tags":["Program Templates & Titration"],"summary":"List the shared FUSE program templates.","operationId":"getApiV1Programtemplates","description":"List the shared FUSE program templates.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/program-templates/{id}":{"get":{"tags":["Program Templates & Titration"],"summary":"One program template.","operationId":"getApiV1ProgramtemplatesById","description":"One program template.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/program-templates/{id}/global-products":{"get":{"tags":["Program Templates & Titration"],"summary":"Global products carried by a program template.","operationId":"getApiV1ProgramtemplatesByIdGlobalproducts","description":"Global products carried by a program template.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/titration-protocols":{"get":{"tags":["Program Templates & Titration"],"summary":"List the shared FUSE titration protocols.","operationId":"getApiV1Titrationprotocols","description":"List the shared FUSE titration protocols.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/catalog":{"get":{"tags":["Products & Catalog"],"summary":"Storefront catalog (light view) — same source as the brand portal.","operationId":"getApiV1Catalog","description":"Storefront catalog (light view) — same source as the brand portal.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":200},"example":"200"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0},"example":"0"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProduct"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/products":{"get":{"tags":["Products & Catalog"],"summary":"Product management view (clinic's own + shared platform products).","operationId":"getApiV1Products","description":"Product management view (clinic's own + shared platform products).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"example":"1"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50},"example":"50"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Products & Catalog"],"summary":"Create a custom product for the key clinic's brand.","operationId":"postApiV1Products","description":"Creates a legacy Product owned by the key clinic's brand (brandId-scoped). No Stripe side-effect. Write-scoped. Gated per-clinic (v1_products_writes).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","pharmacyPrice","pharmacyProductId"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"pharmacyPrice":{"type":"number"},"pharmacyProductId":{"type":"string"},"isActive":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/products/{id}":{"get":{"tags":["Products & Catalog"],"summary":"One product (accepts a Product id or a GlobalProduct id).","operationId":"getApiV1ProductsById","description":"One product (accepts a Product id or a GlobalProduct id).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Product"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["Products & Catalog"],"summary":"Update one of the clinic's OWN products.","operationId":"putApiV1ProductsById","description":"Update one of the clinic's OWN products.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string"}}},"example":{"description":"Updated copy"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Product"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/brand/product-catalog":{"get":{"tags":["Products & Catalog"],"summary":"Alias of /catalog — the brand's fee-adjusted product catalog.","operationId":"getApiV1BrandProductcatalog","description":"Alias of /catalog — the brand's fee-adjusted product catalog.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProduct"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/products-management/{id}":{"get":{"tags":["Products & Catalog"],"summary":"Alias of GET /products/:id — read one of the clinic's own products.","operationId":"getApiV1ProductsmanagementById","description":"Alias of GET /products/:id. Accepts either a Product id or a GlobalProduct id (resolved to the primary pharmacy's Product, matching the admin editor). Ownership-gated: a product owned by another brand returns 404. No patient PHI. Read scope.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["Products & Catalog"],"summary":"Alias of PUT /products/:id — update one of the clinic's own products.","operationId":"putApiV1ProductsmanagementById","description":"Alias of PUT /products/:id — update one of the clinic's own products.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string"}}},"example":{"description":"Updated copy"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Product"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/tenant-products":{"get":{"tags":["Products & Catalog"],"summary":"The clinic's own tenant-product offerings + facilitation fees.","operationId":"getApiV1Tenantproducts","description":"The clinic's own tenant-product offerings + facilitation fees.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/global-products/discontinued-in-use":{"get":{"tags":["Products & Catalog"],"summary":"Discontinued global SKUs still referenced by THIS clinic's programs.","operationId":"getApiV1GlobalproductsDiscontinuedinuse","description":"Discontinued global SKUs still referenced by THIS clinic's programs.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/tenant-products/update":{"post":{"tags":["Products & Catalog"],"summary":"Set the price of one tenant product (creates a real Stripe price).","operationId":"postApiV1TenantproductsUpdate","description":"Set the price of one tenant product (creates a real Stripe price).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tenantProductId":{"type":"string"},"price":{"type":"integer"}}},"example":{"tenantProductId":"<tenant-product-uuid>","price":99}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/tenant-products/update-selection":{"post":{"tags":["Products & Catalog"],"summary":"Update the clinic's selected tenant products (enforces plan limits + billing caps).","operationId":"postApiV1TenantproductsUpdateselection","description":"Update the clinic's selected tenant products (enforces plan limits + billing caps).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string"},"questionnaireId":{"type":"string"}}}}}},"example":{"products":[{"productId":"<product-uuid>","questionnaireId":"<questionnaire-uuid>"}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/global-products/{id}/upload-image":{"post":{"tags":["Products & Catalog"],"summary":"Upload a brand-scoped image override for a global product (multipart, field `image`; never mutates the shared product).","operationId":"postApiV1GlobalproductsByIdUploadimage","description":"Upload a brand-scoped image override for a global product (multipart, field `image`; never mutates the shared product).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","format":"binary","description":"Upload file field"}},"required":["image"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/global-form-structures":{"get":{"tags":["Products & Catalog"],"summary":"Shared FUSE global form-builder structure catalog (no clinic data / no PHI).","operationId":"getApiV1Globalformstructures","description":"Shared FUSE global form-builder structure catalog (no clinic data / no PHI).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/payouts":{"get":{"tags":["Payouts & Refunds"],"summary":"Order-level payout history.","operationId":"getApiV1Payouts","description":"Order-level payout history.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"example":"1"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50},"example":"50"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PayoutItem"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/payouts/balance":{"get":{"tags":["Payouts & Refunds"],"summary":"Balance, reserve, held, Stripe — the portal's exact numbers.","operationId":"getApiV1PayoutsBalance","description":"Balance, reserve, held, Stripe — the portal's exact numbers.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/BrandBalance"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/payouts/disputes":{"get":{"tags":["Payouts & Refunds"],"summary":"Dispute summary + history.","operationId":"getApiV1PayoutsDisputes","description":"Dispute summary + history.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"windowDays","in":"query","required":false,"schema":{"type":"integer","default":90},"example":"90"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/payouts/withdraw":{"post":{"tags":["Payouts & Refunds"],"summary":"Withdraw available balance to the connected Stripe account.","operationId":"postApiV1PayoutsWithdraw","description":"Withdraw available balance to the connected Stripe account.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer"}}},"example":{"amount":100}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/refunds":{"post":{"tags":["Payouts & Refunds"],"summary":"Full refund on one of the clinic's own orders (30-day + balance guard).","operationId":"postApiV1Refunds","description":"Full refund on one of the clinic's own orders (30-day + balance guard).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string"},"reason":{"type":"string"}}},"example":{"orderId":"<order-uuid>","reason":"customer request"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/refund-requests":{"get":{"tags":["Refund Requests"],"summary":"List incoming patient refund requests for the clinic.","operationId":"getApiV1Refundrequests","description":"List incoming patient refund requests for the clinic.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"example":"1"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25},"example":"25"},{"name":"status","in":"query","required":false,"schema":{"type":"string"},"example":"pending"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/refund-requests/{id}/{action}":{"post":{"tags":["Refund Requests"],"summary":"Approve or deny a refund request (:action = approve|deny). Approve issues the refund.","operationId":"postApiV1RefundrequestsByIdByAction","description":"Approve or deny a refund request (:action = approve|deny). Approve issues the refund.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"action","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reviewNotes":{"type":"string"}}},"example":{"reviewNotes":"Approved per policy"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/treatments":{"get":{"tags":["Treatments"],"summary":"Clinic treatments.","operationId":"getApiV1Treatments","description":"Clinic treatments.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Treatment"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Treatments"],"summary":"Create a treatment.","operationId":"postApiV1Treatments","description":"Create a treatment.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}}},"example":{"name":"New treatment","description":"..."}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Treatment"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/treatments/{id}":{"get":{"tags":["Treatments"],"summary":"One treatment (clinic-scoped by id + clinicId).","operationId":"getApiV1TreatmentsById","description":"One treatment (clinic-scoped by id + clinicId).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Treatment"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["Treatments"],"summary":"Update one of the clinic's own treatments.","operationId":"putApiV1TreatmentsById","description":"Update one of the clinic's own treatments.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}},"example":{"name":"Renamed treatment"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Treatment"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/brand-treatments":{"get":{"tags":["Treatments"],"summary":"Global treatments joined with this brand's selections.","operationId":"getApiV1Brandtreatments","description":"Global treatments joined with this brand's selections.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/BrandTreatment"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Treatments"],"summary":"Select a global treatment for the brand.","operationId":"postApiV1Brandtreatments","description":"Select a global treatment for the brand.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"treatmentId":{"type":"string"}}},"example":{"treatmentId":"<treatment-uuid>"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/BrandTreatment"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"delete":{"tags":["Treatments"],"summary":"Deselect a global treatment for the brand.","operationId":"deleteApiV1Brandtreatments","description":"Deselect a global treatment for the brand.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"treatmentId":{"type":"string"}}},"example":{"treatmentId":"<treatment-uuid>"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/BrandTreatment"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/treatment/{id}/upload-logo":{"post":{"tags":["Treatments"],"summary":"Upload/remove a treatment logo (multipart, field `logo`; send removeLogo=true to clear).","operationId":"postApiV1TreatmentByIdUploadlogo","description":"Upload/remove a treatment logo (multipart, field `logo`; send removeLogo=true to clear).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"logo":{"type":"string","format":"binary","description":"Upload file field"}},"required":["logo"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/dashboard/overview":{"get":{"tags":["Dashboard & Analytics"],"summary":"Top-line dashboard summary.","operationId":"getApiV1DashboardOverview","description":"Top-line dashboard summary.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/dashboard/metrics":{"get":{"tags":["Dashboard & Analytics"],"summary":"Key metric tiles (orders, revenue, patients).","operationId":"getApiV1DashboardMetrics","description":"Key metric tiles (orders, revenue, patients).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"startDate","in":"query","required":false,"schema":{"type":"string"},"example":"2026-01-01"},{"name":"endDate","in":"query","required":false,"schema":{"type":"string"},"example":"2026-12-31"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/dashboard/earnings-report":{"get":{"tags":["Dashboard & Analytics"],"summary":"Earnings breakdown report.","operationId":"getApiV1DashboardEarningsreport","description":"Earnings breakdown report.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/dashboard/recent-activity":{"get":{"tags":["Dashboard & Analytics"],"summary":"Recent clinic activity feed (PHI-scrubbed).","operationId":"getApiV1DashboardRecentactivity","description":"Recent clinic activity feed (PHI-scrubbed).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/dashboard/revenue-chart":{"get":{"tags":["Dashboard & Analytics"],"summary":"Time-series revenue chart data.","operationId":"getApiV1DashboardRevenuechart","description":"Time-series revenue chart data.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string"},"example":"30d"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/dashboard/projected-revenue":{"get":{"tags":["Dashboard & Analytics"],"summary":"Projected revenue from active subscriptions.","operationId":"getApiV1DashboardProjectedrevenue","description":"Projected revenue from active subscriptions.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/analytics/forms":{"get":{"tags":["Dashboard & Analytics"],"summary":"The clinic's own intake-form metrics (no PHI).","operationId":"getApiV1AnalyticsForms","description":"The clinic's own intake-form metrics (no PHI).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/likes/admin/analytics/{tenantProductId}":{"get":{"tags":["Dashboard & Analytics"],"summary":"Like/engagement analytics for one of the clinic's tenant products.","operationId":"getApiV1LikesAdminAnalyticsByTenantProductId","description":"Like/engagement analytics for one of the clinic's tenant products.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"tenantProductId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/likes/admin/counts":{"post":{"tags":["Dashboard & Analytics"],"summary":"Bulk like counts for a list of tenant products (POST only because ids travel in the body; mutates nothing).","operationId":"postApiV1LikesAdminCounts","description":"Bulk like counts for a list of tenant products (POST only because ids travel in the body; mutates nothing).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tenantProductIds":{"type":"array","items":{"type":"string"}}}},"example":{"tenantProductIds":["<tenant-product-uuid>"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/contacts":{"get":{"tags":["CRM · Contacts"],"summary":"List contacts (patients).","operationId":"getApiV1Contacts","description":"List contacts (patients).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50},"example":"50"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0},"example":"0"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["CRM · Contacts"],"summary":"Create a contact (provisions a patient + welcome email).","operationId":"postApiV1Contacts","description":"Create a contact (provisions a patient + welcome email).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"}}},"example":{"firstName":"Jane","lastName":"Doe","email":"jane@example.com"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Contact"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/contacts/{id}":{"put":{"tags":["CRM · Contacts"],"summary":"Update a contact.","operationId":"putApiV1ContactsById","description":"Update a contact.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string"}}},"example":{"firstName":"Jane"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Contact"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/contacts/import":{"post":{"tags":["CRM · Contacts"],"summary":"Bulk CSV import (multipart, field `csv`, 5 MB). Headers: firstname,lastname,email[,phonenumber]. Patient emails are redacted from error rows.","operationId":"postApiV1ContactsImport","description":"Bulk CSV import (multipart, field `csv`, 5 MB). Headers: firstname,lastname,email[,phonenumber]. Patient emails are redacted from error rows.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"csv":{"type":"string","format":"binary","description":"Upload file field"}},"required":["csv"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Contact"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/tags":{"get":{"tags":["CRM · Tags"],"summary":"List tags (category/isActive filters).","operationId":"getApiV1Tags","description":"List tags (category/isActive filters).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"isActive","in":"query","required":false,"schema":{"type":"string"},"example":"true"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["CRM · Tags"],"summary":"Create a tag.","operationId":"postApiV1Tags","description":"Create a tag.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"}}},"example":{"name":"VIP","color":"#3B82F6"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Tag"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/tags/{id}":{"put":{"tags":["CRM · Tags"],"summary":"Update a tag.","operationId":"putApiV1TagsById","description":"Update a tag.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"color":{"type":"string"}}},"example":{"color":"#123456"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Tag"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["CRM · Tags"],"summary":"Delete a tag (cascades assignments).","operationId":"deleteApiV1TagsById","description":"Delete a tag (cascades assignments).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Tag"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/tags/{id}/assign":{"post":{"tags":["CRM · Tags"],"summary":"Assign a tag to a patient.","operationId":"postApiV1TagsByIdAssign","description":"Assign a tag to a patient.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string"}}},"example":{"userId":"<patient-uuid>"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/tags/{id}/assign/{userId}":{"delete":{"tags":["CRM · Tags"],"summary":"Unassign a tag.","operationId":"deleteApiV1TagsByIdAssignByUserId","description":"Unassign a tag.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/sequences":{"get":{"tags":["CRM · Sequences"],"summary":"List sequences.","operationId":"getApiV1Sequences","description":"List sequences.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Sequence"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["CRM · Sequences"],"summary":"Create a sequence (draft). Key-created rows store createdBy=null (audited).","operationId":"postApiV1Sequences","description":"Create a sequence (draft). Key-created rows store createdBy=null (audited).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"triggerEvent":{"type":"string"}}},"example":{"name":"Welcome series","triggerEvent":"manual"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Sequence"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/sequences/{id}":{"get":{"tags":["CRM · Sequences"],"summary":"Sequence detail + analytics.","operationId":"getApiV1SequencesById","description":"Sequence detail + analytics.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Sequence"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["CRM · Sequences"],"summary":"Update a sequence.","operationId":"putApiV1SequencesById","description":"Update a sequence.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}},"example":{"name":"Renamed"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Sequence"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/sequences/{id}/steps":{"put":{"tags":["CRM · Sequences"],"summary":"Replace a sequence's steps.","operationId":"putApiV1SequencesByIdSteps","description":"Replace a sequence's steps.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"steps":{"type":"array","items":{}}}},"example":{"steps":[]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/sequence-triggers/manual":{"post":{"tags":["CRM · Sequences"],"summary":"Manually trigger an active sequence for a user or a tag (provide exactly one).","operationId":"postApiV1SequencetriggersManual","description":"Manually trigger an active sequence for a user or a tag (provide exactly one).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sequenceId":{"type":"string"},"userId":{"type":"string"}}},"example":{"sequenceId":"<seq-uuid>","userId":"<patient-uuid>"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/message-templates":{"get":{"tags":["CRM · Templates"],"summary":"List message templates.","operationId":"getApiV1Messagetemplates","description":"List message templates.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/MessageTemplate"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["CRM · Templates"],"summary":"Create a template. Key-created rows store createdBy=null (audited).","operationId":"postApiV1Messagetemplates","description":"Create a template. Key-created rows store createdBy=null (audited).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"}}},"example":{"name":"Welcome email","type":"email","subject":"Welcome","body":"Hi {{firstName}}"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/MessageTemplate"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/message-templates/{id}":{"put":{"tags":["CRM · Templates"],"summary":"Update a template.","operationId":"putApiV1MessagetemplatesById","description":"Update a template.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"}}},"example":{"body":"Hi {{firstName}}"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/MessageTemplate"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["CRM · Templates"],"summary":"Delete a template (soft).","operationId":"deleteApiV1MessagetemplatesById","description":"Delete a template (soft).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/MessageTemplate"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/message-templates/upload-image":{"post":{"tags":["CRM · Templates"],"summary":"Upload an image for use in a template (multipart, field `image`).","operationId":"postApiV1MessagetemplatesUploadimage","description":"Upload an image for use in a template (multipart, field `image`).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","format":"binary","description":"Upload file field"}},"required":["image"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/MessageTemplate"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/message-templates/{id}/duplicate":{"post":{"tags":["CRM · Templates"],"summary":"Duplicate a message template.","operationId":"postApiV1MessagetemplatesByIdDuplicate","description":"Duplicate a message template.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/crm/connection":{"get":{"tags":["CRM · Connection"],"summary":"CRM connection status (safe projection — no secret).","operationId":"getApiV1CrmConnection","description":"CRM connection status (safe projection — no secret).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"delete":{"tags":["CRM · Connection"],"summary":"Disconnect the brand's CRM.","operationId":"deleteApiV1CrmConnection","description":"Disconnect the brand's CRM.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/crm/connect/apikey":{"post":{"tags":["CRM · Connection"],"summary":"Connect a CRM via GHL API key.","operationId":"postApiV1CrmConnectApikey","description":"Connect a CRM via GHL API key.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"apiKey":{"type":"string"}}},"example":{"provider":"gohighlevel","apiKey":"<ghl-api-key>"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/crm/connect/oauth/start":{"get":{"tags":["CRM · Connection"],"summary":"Build the GHL OAuth authorize URL (signed state; no mutation).","operationId":"getApiV1CrmConnectOauthStart","description":"Build the GHL OAuth authorize URL (signed state; no mutation).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/affiliate-program":{"get":{"tags":["Affiliate Program"],"summary":"Affiliate program config for the clinic.","operationId":"getApiV1Affiliateprogram","description":"Affiliate program config for the clinic.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"put":{"tags":["Affiliate Program"],"summary":"Update affiliate program config (rates, cookie window, payout thresholds).","operationId":"putApiV1Affiliateprogram","description":"Update affiliate program config (rates, cookie window, payout thresholds).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"affiliateProgramEnabled":{"type":"boolean"},"affiliateCommissionMode":{"type":"string"},"affiliateFirstOrderRate":{"type":"integer"},"affiliateDefaultRate":{"type":"integer"},"affiliateCommissionDurationMonths":{"type":"integer"},"affiliateCookieWindowDays":{"type":"integer"},"affiliateMinimumPayoutThreshold":{"type":"integer"},"affiliatePayoutFrequency":{"type":"string"},"affiliateMaxCount":{"type":"integer"}}},"example":{"affiliateProgramEnabled":true,"affiliateCommissionMode":"percentage","affiliateFirstOrderRate":20,"affiliateDefaultRate":10,"affiliateCommissionDurationMonths":12,"affiliateCookieWindowDays":30,"affiliateMinimumPayoutThreshold":50,"affiliatePayoutFrequency":"monthly","affiliateMaxCount":100}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/affiliate-program/margin-estimate":{"get":{"tags":["Affiliate Program"],"summary":"Estimated margin impact of the current commission config.","operationId":"getApiV1AffiliateprogramMarginestimate","description":"Estimated margin impact of the current commission config.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/affiliate-program/affiliates":{"get":{"tags":["Affiliate Program"],"summary":"List the clinic's affiliates.","operationId":"getApiV1AffiliateprogramAffiliates","description":"List the clinic's affiliates.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/affiliate-program/affiliates/{membershipId}":{"patch":{"tags":["Affiliate Program"],"summary":"Update per-affiliate rate overrides / payout details.","operationId":"patchApiV1AffiliateprogramAffiliatesByMembershipId","description":"Update per-affiliate rate overrides / payout details.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"membershipId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstOrderRate":{"type":"integer"},"commissionRate":{"type":"integer"},"payoutContactMethod":{"type":"string"},"payoutNotes":{"type":"string"}}},"example":{"firstOrderRate":25,"commissionRate":12,"payoutContactMethod":"email","payoutNotes":"..."}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/affiliate-program/payouts":{"get":{"tags":["Affiliate Program"],"summary":"List affiliate payouts.","operationId":"getApiV1AffiliateprogramPayouts","description":"List affiliate payouts.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/affiliate-program/payouts/generate":{"post":{"tags":["Affiliate Program"],"summary":"Generate the next payout batch from accrued commissions.","operationId":"postApiV1AffiliateprogramPayoutsGenerate","description":"Generate the next payout batch from accrued commissions.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/affiliate-program/payouts/{id}/commissions":{"get":{"tags":["Affiliate Program"],"summary":"Commissions included in a payout.","operationId":"getApiV1AffiliateprogramPayoutsByIdCommissions","description":"Commissions included in a payout.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/affiliate-program/payouts/{id}/approve":{"post":{"tags":["Affiliate Program"],"summary":"Approve a pending payout.","operationId":"postApiV1AffiliateprogramPayoutsByIdApprove","description":"Approve a pending payout.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/affiliate-program/payouts/{id}/mark-paid":{"post":{"tags":["Affiliate Program"],"summary":"Mark a payout as paid (records payout metadata).","operationId":"postApiV1AffiliateprogramPayoutsByIdMarkpaid","description":"Mark a payout as paid (records payout metadata).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string"}}},"example":{"notes":"Paid via ACH"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/affiliate-program/payouts/{payoutId}/exclude-commissions":{"post":{"tags":["Affiliate Program"],"summary":"Exclude specific commissions from a payout.","operationId":"postApiV1AffiliateprogramPayoutsByPayoutIdExcludecommissions","description":"Exclude specific commissions from a payout.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"payoutId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"commissionIds":{"type":"array","items":{"type":"string"}}}},"example":{"commissionIds":["<commission-uuid>"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/affiliate-program/tax-documents":{"get":{"tags":["Affiliate Program"],"summary":"List affiliate W-9 / tax documents for review.","operationId":"getApiV1AffiliateprogramTaxdocuments","description":"List affiliate W-9 / tax documents for review.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/affiliate-program/tax-documents/{docId}/verify":{"post":{"tags":["Affiliate Program"],"summary":"Mark a tax document verified.","operationId":"postApiV1AffiliateprogramTaxdocumentsByDocIdVerify","description":"Mark a tax document verified.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"docId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/affiliate-program/tax-documents/{docId}/reject":{"post":{"tags":["Affiliate Program"],"summary":"Reject a tax document (reason required).","operationId":"postApiV1AffiliateprogramTaxdocumentsByDocIdReject","description":"Reject a tax document (reason required).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"docId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}},"example":{"reason":"Illegible — please resubmit"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/affiliate-program/tiers":{"post":{"tags":["Affiliate Program"],"summary":"Create a commission tier.","operationId":"postApiV1AffiliateprogramTiers","description":"Create a commission tier.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"minActiveReferrals":{"type":"integer"},"percentage":{"type":"integer"},"label":{"type":"string"}}},"example":{"minActiveReferrals":5,"percentage":15,"label":"Silver"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/affiliate-program/tiers/{tierId}":{"delete":{"tags":["Affiliate Program"],"summary":"Delete a commission tier.","operationId":"deleteApiV1AffiliateprogramTiersByTierId","description":"Delete a commission tier.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"tierId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/team/members":{"get":{"tags":["Team & Users"],"summary":"Brand-staff roster + pending team invitations (no patient PHI).","operationId":"getApiV1TeamMembers","description":"Brand-staff roster + pending team invitations (no patient PHI).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/team/invite":{"post":{"tags":["Team & Users"],"summary":"Invite a team member.","operationId":"postApiV1TeamInvite","description":"Invite a team member.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"role":{"type":"string"}}},"example":{"email":"colleague@brand.com","role":"member"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/team/invitations/{invitationId}":{"delete":{"tags":["Team & Users"],"summary":"Revoke a pending team invitation.","operationId":"deleteApiV1TeamInvitationsByInvitationId","description":"Revoke a pending team invitation.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"invitationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/team/{userId}":{"delete":{"tags":["Team & Users"],"summary":"Remove a team member from the clinic.","operationId":"deleteApiV1TeamByUserId","description":"Remove a team member from the clinic.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/team/{userId}/role":{"patch":{"tags":["Team & Users"],"summary":"Change a team member's role ('admin' or 'member'; ownership cannot be assigned via the API).","operationId":"patchApiV1TeamByUserIdRole","description":"Change a team member's role ('admin' or 'member'; ownership cannot be assigned via the API).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string"}}},"example":{"role":"admin"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/clinic":{"get":{"tags":["Organization & Clinic"],"summary":"The key clinic's profile.","operationId":"getApiV1Clinic","description":"The key clinic's profile.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/config/fees":{"get":{"tags":["Organization & Clinic"],"summary":"Fee configuration for the clinic (pharmacy, doctor, Stripe, merchant fees).","operationId":"getApiV1ConfigFees","description":"Fee configuration for the clinic (pharmacy, doctor, Stripe, merchant fees).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/organization":{"get":{"tags":["Organization & Clinic"],"summary":"The key clinic's org settings + notification config.","operationId":"getApiV1Organization","description":"The key clinic's org settings + notification config.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/clinic/email-domain":{"get":{"tags":["Organization & Clinic"],"summary":"SendGrid email-domain authentication status.","operationId":"getApiV1ClinicEmaildomain","description":"SendGrid email-domain authentication status.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/clinic/email-sender":{"put":{"tags":["Organization & Clinic"],"summary":"Update the reply-to email sender address.","operationId":"putApiV1ClinicEmailsender","description":"Update the reply-to email sender address.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"replyTo":{"type":"string"}}},"example":{"replyTo":"support@brand.com"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/clinic/email-domain/start":{"post":{"tags":["Organization & Clinic"],"summary":"Start SendGrid domain authentication (returns DNS records to add).","operationId":"postApiV1ClinicEmaildomainStart","description":"Start SendGrid domain authentication (returns DNS records to add).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"fromLocalPart":{"type":"string"}}},"example":{"domain":"brand.com","fromLocalPart":"support"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/clinic/email-domain/verify":{"post":{"tags":["Organization & Clinic"],"summary":"Verify the SendGrid domain authentication DNS records.","operationId":"postApiV1ClinicEmaildomainVerify","description":"Verify the SendGrid domain authentication DNS records.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/clinic/email-domain/remove":{"post":{"tags":["Organization & Clinic"],"summary":"Remove SendGrid domain authentication.","operationId":"postApiV1ClinicEmaildomainRemove","description":"Remove SendGrid domain authentication.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/clinic/{id}/upload-logo":{"post":{"tags":["Organization & Clinic"],"summary":"Upload the clinic logo (multipart, field `logo`; :id is ignored, always the key's own clinic).","operationId":"postApiV1ClinicByIdUploadlogo","description":"Upload the clinic logo (multipart, field `logo`; :id is ignored, always the key's own clinic).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"logo":{"type":"string","format":"binary","description":"Upload file field"}},"required":["logo"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/custom-website":{"get":{"tags":["Custom Website"],"summary":"The clinic's storefront config.","operationId":"getApiV1Customwebsite","description":"The clinic's storefront config.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Custom Website"],"summary":"Create/update the storefront config.","operationId":"postApiV1Customwebsite","description":"Create/update the storefront config.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"heroPrimaryButtonText":{"type":"string"},"isActive":{"type":"boolean"},"footerColor":{"type":"string"},"socialMediaLinks":{"type":"object","properties":{"instagram":{"type":"string"}}}}},"example":{"heroPrimaryButtonText":"Get started","isActive":true,"footerColor":"#111827","socialMediaLinks":{"instagram":"https://instagram.com/brand"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/custom-website/toggle-active":{"post":{"tags":["Custom Website"],"summary":"Enable/disable the custom website.","operationId":"postApiV1CustomwebsiteToggleactive","description":"Enable/disable the custom website.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"isActive":{"type":"boolean"}}},"example":{"isActive":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/custom-website/reset-footer":{"post":{"tags":["Custom Website"],"summary":"Reset footer content to defaults.","operationId":"postApiV1CustomwebsiteResetfooter","description":"Reset footer content to defaults.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/custom-website/reset-social-media":{"post":{"tags":["Custom Website"],"summary":"Reset social-media links to defaults.","operationId":"postApiV1CustomwebsiteResetsocialmedia","description":"Reset social-media links to defaults.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/custom-website/upload-logo":{"post":{"tags":["Custom Website"],"summary":"Upload the storefront logo (multipart, field `logo`).","operationId":"postApiV1CustomwebsiteUploadlogo","description":"Upload the storefront logo (multipart, field `logo`).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"logo":{"type":"string","format":"binary","description":"Upload file field"}},"required":["logo"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/custom-website/upload-hero":{"post":{"tags":["Custom Website"],"summary":"Upload the storefront hero image (multipart, field `heroImage`).","operationId":"postApiV1CustomwebsiteUploadhero","description":"Upload the storefront hero image (multipart, field `heroImage`).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"heroImage":{"type":"string","format":"binary","description":"Upload file field"}},"required":["heroImage"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/custom-website/logo-proxy":{"get":{"tags":["Custom Website"],"summary":"CORS-convenience proxy that streams the storefront logo bytes.","operationId":"getApiV1CustomwebsiteLogoproxy","description":"CORS-convenience proxy that streams the storefront logo bytes.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/conversations/{id}":{"get":{"tags":["Support & Conversations"],"summary":"One support conversation thread (own-clinic only).","operationId":"getApiV1ConversationsById","description":"One support conversation thread (own-clinic only).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/conversations/{id}/messages":{"post":{"tags":["Support & Conversations"],"summary":"Post a message to a conversation.","operationId":"postApiV1ConversationsByIdMessages","description":"Post a message to a conversation.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"isInternalNote":{"type":"boolean"}}},"example":{"message":"Thanks for reaching out — how can we help?","isInternalNote":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/conversations/{id}/resolve":{"post":{"tags":["Support & Conversations"],"summary":"Mark a conversation resolved.","operationId":"postApiV1ConversationsByIdResolve","description":"Mark a conversation resolved.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/support/tickets":{"get":{"tags":["Support & Conversations"],"summary":"List the clinic's support tickets.","operationId":"getApiV1SupportTickets","description":"List the clinic's support tickets.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"example":"1"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25},"example":"25"},{"name":"status","in":"query","required":false,"schema":{"type":"string"},"example":"open"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/support/users":{"get":{"tags":["Support & Conversations"],"summary":"Users available for support-ticket assignment.","operationId":"getApiV1SupportUsers","description":"Users available for support-ticket assignment.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/support/tickets/{id}/messages":{"post":{"tags":["Support & Conversations"],"summary":"Post a message on a support ticket.","operationId":"postApiV1SupportTicketsByIdMessages","description":"Post a message on a support ticket.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}},"example":{"message":"We've escalated this to the pharmacy."}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/support/tickets/{id}":{"get":{"tags":["Support & Conversations"],"summary":"One support ticket (own-clinic only).","operationId":"getApiV1SupportTicketsById","description":"One support ticket (own-clinic only).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["Support & Conversations"],"summary":"Update a support ticket (title/description/assignment/status).","operationId":"putApiV1SupportTicketsById","description":"Update a support ticket (title/description/assignment/status).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"assignedTeam":{"type":"string"},"status":{"type":"string"}}},"example":{"title":"Shipment delayed","description":"...","assignedTeam":"fulfillment","status":"in_progress"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/forms/global-products":{"get":{"tags":["Forms & Global Products"],"summary":"List the clinic's global-product intake forms.","operationId":"getApiV1FormsGlobalproducts","description":"List the clinic's global-product intake forms.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Forms & Global Products"],"summary":"Attach an intake form to a global product.","operationId":"postApiV1FormsGlobalproducts","description":"Attach an intake form to a global product.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"globalProductId":{"type":"string"},"formId":{"type":"string"}}},"example":{"globalProductId":"<global-product-uuid>","formId":"<form-uuid>"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"delete":{"tags":["Forms & Global Products"],"summary":"Detach an intake form from a global product.","operationId":"deleteApiV1FormsGlobalproducts","description":"Detach an intake form from a global product.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"formId":{"type":"string"}}},"example":{"formId":"<form-uuid>"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/intake-requests":{"get":{"tags":["Intake Requests"],"summary":"The clinic's own intake-form requests (no PHI).","operationId":"getApiV1Intakerequests","description":"The clinic's own intake-form requests (no PHI).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Intake Requests"],"summary":"Create an intake-form request (requestedByUserId stored NULL for a key actor).","operationId":"postApiV1Intakerequests","description":"Create an intake-form request (requestedByUserId stored NULL for a key actor).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"treatmentName":{"type":"string"},"notes":{"type":"string"}}},"example":{"treatmentName":"New treatment intake","notes":"..."}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/upload/logo":{"post":{"tags":["Misc / Uploads"],"summary":"Upload a logo to S3 and set Clinic.logo for the key's clinic (multipart, field `logo`).","operationId":"postApiV1UploadLogo","description":"Upload a logo to S3 and set Clinic.logo for the key's clinic (multipart, field `logo`).","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"logo":{"type":"string","format":"binary","description":"Upload file field"}},"required":["logo"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/teleform-removals":{"get":{"tags":["Misc / Uploads"],"summary":"Teleform wind-down rows for the clinic (no PHI).","operationId":"getApiV1Teleformremovals","description":"Teleform wind-down rows for the clinic (no PHI).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/teleform-removals/{id}/cancel":{"post":{"tags":["Misc / Uploads"],"summary":"Cancel a scheduled teleform removal (own-clinic only).","operationId":"postApiV1TeleformremovalsByIdCancel","description":"Cancel a scheduled teleform removal (own-clinic only).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}},"example":{"reason":"Keeping this form active"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/checkout/sessions":{"post":{"tags":["Checkout Sessions"],"summary":"Create a checkout session for one of the clinic's own programs","operationId":"postApiV1CheckoutSessions","description":"Creates the session bookkeeping row for the FUSE-hosted, iframe-isolated intake+checkout component. Computes and stores questionnaireVersionHash (the legal audit trail — sha256 over the program's questionnaire content at creation time) and returns an opaque sessionToken + embedUrl the brand mounts in an iframe. This is the ONE endpoint a PUBLISHABLE key (`fuse_pk_…`) may call — every other endpoint on this surface, including GET /checkout/sessions/{id}, 403s a publishable key with `KEY_KIND_NOT_ALLOWED`. Publishable keys are additionally hard rate-limited on this route.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSessionCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/CheckoutSessionCreated"}}}}}},"400":{"description":"Bad request (missing/invalid programId, metadata, or successUrl) or NO_QUESTIONNAIRE_CONFIGURED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Insufficient scope (INSUFFICIENT_SCOPE) — read-only key attempted a write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/api/v1/checkout/sessions/{id}":{"get":{"tags":["Checkout Sessions"],"summary":"Get checkout session status (own-clinic only)","operationId":"getApiV1CheckoutSessionsById","description":"Returns session status + orderId (once completed) — NEVER intake questions or answers. Secret keys only: a publishable key gets 403 `KEY_KIND_NOT_ALLOWED` here too, even though it authenticated successfully.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/CheckoutSessionStatus"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Publishable key used on a route it may not call (KEY_KIND_NOT_ALLOWED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/webhooks":{"post":{"tags":["Webhooks"],"summary":"Register an outbound webhook endpoint","operationId":"postApiV1Webhooks","description":"Register a publicly-reachable HTTPS endpoint to receive signed, opaque-id-only checkout lifecycle events (`session.completed`, `order.created`, `payment.succeeded`), intake conversion events (`intake.started`, `intake.abandoned`), order/fulfillment events (`order.placed`, `order.cancelled`, `order.doctor_approved`, `order.doctor_denied`, `order.sent_to_pharmacy`, `order.shipped`, `order.delivered`, `payment.failed`, `shipment.updated`), telehealth events (`appointment.scheduled`, `appointment.cancelled`) and suppression sync (`contact.unsubscribed`) instead of polling GET /checkout/sessions/{id}. The full accepted event set is the 17-value enum below — registration rejects anything else with 400. Each delivery body is `{ id, event, createdAt, data:{ …opaque ids + event-specific fields } }`; the exact per-event payload key sets are documented in docs/api/external-brand-api/OUTBOUND-WEBHOOKS.md (source of truth: BRAND_WEBHOOK_PAYLOAD_KEYS in patient-api/src/services/brand-webhook-dispatch.service.ts). Note `order.doctor_denied` is accepted at registration but currently has no firing source in the API — it is declared for forward compatibility and will not be delivered until the denial chokepoint emits it. Verify `X-Fuse-Signature: t=<unixSeconds>,v1=<hex>` (HMAC-SHA256 over `<t>.<rawBody>` keyed by the endpoint secret) and dedupe on `X-Fuse-Idempotency-Key` (stable across retries and replays; `X-Fuse-Delivery-Id` is a per-attempt id, not a dedupe key). URLs that resolve to private/link-local addresses are refused and 3xx redirects are not followed (SSRF protection). The secret is returned in THIS response ONLY and is never retrievable again. Requires write scope; secret keys only.\n","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","description":"Absolute https:// URL."},"events":{"type":"array","items":{"type":"string","enum":["session.completed","order.created","payment.succeeded","intake.started","intake.abandoned","order.cancelled","shipment.updated","appointment.scheduled","appointment.cancelled","order.placed","payment.failed","order.doctor_approved","order.doctor_denied","order.sent_to_pharmacy","order.shipped","order.delivered","contact.unsubscribed"]},"minItems":1}}}}}},"responses":{"201":{"description":"Created — secret returned once","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"secret":{"type":"string","description":"Signing secret (whsec_…) — shown once."}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Insufficient scope, or a publishable key used on a route it may not call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"tags":["Webhooks"],"summary":"List the clinic's webhook endpoints (secrets omitted)","operationId":"getApiV1Webhooks","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"lastTriggeredAt":{"type":"string","format":"date-time","nullable":true},"consecutiveFailures":{"type":"integer"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/webhooks/{id}":{"delete":{"tags":["Webhooks"],"summary":"Delete a webhook endpoint (own-clinic only)","operationId":"deleteApiV1WebhooksById","description":"Foreign-clinic ids return 404. Requires write scope; secret keys only.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/products-management":{"get":{"tags":["Products & Catalog"],"summary":"List the brand's products (product-management view).","operationId":"getApiV1Productsmanagement","description":"The brand's product-management list — its own custom products plus the shared platform SKUs (scoped via the key clinic's brand owner). Same scope the FUSE-hosted admin product list shows. No patient PHI. Read scope.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"minimum":1}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"categories","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated list."}},{"name":"isActive","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"pharmacyProvider","in":"query","required":false,"schema":{"type":"string"}},{"name":"isAutoImported","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"hasMdiOffering","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/orders/needs-attention":{"get":{"tags":["Orders"],"summary":"List orders needing attention (failed payment / dunning queue).","operationId":"getApiV1OrdersNeedsattention","description":"The dunning queue: this clinic's orders in `payment_due` whose most recent charge failed, enriched with Stripe retry context. Clinic-scoped by the API key. PHI: patient first/last name only (data-minimized). Read scope.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"count":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"orderNumber":{"type":"string"},"patientName":{"type":["string","null"]},"programName":{"type":["string","null"]},"paymentFailedAt":{"type":["string","null"],"format":"date-time"},"lastPaymentError":{"type":["string","null"]},"enrichment":{"type":"object"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/notifications":{"get":{"tags":["Misc / Uploads"],"summary":"List the brand's notifications.","operationId":"getApiV1Notifications","description":"The brand notification feed (order / financial / program / compliance), resolved via the key clinic's brand owner. Audience is locked to `brand` — a key can never read a patient feed. Read scope.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":30}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"category","in":"query","required":false,"schema":{"type":"string","enum":["order","financial","program","compliance"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"notifications":{"type":"array","items":{"type":"object"}},"unreadCount":{"type":"integer"},"total":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/notifications/read":{"post":{"tags":["Misc / Uploads"],"summary":"Mark brand notifications as read.","operationId":"postApiV1NotificationsRead","description":"Marks the given brand-audience notification ids read (omit `ids` to mark all). Requires the `write` scope.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Omit or send empty to mark every brand-audience notification read."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"updated":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/coupons":{"get":{"tags":["Misc / Uploads"],"summary":"List the brand's customer coupons.","operationId":"getApiV1Coupons","description":"The clinic's own customer-facing discount coupons. Discounts reduce customer-pays and brand profit only — pharmacy, doctor, Stripe and merchant fees are never discounted. Read scope.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"tags":["Misc / Uploads"],"summary":"Create a customer coupon.","operationId":"postApiV1Coupons","description":"Creates a coupon for the key's clinic (code unique per clinic, stored uppercase). Requires the `write` scope.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","discountType","discountValue"],"properties":{"code":{"type":"string"},"description":{"type":["string","null"]},"discountType":{"type":"string","enum":["percent","fixed"]},"discountValue":{"type":"number","description":"> 0; ≤ 100 when discountType=percent."},"startsAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"isActive":{"type":"boolean","default":true},"scope":{"type":"string","enum":["first_charge","all_charges"]},"overMarginBehavior":{"type":"string","enum":["reject","cap","absorb"]},"maxRedemptions":{"type":["integer","null"]},"perCustomerLimit":{"type":["integer","null"]},"minOrderAmount":{"type":["number","null"]}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/coupons/{id}":{"get":{"tags":["Misc / Uploads"],"summary":"Get one of the brand's coupons.","operationId":"getApiV1CouponsById","description":"404s unless the coupon belongs to the key's clinic. Read scope.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["Misc / Uploads"],"summary":"Update one of the brand's coupons.","operationId":"putApiV1CouponsById","description":"Updates a coupon owned by the key's clinic (404 otherwise). Requires the `write` scope.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":["string","null"]},"discountType":{"type":"string","enum":["percent","fixed"]},"discountValue":{"type":"number"},"startsAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"isActive":{"type":"boolean"},"scope":{"type":"string","enum":["first_charge","all_charges"]},"overMarginBehavior":{"type":"string","enum":["reject","cap","absorb"]},"maxRedemptions":{"type":["integer","null"]},"perCustomerLimit":{"type":["integer","null"]},"minOrderAmount":{"type":["number","null"]}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Misc / Uploads"],"summary":"Delete one of the brand's coupons.","operationId":"deleteApiV1CouponsById","description":"Deletes a coupon owned by the key's clinic (404 otherwise). Requires the `write` scope.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/coupons/{id}/performance":{"get":{"tags":["Misc / Uploads"],"summary":"Coupon performance (redemptions, discount totals).","operationId":"getApiV1CouponsByIdPerformance","description":"Redemption counts and discount totals for a coupon owned by the key's clinic (404 otherwise). Read scope.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/pharmacy-price-changes/alerts":{"get":{"tags":["Misc / Uploads"],"summary":"List outstanding pharmacy price-change alerts.","operationId":"getApiV1PharmacypricechangesAlerts","description":"Outstanding pharmacy wholesale-cost change alerts for this clinic's programs, with the current vs suggested program fee and the per-unit margin delta. Brand's own margin data — no patient PHI. Read scope.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"count":{"type":"integer"},"alerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"productId":{"type":["string","null"],"format":"uuid"},"programId":{"type":["string","null"],"format":"uuid"},"globalProductId":{"type":["string","null"],"format":"uuid"},"direction":{"type":"string","enum":["increase","decrease"]},"currentProgramFee":{"type":["number","null"]},"suggestedProgramFee":{"type":["number","null"]},"perUnitMarginDelta":{"type":["number","null"]},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/v1/pharmacy-price-changes/alerts/{alertId}/acknowledge":{"post":{"tags":["Misc / Uploads"],"summary":"Acknowledge a pharmacy price-change alert.","operationId":"postApiV1PharmacypricechangesAlertsByAlertIdAcknowledge","description":"Dismisses an outstanding alert owned by the key's clinic (404 otherwise). Idempotent — acknowledging an already-acknowledged alert returns its current state. Attribution is recorded in the audit log (no user row behind an API key). Requires the `write` scope.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"alertId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Acknowledged","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/crm/connection/phi-sync":{"patch":{"tags":["CRM · Connection"],"summary":"Enable or disable patient-data (PHI) sync to the connected CRM.","operationId":"patchApiV1CrmConnectionPhisync","description":"Toggles PHI egress to the clinic's connected CRM. Enabling requires `baaAttested: true` in the body AND the verified BAA on file with FUSE — otherwise 403 `CRM_BAA_REQUIRED`. Disabling is always permitted. 409 if no CRM is connected. Requires the `write` scope.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phiSyncEnabled"],"properties":{"phiSyncEnabled":{"type":"boolean"},"baaAttested":{"type":"boolean","description":"Must be true when enabling — confirms the brand holds a BAA with its CRM provider."}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"No CRM connected for this clinic."}}}},"/api/v1/analytics/forms/{formId}/sessions":{"get":{"tags":["Dashboard & Analytics"],"summary":"Per-form intake funnel sessions.","operationId":"getApiV1AnalyticsFormsByFormIdSessions","description":"Session-level intake funnel breakdown for one of this clinic's forms. ⚠️ PHI-bearing — the sessions array includes visitor/patient name, email and phone. Read-only (read scope); every call is audit-logged.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"formId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/analytics/programs/{questionnaireId}/sessions":{"get":{"tags":["Dashboard & Analytics"],"summary":"Per-program intake funnel sessions.","operationId":"getApiV1AnalyticsProgramsByQuestionnaireIdSessions","description":"Session-level intake funnel breakdown keyed by the program's teleform (questionnaire) id, scoped to this clinic's own programs. ⚠️ PHI-bearing — the sessions array includes visitor/patient name, email and phone. Read-only (read scope); every call is audit-logged.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"questionnaireId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Clinic-scoped API key. Keep server-side; never expose in a browser or app bundle."},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"FUSE brand-admin JWT (from POST /auth/signin). Used ONLY by the key-management endpoints — the external /api/v1 surface never accepts JWTs, and API keys never work on key management."}},"responses":{"Unauthorized":{"description":"Missing, invalid, inactive, or expired API key (or JWT)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Authenticated but not permitted (insufficient scope, wrong role, or FUSE feature not enabled)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Resource not found (or not owned by the key's clinic)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BadRequest":{"description":"Bad request / business-rule failure (may include a `code`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"MessageOk":{"description":"Success with a message","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"TooManyRequests":{"description":"Rate limit exceeded for this key. Respect the `Retry-After` header. Applies to every endpoint.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"schemas":{"DataEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{}}},"ErrorEnvelope":{"description":"Failure shape. NOTE: most modules use `message`; programs endpoints use `error`. Read both. Some errors include a machine-readable `code` and/or a `data` payload.","type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"error":{"type":"string"},"code":{"type":"string"},"data":{}}},"PagePagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"OffsetPagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"},"hasMore":{"type":"boolean"}}},"OrderBrandView":{"description":"Sanitized brand-facing order (whitelisted fields only).","type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderNumber":{"type":"string"},"status":{"type":"string"},"totalAmount":{"type":"number"},"subtotalAmount":{"type":"number"},"discountAmount":{"type":"number"},"taxAmount":{"type":"number"},"shippingAmount":{"type":"number"},"brandAmount":{"type":"number"},"billingInterval":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"shippedAt":{"type":"string","nullable":true,"format":"date-time"},"deliveredAt":{"type":"string","nullable":true,"format":"date-time"},"fulfillmentType":{"type":"string"},"approvedByDoctor":{"type":"boolean"},"feeBreakdown":{"type":"object","additionalProperties":true,"description":"Per-order fee waterfall."},"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"phoneNumber":{"type":"string","nullable":true}}},"orderItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quantity":{"type":"integer"},"unitPrice":{"type":"number"},"totalPrice":{"type":"number"},"product":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}},"payment":{"type":"object","properties":{"status":{"type":"string"},"paymentMethod":{"type":"string"}}},"shippingAddress":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zipCode":{"type":"string"},"country":{"type":"string"}}},"shippingOrders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"trackingNumber":{"type":"string","nullable":true},"trackingUrl":{"type":"string","nullable":true}}}}}},"Customer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"phoneNumber":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"orderCount":{"type":"integer"},"totalRevenue":{"type":"number"},"categories":{"type":"array","items":{"type":"string"}},"hasActiveSubscription":{"type":"boolean"}}},"CatalogProduct":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"imageUrl":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"requiresCooler":{"type":"boolean"},"pharmacyPrice":{"type":"number"},"facilitationFee":{"type":"number"},"price":{"type":"number"},"pharmacyName":{"type":"string","nullable":true},"pharmacyRole":{"type":"string","nullable":true,"enum":["primary","secondary","fallback"]}}},"Product":{"description":"Full management view (serializeProduct) — all Product columns plus derived fields.","type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"categories":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"pharmacyProvider":{"type":"string","nullable":true},"pharmacyPrice":{"type":"number"},"pharmacyProductId":{"type":"string","nullable":true},"brandName":{"type":"string","nullable":true},"imageUrl":{"type":"string","nullable":true},"pharmacyCoverages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"customName":{"type":"string","nullable":true},"pharmacy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}}}}}}},"additionalProperties":true},"ProductUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":{"type":"string","minLength":1},"activeIngredients":{"type":"array","minItems":1,"description":"Active ingredients. Accepts either a bare string per entry (the original shape, still fully supported) or an object with `name` and optional `strength`. Stored as `{name, strength}`; a null strength means \"not recorded\" and is never inferred from the name.","items":{"oneOf":[{"type":"string"},{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"strength":{"type":"string","nullable":true}}}]}},"placeholderSig":{"type":"string","minLength":1},"imageUrl":{"type":"string","format":"uri"},"pharmacyProvider":{"type":"string"},"pharmacyPrice":{"type":"number","minimum":0},"pharmacyProductId":{"type":"string","minLength":1},"category":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"}},"additionalProperties":true},"Program":{"description":"Program.toJSON plus derived links and ClinicProgram overrides.","type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"isFeatured":{"type":"boolean"},"nonMedicalServiceFee":{"type":"number"},"heroImageUrl":{"type":"string","nullable":true},"customSlug":{"type":"string","nullable":true},"accentColor":{"type":"string","nullable":true},"sellableProductCount":{"type":"integer"},"unpricedProductCount":{"type":"integer"},"programGlobalProducts":{"type":"array","items":{"$ref":"#/components/schemas/ProgramGlobalProduct"}}},"additionalProperties":true},"ProgramGlobalProduct":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"displayOrder":{"type":"integer"},"isPatientVisible":{"type":"boolean"},"globalProduct":{"type":"object","additionalProperties":true}}},"ProgramCreate":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"medicalTemplateId":{"type":"string","format":"uuid"},"individualGlobalProductId":{"type":"string","format":"uuid"},"parentProgramId":{"type":"string","format":"uuid"},"templateId":{"type":"string","format":"uuid"},"hasPatientPortal":{"type":"boolean"},"autoTitration":{"type":"boolean"}},"additionalProperties":true},"ProgramUpdate":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"portalDisplayName":{"type":"string"},"isActive":{"type":"boolean"},"isFeatured":{"type":"boolean"},"productOrder":{"type":"array","items":{"type":"string","format":"uuid"}},"nonMedicalServiceFee":{"type":"number"},"customSlug":{"type":"string","pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"},"accentColor":{"type":"string","nullable":true,"pattern":"^#[0-9A-Fa-f]{6}$"},"productPricing":{"type":"object","description":"Per-product pricing, keyed by globalProductId. Writing `programFee` sets this brand's authoritative patient price for that product (persisted on ClinicProgramGlobalProduct) and is rejected if it would put the product below margin. Read the resulting effective prices back from GET /api/v1/programs/{id}/products.","additionalProperties":{"$ref":"#/components/schemas/ProductPricingEntry"}},"autoTitration":{"type":"boolean"}},"additionalProperties":true},"ProductPricingEntry":{"type":"object","description":"One product's pricing configuration inside `productPricing`.","properties":{"programFee":{"type":"number","nullable":true,"description":"The all-in patient price per cycle for this product, in USD. This is the brand's own price and the only field that changes what checkout charges. Null clears the override."},"monthlyDiscountPercent":{"type":"number","nullable":true,"description":"Percentage discount applied to the monthly plan (0-100)."},"multiMonthPlans":{"type":"array","description":"Optional prepay plans (e.g. 3-month) offered for this product.","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"ProgramProductPricing":{"type":"object","properties":{"globalProductId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"The patient-facing product label."},"displayOrder":{"type":"integer","nullable":true},"linkSource":{"type":"string","enum":["program","template","pool"],"description":"Which link source offered this product — the storefront's fallback chain: the program's own links, its template's links, or the teleform's approved product pool."},"isPatientVisible":{"type":"boolean","description":"Whether the brand has this product switched on for its storefront."},"displayPrice":{"type":"number","nullable":true,"description":"What the patient is charged per cycle before discounts/coupons and before the program-level nonMedicalServiceFee. Null when the product is not sellable (checkout would reject it) — never fall back to a pharmacy cost."},"effectiveProgramFee":{"type":"number","description":"Configured fee after clinic-override -> program-base resolution (0 = none)."},"feeSource":{"type":"string","enum":["clinic_override","program_base","placeholder","none"],"description":"Which field produced effectiveProgramFee."},"clinicProgramFee":{"type":"number","nullable":true,"description":"This brand's own override — what PUT /programs/{id} productPricing writes."},"programBaseFee":{"type":"number","nullable":true,"description":"The program-level base fee."},"placeholderPrice":{"type":"number","nullable":true,"description":"Tenant SUGGESTION only. Not the canonical fee."},"pharmacyBasePrice":{"type":"number","description":"The REAL pharmacy cost plus facilitation fees — the floor a fee must clear. Never a placeholder substitution, so a placeholder in front of a higher pharmacy cost cannot read as the cost."},"facilitationFee":{"type":"number","description":"Clinic-level plus per-product facilitation fee included in pharmacyBasePrice."},"packDurationMonths":{"type":"integer","nullable":true,"description":"How many BILLING MONTHS one unit of displayPrice covers. displayPrice is the price of ONE PACK, not of one month: checkout charges the chargeable unit price times the number of PACKS a term needs, so displayPrice times months is WRONG whenever a pack spans more than one month. A 3-month pack on a 6-month term is TWO packs, not six."},"vialsPerPack":{"type":"integer","nullable":true,"description":"Dispense quantity inside one pack."},"supplyDays":{"type":"integer","nullable":true,"description":"Days of supply for the pharmacy cadence — not a billing quantity."},"allowPrepay":{"type":"boolean","description":"Whether multi-month prepay terms may be offered for this product. Never null: an unknown value would let a storefront offer a term checkout then rejects."},"isSellable":{"type":"boolean","description":"A positive chargeable price resolves (fee half of the shared predicate)."},"isCostBacked":{"type":"boolean","description":"A pharmacy cost resolves to dispense against (cost half)."},"hasResolvedPrice":{"type":"boolean","description":"This product resolves a chargeable price AND a pharmacy cost AND is switched on for the storefront. NOT an activation-readiness signal: it does not check the program's activation status, does not check the questionnaire's FUSE clinical approval, and the pharmacy cost is priced-anywhere rather than per shipping state — a product priced in some states and unpriced in others still reads true. No endpoint on this API answers \"safe to publish\" today: GET /api/v1/programs/{id}/products/activation-status returns only per-product on/off toggles (ClinicProgramGlobalProduct.isActive), not a gate, and per-state pharmacy coverage is available only from GET /api/v1/public/products/{productId}/pharmacy-coverages. Treat this field as \"a price and a generic pharmacy cost resolve\" and nothing more."}}},"ProgramPricingRead":{"type":"object","properties":{"programId":{"type":"string","format":"uuid"},"nonMedicalServiceFee":{"type":"number","description":"The LEGACY per-program non-medical service fee, and 0 for every program with GlobalProduct links (which is every program sold today). DO NOT add it to displayPrice: for a GlobalProduct program the fee is already baked into the per-product price and is only derived afterwards for ledger bookkeeping — what Stripe recurs is the resolved per-product price with nothing added. See nonMedicalServiceFeeIncludedInDisplayPrice."},"nonMedicalServiceFeeIncludedInDisplayPrice":{"type":"boolean","description":"True when the non-medical service fee is already inside displayPrice (a GlobalProduct-linked program). When true, displayPrice is the whole per-cycle product charge."},"products":{"type":"array","items":{"$ref":"#/components/schemas/ProgramProductPricing"}}}},"ProgramsOverview":{"type":"object","properties":{"stats":{"type":"object","properties":{"livePrograms":{"type":"integer"},"draftPrograms":{"type":"integer"},"pausedPrograms":{"type":"integer"},"totalPatients":{"type":"integer"},"estBilledMonthlyCents":{"type":"integer"},"estNetMonthlyCents":{"type":"integer"}}},"perProgram":{"type":"array","items":{"type":"object","properties":{"programId":{"type":"string","format":"uuid"},"patients":{"type":"integer"},"estBilledMonthlyCents":{"type":"integer"},"estNetMonthlyCents":{"type":"integer"}}}},"attention":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"programId":{"type":"string","format":"uuid"},"programName":{"type":"string"},"headline":{"type":"string"},"detail":{"type":"string"},"estValueCents":{"type":"integer"},"action":{"type":"string"}}}}}},"Treatment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"selected":{"type":"boolean"},"brandColor":{"type":"string","nullable":true},"brandLogo":{"type":"string","nullable":true},"clinicSlug":{"type":"string","nullable":true},"productsPrice":{"type":"number"}},"additionalProperties":true},"BrandTreatment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"treatmentLogo":{"type":"string","nullable":true},"active":{"type":"boolean"},"selected":{"type":"boolean"},"brandLogo":{"type":"string","nullable":true},"brandColor":{"type":"string","nullable":true},"clinicSlug":{"type":"string","nullable":true}}},"PayoutItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"orderId":{"type":"string","nullable":true,"format":"uuid"},"orderNumber":{"type":"string","nullable":true},"amount":{"type":"number"},"totalAmount":{"type":"number"},"date":{"type":"string","format":"date-time"},"status":{"type":"string"},"stripeTransferId":{"type":"string","nullable":true},"customer":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"email":{"type":"string"}}}}},"BrandBalance":{"type":"object","properties":{"balance":{"type":"object","properties":{"totalReceived":{"type":"number"},"totalWithdrawn":{"type":"number"},"currentBalance":{"type":"number"},"lastUpdated":{"type":"string","format":"date-time"}}},"stripeBalance":{"type":"object","nullable":true,"properties":{"available":{"type":"number"},"pending":{"type":"number"}}},"withdrawable":{"type":"number"},"reserve":{"type":"object","properties":{"totalHeld":{"type":"number"},"totalReleased":{"type":"number"},"totalForfeited":{"type":"number"},"heldCount":{"type":"integer"}}},"heldBalance":{"type":"object","properties":{"heldOwed":{"type":"number"},"hasHeldBalance":{"type":"boolean"},"isConnected":{"type":"boolean"}}},"recentActivity":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"Contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"phoneNumber":{"type":"string","nullable":true},"emailOptedOut":{"type":"boolean"},"smsOptedOut":{"type":"boolean"},"optOutDate":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"lastLoginAt":{"type":"string","nullable":true,"format":"date-time"},"lastContactDate":{"type":"string","nullable":true,"format":"date-time"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}}},"Tag":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"category":{"type":"string"},"color":{"type":"string"},"clinicId":{"type":"string","format":"uuid"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Sequence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clinicId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger":{"type":"object","additionalProperties":true},"steps":{"type":"array","items":{"$ref":"#/components/schemas/SequenceStep"}},"analytics":{"type":"object","additionalProperties":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"SequenceStep":{"type":"object","description":"A delay, email, or sms step. Requires an id (or step_id) and a type (or stepType). delay steps carry timeSeconds; email/sms steps carry a templateId or custom text.","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["delay","email","sms"]},"timeSeconds":{"type":"number","minimum":0},"useCustomText":{"type":"boolean"},"templateId":{"type":"string","format":"uuid"},"customText":{"type":"string"},"customSubject":{"type":"string"}}},"MessageTemplate":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"clinicId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","enum":["email","sms"]},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"category":{"type":"string","nullable":true},"mergeFields":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"version":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}},"CheckoutSessionCreate":{"type":"object","required":["programId"],"properties":{"programId":{"type":"string","format":"uuid","description":"Must belong to the key's own clinic (404 otherwise)."},"metadata":{"type":"object","additionalProperties":true,"description":"Brand-supplied data, stored verbatim and capped at 16 KiB (DB CHECK constraint plus model-layer validation). FUSE never displays or acts on it, with one exception: the marketing-attribution keys lead_id (or legacy leadId), utm_source, utm_medium, utm_campaign, utm_content, gclid and fbclid are copied onto the resulting order and echoed on the intake.started webhook. Every other key is ignored.\n"},"successUrl":{"type":["string","null"],"format":"uri","description":"Absolute https:// URL only — http/javascript:/data: and relative paths are rejected. Navigates the checkout IFRAME after payment, never the brand's page — move your own page from the fuse:completed event instead.\n"}}},"CheckoutSessionCreated":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"sessionToken":{"type":"string","description":"Opaque, HMAC-signed, short-lived (~30 min) credential for the embed page (not this API-key-authenticated surface) to load and render the session's questionnaire.\n"},"embedUrl":{"type":"string","format":"uri","description":"Mount this in an iframe on the brand's page."},"expiresAt":{"type":"string","format":"date-time"}}},"CheckoutSessionStatus":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","in_progress","completed","expired","abandoned"]},"orderId":{"type":["string","null"],"format":"uuid","description":"Set once the embed flow completes checkout."},"expiresAt":{"type":"string","format":"date-time"}}}}}}