Public vs internal API surface

Use this page to stay honest about what third-party integrations may call.

Public (integration-friendly)

Surface	Auth	Purpose
`GET /api/public/v1/customers`	Org API key Bearer	List customers
`GET /api/public/v1/appointments`	Org API key Bearer	List appointments
`GET /openapi.json`	None	OpenAPI document

Contract source of truth in code:

Routes: app/api/public/v1/**
Zod + OpenAPI: lib/openapi/public-v1-schemas.ts, lib/openapi/public-v1-registry.ts

Do not build partner integrations on these without an explicit product contract:

Surface	Why it is internal
`/api/dashboard/`, most `/api/` session routes	NextAuth cookie/session; CSRF and role checks for the web app
`/api/admin/*`	Super-admin only
`/api/stripe/*`, webhooks	Platform billing / Stripe
`/api/scim/v2/*`	Separate enterprise SCIM product surface (if enabled)
`/api/cron/*`	Scheduled jobs with shared secrets
HTML scraping of `/dashboard/**`	Unstable, not an API

These product areas exist in the dashboard but have no public API key endpoints in v1:

If you need a resource that is not listed, contact product — do not invent paths.

Every public request is scoped by the organization on the API key.
Soft-deleted / inactive rows are excluded (isActive: true filters on customers and appointments).
PHI and sensitive fields: treat customer PII and notes as confidential; do not log full payloads in multi-tenant systems.