API Overview

Base URL

All API endpoints use the /api/v1/ prefix. This prefix is centralized in packages/shared via SERVICE_PREFIXES.api and the apiPath() builder function, so future URI changes only require updating one file.

Authentication

Authenticated endpoints require a JWT Bearer token in the Authorization header:

Authorization: Bearer <token>

Obtain a token via POST /api/v1/auth/login.

Error Format

All errors follow a standard format:

{
  "error": "Human-readable message",
  "code": "MACHINE_CODE",
  "details": {}
}

Endpoints

Auth (Public)

Method	Path	Description
POST	/api/v1/auth/register	Create admin account + tenant
POST	/api/v1/auth/login	Login, returns JWT (or changeToken if force-password-change)
POST	/api/v1/auth/change-password	Complete forced password change (purpose-scoped JWT)
POST	/api/v1/auth/accept-invite	Accept team invite, set password
POST	/api/v1/auth/contractor-token	Generate contractor inspection token (configurable TTL)

Auth (Authenticated)

Method	Path	Auth	Description
GET	/api/v1/auth/me	JWT	Current user info + tenant config

Leads

Method	Path	Auth	Description
GET	/api/v1/leads	JWT	List leads (paginated, sortable, filterable)
GET	/api/v1/leads/:id	JWT	Lead detail with scoring breakdown
POST	/api/v1/leads	JWT (admin/member)	Create a lead
PATCH	/api/v1/leads/:id	JWT (admin/member)	Update a lead
DELETE	/api/v1/leads/:id	JWT (admin)	Delete a lead
POST	/api/v1/leads/:id/convert	JWT (admin/member)	Convert lead to customer

Customers

Method	Path	Auth	Description
GET	/api/v1/customers	JWT	List customers (paginated)
GET	/api/v1/customers/:id	JWT	Customer detail
POST	/api/v1/customers	JWT (admin/member)	Create a customer
PATCH	/api/v1/customers/:id	JWT (admin/member)	Update a customer

Projects

Method	Path	Auth	Description
GET	/api/v1/projects	JWT	List projects
GET	/api/v1/projects/:id	JWT	Project detail
POST	/api/v1/projects	JWT (admin/member)	Create a project
PATCH	/api/v1/projects/:id	JWT (admin/member)	Update a project

Estimates / Quotes

Method	Path	Auth	Description
GET	/api/v1/estimates	JWT	List estimates (auto-expires stale quotes)
GET	/api/v1/estimates/:id	JWT	Estimate detail with line items
POST	/api/v1/estimates	JWT (admin/member)	Create estimate (generates display_id QT-{seq}-{rev})
PATCH	/api/v1/estimates/:id	JWT (admin/member)	Update estimate (content-locked for non-draft)
POST	/api/v1/estimates/:id/duplicate	JWT (admin/member)	Create revision (supersedes original)
POST	/api/v1/estimates/:id/clone	JWT (admin/member)	Independent copy with new identity
POST	/api/v1/estimates/:id/renew	JWT (admin/member)	Renew expired quote with new expiration
POST	/api/v1/estimates/:id/share	JWT (admin/member)	Generate share token (30-day default)
POST	/api/v1/estimates/:id/convert	JWT (admin/member)	Convert to project (creates tasks from line items)
POST	/api/v1/estimates/:id/archive	JWT (admin/member)	Archive estimate
POST	/api/v1/estimates/:id/unarchive	JWT (admin/member)	Unarchive estimate
GET	/api/v1/estimates/:id/pdf	JWT	HTML rendering (format=html param for raw HTML)
POST	/api/v1/estimates/preview	JWT	Render HTML from builder data (no DB write)

Estimate Attachments

Method	Path	Auth	Description
GET	/api/v1/estimates/:id/attachments	JWT	List attachments (ordered by sort_order)
POST	/api/v1/estimates/:id/attachments	JWT (admin/member)	Upload attachment (multipart/form-data, draft only)
DELETE	/api/v1/estimates/:id/attachments/:aid	JWT (admin/member)	Delete attachment (removes from R2 + DB)
GET	/api/v1/estimates/:id/attachments/:aid/download	JWT	Download attachment (streams from R2)

