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://api.mymellow.xyz).

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,
  "restartCount": 7,
  "firstStartedAt": "2026-08-01T10:00:00Z",
  "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.

uptimeSeconds counts from the current process start. restartCount is a lifetime total that is stored in the database, so it survives restarts and deploys; firstStartedAt is when the bot first ran.

`GET /v1/commands`

Every public slash command with the permissions and cooldowns that apply. Staff commands are not listed. Unauthenticated, cached for 5 minutes, and callable from any origin. Used by the website's commands page.

200 OK
{
  "commands": [
    {
      "name": "safetyplan",
      "description": "Build a personal plan for hard moments. Only you can see it.",
      "category": "Crisis",
      "guildOnly": false,
      "cooldownSeconds": 5,
      "permissions": [],
      "options": [ { "name": "view", "type": 1, "description": "Show your safety plan." } ]
    }
  ]
}

permissions lists what Discord requires (for example Manage Server). plusCooldownSeconds is present when Mellow+ gets a shorter cooldown. options follows Discord's option format.

`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.

Dashboard endpoints

These power the

dashboard

The Mellow Dashboard

Manage your preferences, Mellow+ status, data, and servers from the web.

. They act on the signed-in user's own data, so they use a session cookie rather than the bearer token, and they are not meant for third-party integrations. They exist only when DISCORD_CLIENT_SECRET is set.

Signing in. GET /v1/auth/login redirects to Discord's OAuth2 page (scopes identify and guilds). Discord returns to GET /v1/auth/callback, which sets an HTTP-only mellow_session cookie (14 days) and redirects to DASHBOARD_URL. The Discord access token is used once and not stored.

Cross-origin rules. Requests with a session cookie are only accepted from the origins in WEBSITE_URL and ALLOWED_ORIGINS. State-changing requests (POST, PUT, PATCH) from any other origin are rejected with 403.

Endpoint	Description
`GET /v1/me`	Your ID, name, avatar, and Mellow+ status (`active`, `endsAt`, `renews`, `storeUrl`).
`GET /v1/me/preferences`	Your preferences, plus the lists the form needs (`personalities`, `plusPersonalities`, `countries`) and whether you have Mellow+.
`PATCH /v1/me/preferences`	Change any subset of your preferences. Plus-only fields return `403` without Mellow+.
`GET /v1/me/safety-plan`	Your safety plan.
`PUT /v1/me/safety-plan`	Replace your safety plan (six sections, 2000 characters each).
`GET /v1/me/mood?days=30`	Your check-ins for the period. `days` up to 30 is free; 31 to 365 needs Mellow+.
`GET /v1/me/export`	Everything stored about you, as a JSON download.
`POST /v1/me/delete`	Permanently erase your data. Body: `{ "confirm": "DELETE" }`. Ends your session.
`GET /v1/me/guilds`	Servers you manage (Manage Server or Administrator) where Mellow is installed.
`GET /v1/guilds/{id}`	Settings, channels, and roles for a server you manage.
`PATCH /v1/guilds/{id}`	Change server settings. An empty string clears a channel or role.
`POST /v1/auth/logout`	End your session.

Access to a server is checked on every request against the servers the signed-in user can manage, and channels and roles are validated against the server, so a request cannot point Mellow at another server's channel.

Errors

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

API Reference