# API Reference

Date: 2026-06-16

This document describes the API-style routes that are active in the current runtime. It does not advertise the planned public REST API as live.

## Active API-Style Routes

Active API-style routes are split into two groups:

- JSON endpoints for machine clients.
- Signed form endpoints used by FieldOps web/customer-portal forms.

Active JSON responses use:

- Success: `{ "success": true, "data": {}, "meta": {} }`
- Error: `{ "success": false, "error": { "code": "...", "message": "...", "fields": {} } }`

Unknown or forbidden `/api/*` routes return the same JSON error envelope at the application boundary.

### JSON Endpoints

| Method | Route | Purpose | Auth / access |
| --- | --- | --- | --- |
| `POST` | `/ai-assistant/generate` | Returns deterministic local assistant guidance. No external LLM is called and no operational records are changed. | Logged-in user with `use_ai_assistant`; CSRF required. |
| `POST` | `/api/offline-sync` | Technician offline sync endpoint for queued field actions. | Logged-in tenant user with offline workflow access. |
| `POST` | `/api/billing/stripe/webhook` | Signed Stripe-style billing webhook intake. Returns JSON but stays disabled until provider secrets and price mappings are configured. | Provider signature; no tenant login required. |

### Signed Form Endpoints

These routes live under `/api/*` so they bypass normal web-form CSRF, but they are not a public REST API. They require a signed customer portal token and respond with redirects or portal HTML validation errors because they back browser forms.

| Method | Route | Purpose | Auth / access |
| --- | --- | --- | --- |
| `POST` | `/api/portal/quote` | Customer portal quote approve/decline action for a signed portal token. | Signed portal token; no tenant login required. |
| `POST` | `/api/portal/invoice-payment` | Customer portal sandbox invoice-payment recording for a signed portal token. This is not a live payment gateway. | Signed portal token; no tenant login required. |
| `POST` | `/api/portal/booking-request` | Customer portal booking request for a signed portal token. | Signed portal token; no tenant login required. |

## Active Web Routes For Integration Settings

| Method | Route | Purpose | Permission |
| --- | --- | --- | --- |
| `GET` | `/settings/accounting` | Renders accounting integration settings for Xero, QuickBooks Online, Sage Accounting, Zoho Books, MYOB, FreeAgent, Reckon, SMEPlus, FreshBooks, and Wave Accounting provider metadata. | `view_accounting_integrations` |
| `GET` | `/settings/calendar` | Renders Google Calendar and Outlook/Microsoft 365 calendar settings foundation. | `view_calendar_integrations` |
| `GET` | `/settings/llm` | Renders LLM API settings foundation. | `view_llm_settings` |
| `GET` | `/import-data` | Renders selected import workflow. Supported query parameter: `type=customers|jobs|quotes|invoices|team`. | `import_csv` |
| `GET` | `/import-data/sample` | Downloads a sample CSV for the selected import type. | `import_csv` |
| `POST` | `/import-data/preview` | Validates CSV input before import. | `import_csv`; CSRF required. |
| `POST` | `/import-data/commit` | Commits the most recent valid import preview. | `import_csv`; CSRF required. |
| `POST` | `/import-data/undo` | Undoes the most recent committed import when still available. | `import_csv`; CSRF required. |

## Explicitly Planned, Not Live

The general public REST API below is planned only. These routes are not currently registered in `public/index.php`, must not be marketed as available, and require token auth, RBAC, tenant isolation, rate limiting, audit logging, and tests before release:

- `POST /api/auth/token`
- `POST /api/auth/revoke`
- `GET|POST /api/clients`, `GET|PATCH|DELETE /api/clients/{id}`
- `GET|POST /api/jobs`, `GET|PATCH|DELETE /api/jobs/{id}`
- `GET|POST /api/quotes`, `GET|PATCH|DELETE /api/quotes/{id}`
- `GET|POST /api/invoices`, `GET|PATCH|DELETE /api/invoices/{id}`
- `GET /api/dashboard`
- `GET /api/reports/summary`
- `GET /api/team`

Live OAuth callbacks, non-billing provider webhooks, and sync worker endpoints are also deferred until provider credentials, redirect URLs, encryption keys, HTTPS callback URLs, and sandbox tenants are confirmed.