LIGHTWELL
lightwell-labs.com
API Reference

API Reference

The Lightwell platform exposes its application surface as REST endpoints under /api. This reference covers the conventions, the core resources, and the integration patterns used across the system.

Conventions

REST over JSON

All endpoints live under /api and exchange JSON. Requests use standard methods: GET for reads, POST for creation and actions. Responses return JSON with consistent error envelopes.

Session-based auth

User-scoped endpoints authenticate via the platform session (NextAuth). Unauthenticated calls to protected resources receive 401; unauthorized access to another user’s resources receives 403.

Typed persistence

State is persisted through Prisma with schema-enforced types. Client payloads are validated with Zod before they reach the database — malformed input fails fast with 400 and a field-level reason.

Fail closed on safety

Safety-critical endpoints (crisis detection, therapeutic interventions) fail closed: when a check cannot be completed, the conservative path is taken and the request is escalated, never silently dropped.

Request & response shape

example — POST /api/contact
// Request
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "message": "Hello Lightwell"
}

// 200 OK
{
  "ok": true
}

// 400 Bad Request — validation failure
{
  "ok": false,
  "error": "Validation failed",
  "fields": { "email": "Invalid email address" }
}

Successful mutations return 200 with a JSON body. Validation failures return 400 with field-level detail. Authentication failures return 401. Server faults return 500 with a safe, non-leaking message.

Core endpoints

Conversation & Memory

POST/api/chatSend a message to the assistant and receive a streamed response.
GET/POST/api/memoryRead and write long-term memory entries for the session user.
POST/api/voice-agent/processProcess a voice-agent turn with structured intake output.

Journal & Progress

GET/POST/api/journalList or create journal entries for the authenticated user.
GET/PATCH/DELETE/api/journal/[id]Read, update, or delete a single journal entry.
POST/api/save-moodRecord a mood datapoint.
GET/POST/api/progress/assessmentFetch or submit assessment progress.

Safety & Wellbeing

POST/api/crisis/detectRun crisis-risk detection over user input. Fail-closed.
POST/api/therapeutic/crisis-assessmentStructured crisis assessment with escalation routing.
POST/api/therapeutic/generate-interventionGenerate a therapeutic intervention for a session.

Platform & Ops

POST/api/contactSubmit a contact request.
POST/api/feedbackSubmit product feedback.
POST/api/track-eventRecord a client analytics event.
POST/api/billing/create-checkout-sessionCreate a Stripe checkout session for upgrades.

Rate limits & reliability

Client analytics and tracking endpoints are fire-and-forget: they never block the UI and degrade silently when unreachable.

Streaming endpoints (chat, voice) use incremental delivery over the response stream; consumers should handle partial chunks and termination frames.

All state-changing endpoints are idempotent-safe at the schema level: repeated submissions of the same logical action are deduplicated or safely upserted where the domain allows.