API reference

REST endpoints on the same origin as the site. All requests and responses are JSON unless noted.

Base URL & proxying

https://kinetic-4g1.pages.dev/api/...

Cloudflare Pages Functions (/functions/_middleware.js) proxy /api/* to the EC2 backend with the same origin — no CORS configuration is needed for browser apps served alongside it.

Authentication methods

Core endpoint groups

Unified inbox (highlights)

GET  /api/inbox/unified?vertical=cx|lg|bd&channel=&status=all|needs_you|in_progress|resolved
GET  /api/inbox/unified/:vertical/:id/messages
POST /api/inbox/unified/:vertical/:id/reply   { "message": "..." }

# Legacy per-participant endpoints remain available:
GET  /api/inbox
GET  /api/inbox/:participantId/messages
POST /api/inbox/:participantId/reply          { "message": "...", "channel": "whatsapp" }

The unified reply endpoint routes automatically: a CX reply goes out on the customer's channel; an LG reply uses the lead's active WhatsApp; a BD reply uses the partner's WhatsApp. A thread without a sendable channel returns 400 with an explanatory error — the API never fakes a send.

Copilot message

POST /api/portal/copilot/message
{ "message": "Find plumbers in Lusaka", "sessionId": null }   // sessionId: null starts a new session

B2C commerce endpoints (tenant-scoped)

Developer Copilot API (senses)

A machine-facing, scoped surface at /api/copilot for the Developer Copilot. Every route requires the copilot key (see authentication); if COPILOT_API_KEYS is unset the entire surface is disabled and every request is rejected with 503.

GET  /api/copilot/health-check        # orchestrator + MCP + Redis pings with response times
GET  /api/copilot/cost-intelligence   # same logic as GET /api/developer/cost-intelligence
GET  /api/copilot/infrastructure      # container/service infrastructure view
GET  /api/copilot/mesh-health         # harness mesh health
GET  /api/copilot/status              # persisted copilot heartbeat document
POST /api/copilot/alerts              # Alertmanager ingestion: {"alerts":[...]} or a single alert object
POST /api/copilot/remediate           # gated self-heal scaffold (see below)

• Alerts: accepts either the Alertmanager envelope or a single alert object. Only alerts actually received are stored, each stamped with receivedAt. An empty payload returns 400.
• Remediation: exactly one action is supported — {"action":"restart-container","container":"<name>"}. It runs only when COPILOT_HEAL_ENABLED=true, only for containers on the COPILOT_HEAL_ALLOWED_CONTAINERS allowlist, and always reports what it did afterwards.

Admin control plane APIs

The admin control plane exposes tenant lifecycle and platform health via /api/admin (admin session cookie) and the developer-side control-plane views under /api/developer (developer key): tenant list and detail, incidents, activity, usage summaries, pricing, and ingestion/profiling statistics.

Backup & restore

• Nightly encrypted backups run from scripts/backup/nightly-backup.sh inside the backup Compose stack (docker-compose.backup.yml).
• Restore drills are scripted and repeatable: scripts/backup/restore-drill.sh. Run them on a schedule — a backup you have never restored is a hypothesis.
• Activation, scheduling, and capacity reporting live in scripts/backup/; operational procedure is in docs/runbooks/disaster-recovery.md.

Units consumption

• AI-consuming endpoints deduct units from the calling tenant's wallet atomically per request.
• Consumption events are recorded with model, tokens, and cost for the tenant's usage views.
• A wallet at zero returns an explicit insufficient-units error; no partial work is billed.
• BYOK tenants draw against their own provider keys instead of platform units.

Error semantics