Public Quote Access (no auth)

Method	Path	Description
GET	/api/v1/public/quote/:token	Public quote HTML view (checks token expiry)
GET	/api/v1/public/quote/:token/pdf	Public quote PDF download
GET	/api/v1/public/quote/:token/attachments/:aid	Public attachment download

Catalog (Feature-Gated)

Method	Path	Auth	Description
GET	/api/v1/catalog/items	JWT	List catalog items
POST	/api/v1/catalog/items	JWT (admin)	Create catalog item
PATCH	/api/v1/catalog/items/:id	JWT (admin)	Update catalog item
DELETE	/api/v1/catalog/items/:id	JWT (admin)	Delete catalog item
GET	/api/v1/catalog/unit-types	JWT	List unit types
POST	/api/v1/catalog/unit-types	JWT (admin)	Create unit type
PATCH	/api/v1/catalog/unit-types/:id	JWT (admin)	Update unit type
DELETE	/api/v1/catalog/unit-types/:id	JWT (admin)	Delete unit type

Activities

Method	Path	Auth	Description
GET	/api/v1/activities	JWT	List activities (filterable by lead/customer)
GET	/api/v1/activities/recent	JWT	Recent activity feed
POST	/api/v1/activities	JWT (admin/member)	Create activity/note

Dashboard

Method	Path	Auth	Description
GET	/api/v1/dashboard/stats	JWT	Dashboard aggregations
GET	/api/v1/dashboard/attention	JWT	Needs-attention items

Tenant

Method	Path	Auth	Description
GET	/api/v1/tenant	JWT	Tenant config
PATCH	/api/v1/tenant	JWT (admin)	Update tenant config
GET	/api/v1/tenant/config	JWT	Tenant config_json settings

Assets — Intake

Method	Path	Auth	Description
POST	/api/v1/assets/intake/upload	JWT (admin/member/contractor)	Upload an intake or inspection file to R2. Accepts multipart/form-data with fields: file (image, max 10MB), entityId (lead or customer ID), action (e.g. inspection, intake). Returns { url, id } where url is the R2 key.
GET	/api/v1/assets/intake/download?key=...	JWT (admin/member/contractor)	Download a file from R2 by its storage key. Returns the file with appropriate Content-Type.

R2 key format: intake-photos/{entityId}/{action}/{YYYY-MM-DD}/{filename}

Defaults to unlinked if no entityId is provided and general if no action is provided.

Other

Method	Path	Auth	Description
GET	/api/v1/search	JWT	Cross-entity search
POST	/api/v1/geocode	JWT (admin/member)	On-demand Nominatim geocoding
GET	/api/v1/preferences	JWT	User preferences
PUT	/api/v1/preferences/:key	JWT	Set preference
POST	/api/v1/webhooks/intake	Signature	Intake form submission webhook
GET	/api/v1/health	None	Health check
POST	/api/v1/communications/call	JWT (admin/member)	Log outbound call
POST	/api/v1/communications/sms	JWT (admin/member)	Log outbound SMS

Inspection Drafts

Method	Path	Auth	Description
POST	/api/v1/inspections/draft	JWT (contractor)	Save inspection draft
GET	/api/v1/inspections/draft	JWT (contractor)	Get inspection draft

Admin (admin-only)

Method	Path	Description
POST	/api/v1/admin/generate-leads	Generate fake leads via intake pipeline
POST	/api/v1/admin/generate-customers	Generate fake customers (leads → convert)
POST	/api/v1/admin/leads/soft-delete	Soft-delete all leads
POST	/api/v1/admin/leads/hard-delete	Hard-delete all leads
POST	/api/v1/admin/customers/soft-delete	Soft-delete all customers
POST	/api/v1/admin/customers/hard-delete	Hard-delete all customers
GET	/api/v1/admin/system-info	DB size, record counts
GET	/api/v1/admin/registration-status	Registration toggle state
POST	/api/v1/admin/create-account	Create user account
GET	/api/v1/admin/users	List tenant users
POST	/api/v1/admin/reset-password	Reset user password
POST	/api/v1/admin/toggle-force-password-change	Toggle force-password-change flag

See the Schemas reference for request/response field details.