API contracts

Health check

GET /api/v1/health

Returns application and database health. A healthy response is HTTP 200. Unconfigured or unhealthy database state returns a non-2xx response rather than pretending the service is ready.

{
  "status": "healthy",
  "timestamp": "2026-10-04T00:00:00.000Z",
  "version": "1.0.0",
  "database": "healthy"
}

Programmatic booking

POST /api/book
Authorization: Bearer <supabase-access-token>
Content-Type: application/json

This endpoint is not a raw scheduling-provider proxy. The request is authenticated, tenant access is checked, the acting booking agent is resolved server-side, and execution still passes through policy, idempotency, evidence, and provider verification boundaries.

{
  "tenantId": "<uuid>",
  "slotStart": "2026-10-12T14:00:00-04:00",
  "slotEnd": "2026-10-12T14:30:00-04:00",
  "patientName": "Test Patient",
  "patientEmail": "test@example.com",
  "timezone": "America/New_York"
}

Authenticated receptionist turn

POST /api/agent/receptionist
Content-Type: application/json

The receptionist route is tenant-aware and authenticated. Conversation state is durable, tool calls pass through the runtime and policy engine, and side effects are not authorized by model prose alone.

{
  "message": "I would like to book a consultation",
  "conversationId": "<optional-uuid>"
}

Error behavior

• 400 — malformed or incomplete input.
• 401 — missing or invalid authentication where authentication is required.
• 403 — tenant access or policy denial.
• 404 — required tenant-scoped resource is not present.
• 409 — integration configuration is incomplete or conflicts with the requested operation.
• 5xx — provider, database, or server failure. Do not assume the external side effect did or did not happen until reconciled.