# Osolix · Public API Surface Map — v1

**Status:** Wave-B Foundation evidence · 2026-Q2
**Owner:** Chief Architect
**Audit dimension:** #2 Integration-ready · #21 Documentation
**Re-attestation:** Per release

This document is the canonical catalogue of every public REST endpoint
the Osolix API exposes. It pairs with the live Swagger UI at
`/swagger/index.html`. Rate limits, authentication, and idempotency
contracts are documented per group.

## 1 · Authentication & identity

| Method | Path | Purpose |
|---|---|---|
| POST | `/api/auth/login` | Email + password → JWT (access + refresh). Brute-force lockout after 5 attempts. |
| POST | `/api/auth/refresh` | Refresh-token rotation. Returns new access + refresh pair. |
| POST | `/api/auth/logout` | Revokes the refresh token. |
| POST | `/api/auth/signup` | Self-service trial signup (email-verification flow). |
| POST | `/api/auth/verify-email` | Consume email-verification token. |
| GET | `/api/me` | Current user's profile. |
| PUT | `/api/me` | Update profile (name, phone, language, time zone). |
| POST | `/api/me/mfa/totp/enroll` | Begin TOTP enrolment; returns QR + recovery codes. |
| POST | `/api/me/mfa/totp/verify` | Complete TOTP enrolment. |
| POST | `/api/me/mfa/totp/disable` | Disable TOTP (re-auth required). |

## 2 · Privacy rights (GDPR / PDPL)

| Method | Path | Purpose |
|---|---|---|
| GET | `/api/me/export` | Portable JSON archive of the user's account. |
| POST | `/api/me/erase` | File a right-to-erasure request (30-day cool-off, then permanent purge). |
| GET | `/api/me/erase/status` | Current erasure-request status. |

## 3 · Platform Audit (public scorecard)

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/api/audit/overview` | Anonymous | Live audit pass % + dimensions + targets + scores + certificates. |
| POST | `/api/audit/score` | SystemOwner / OsolixStaff | Record a new score for (target, dimension). Append-only. |
| POST | `/api/audit/certificate` | SystemOwner / OsolixStaff | Issue a certificate when a target hits 25/25. |

## 4 · Asset Management

| Method | Path | Purpose |
|---|---|---|
| GET | `/api/assets` | List + filter + paginate. Smart-filter query params. |
| GET | `/api/assets/{id}` | Asset detail with financials, lifecycle, tags. |
| POST | `/api/assets` | Create asset (Wave-B audit fix: routes to AssetAdditions workflow). |
| PUT | `/api/assets/{id}` | Update asset; enforces field-level permissions (UserFarColumnAccess). |
| DELETE | `/api/assets/{id}` | Soft-delete (audit-trail preserved). |
| GET | `/api/assets/{id}/lifecycle` | Full lifecycle event timeline. |
| GET | `/api/assets/{id}/financials` | Cost / NBV / accum-dep / monthly-dep (gated by FinancialData column group). |
| POST | `/api/assets/import` | Bulk-import wizard (dry-run + transactional commit). |
| POST | `/api/assets/export` | Bulk-export (Excel / CSV / PDF). |
| GET | `/api/transfers` | Transfer requests. |
| POST | `/api/transfers` | Create transfer; routes through DoA matrix. |
| POST | `/api/transfers/{id}/approve` | Approve transfer step. |
| GET | `/api/retirements` | Retirement requests. |
| POST | `/api/retirements` | Create retirement (sale / scrap / donation / write-off / trade-in). |
| GET | `/api/verifications` | Verification cycles. |
| POST | `/api/verifications` | Start a new cycle. |
| POST | `/api/verifications/{id}/scan` | Mobile RFID/barcode scan event. |

## 5 · Other solutions

Full catalogue lives in Swagger UI; key controllers per solution:
* **Inventory** — `/api/inventory/parts`, `/api/inventory/stock`, `/api/inventory/reservations`, `/api/inventory/cycle-counts`.
* **Maintenance** — `/api/maintenance/work-orders`, `/api/maintenance/schedules`, `/api/maintenance/predictive`, `/api/maintenance/rca-fmea`.
* **Fleet** — `/api/fleet/vehicles`, `/api/fleet/drivers`, `/api/fleet/fuel`, `/api/fleet/compliance`.
* **Lease** — `/api/leases`, `/api/leases/{id}/amortisation`, `/api/leases/{id}/modifications`.
* **Asset Budget** — `/api/capex/requests`, `/api/capex/approvals`, `/api/capex/forecast`.
* **CWIP** — `/api/cwip/projects`, `/api/cwip/capitalise`, `/api/cwip/aging`.

## 6 · AI assistance (Atlas)

| Method | Path | Purpose |
|---|---|---|
| POST | `/api/ai/chat` | Send a question; returns deterministic offline answer (or Anthropic-polished if AiMode=Online). Supports `pageContext` + `history`. |
| GET | `/api/ai/agent-settings` | Per-tenant settings for the 14 AI agents. |
| PUT | `/api/ai/agent-settings/{agentId}` | Update agent system prompt + enabled flag. |
| GET | `/api/ai/governance` | AI agent latency / accuracy / reaction telemetry. |

## 7 · Integrations

| Method | Path | Purpose |
|---|---|---|
| GET | `/api/erp/connections` | Active ERP integration configurations. |
| POST | `/api/erp/connections` | Configure a new ERP connection (encrypted credentials). |
| GET | `/api/erp/outbox` | View the outbound queue. |
| POST | `/api/erp/outbox/{id}/retry` | Retry a failed outbound item (audit-logged for SOX ITGC-O2). |
| GET | `/api/integrations/webhooks` | Outbound webhook subscriptions. |
| POST | `/api/integrations/webhooks` | Create webhook (secret returned once). |
| POST | `/api/telemetry/ingest` | IoT ingest (HMAC-SHA256 signed). |

## 8 · Health & status

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/api/health` | Anonymous | Liveness + readiness probe. |
| GET | `/swagger/index.html` | Anonymous | Interactive API explorer. |

## 9 · Rate limits

* **Authenticated**: 600 requests / minute per user.
* **Anonymous**: 60 requests / minute per IP.
* **AI chat (`/api/ai/chat`)**: 30 requests / minute per user.
* **IoT ingest (`/api/telemetry/ingest`)**: 6,000 events / minute per token.

## 10 · Versioning + breaking-change policy

* `Accept: application/vnd.osolix.v1+json` is the implicit default.
* Breaking changes ship under v2 once contracted; both versions coexist for ≥ 6 months.
* Deprecated v1 endpoints emit `Deprecation:` and `Sunset:` headers.

## 11 · Open items
* Publish OpenAPI spec to `/openapi.yaml` for download (currently UI-only).
* Wire Stoplight Studio for partner-facing API portal.
* Add per-endpoint per-tenant rate-limit override + view.