Mellow HTTP API

Mellow's self-hosted binary serves a small HTTP API on PORT (default 9420). It is intended for the Mellow website and simple integrations, not as a general-purpose platform.

The canonical, always-current schema is served by the running bot:

GET /openapi.json - the OpenAPI document
GET /docs - an interactive Scalar reference

The base URL is wherever you host the bot (for the official instance, behind https://mellow.codemeapixel.dev).

Authentication

GET /healthz, GET /v1/stats, and GET /v1/testimonials are unauthenticated.
POST /v1/chat and POST /v1/feedback require a bearer token:
```
Authorization: Bearer <API_TOKEN>
```
API_TOKEN is set in the bot's environment. Requests without it get 401.

Rate limits

Scope	Limit
All endpoints	60 requests / minute / IP
`POST /v1/chat`	20 requests / minute
`POST /v1/feedback`	5 requests / minute

Endpoints

`GET /healthz`

Health check.

200 OK
{ "status": "ok" }

`GET /v1/stats`

Aggregate community counts.

200 OK
{
  "users": 1234,
  "guilds": 56,
  "conversations": 7890,
  "moodCheckIns": 4321,
  "crisisEvents": 12
}

`GET /v1/status`

Live bot and per-shard status. Used by the website's status page.

200 OK
{
  "status": "ok",
  "version": "v2.0.0",
  "startedAt": "2026-09-10T09:00:00Z",
  "uptimeSeconds": 12345,
  "shardCount": 2,
  "guilds": 56,
  "generatedAt": "2026-09-10T12:25:45Z",
  "shards": [
    { "id": 0, "state": "ready", "latencyMs": 48, "guilds": 30, "lastReady": "2026-09-10T09:00:04Z", "resumes": 1 },
    { "id": 1, "state": "ready", "latencyMs": 51, "guilds": 26, "lastReady": "2026-09-10T09:00:05Z", "resumes": 0 }
  ]
}

status is ok, degraded (a shard is not ready), or starting.

`GET /v1/testimonials`

Feedback that an owner has explicitly approved and marked public. Wording is the user's own.

200 OK
[
  { "message": "Mellow helped me get through a rough night.", "createdAt": "2026-01-04T22:10:00Z", "featured": true }
]

`POST /v1/chat`

One-shot supportive chat completion. Requires the bearer token.

// request
{ "message": "I'm feeling really anxious tonight" }

// 200 OK
{ "reply": "That sounds heavy. ..." }

Errors: 400 (missing message), 401 (bad token), 503 (AI not configured), 502 (AI request failed).

`POST /v1/feedback`

Submit feedback. Requires the bearer token.

// request
{ "userId": "123456789012345678", "message": "The grounding exercise is great" }

// 202 Accepted
{ "status": "received" }

userId must be a valid Discord user ID and message at least 3 characters, otherwise 400. Submitted feedback enters the queue reviewed with /feedback-manage; it is not public unless an owner approves it.

Errors

All errors are JSON: { "error": "<message>" } with the matching HTTP status.

API Reference