REST API Reference

All API endpoints exposed by Gumm. Every endpoint except /api/setup/status and /api/health requires an authenticated session.

Authentication

All API calls require a session cookie obtained from the login endpoint.

`POST /api/auth/login`

// Request
{ "password": "your-admin-password" }

// Response — 200 OK + sets session cookie
{ "ok": true }

`POST /api/auth/logout`

Invalidates the current session.

// Response
{ "ok": true }

`PUT /api/auth/password`

Change the admin password. Requires the current password.

// Request
{
  "currentPassword": "old-password",
  "newPassword": "new-strong-password"
}

// Response
{ "ok": true }

Setup

`GET /api/setup/status`

Check whether setup has been completed. No authentication required.

// Response
{ "needsSetup": true }

`POST /api/setup/complete`

Complete the first-launch wizard. Only works once.

// Request
{
  "password": "admin-password",
  "identity": {
    "name": "Gumm",
    "personality": "A concise, modular assistant.",
    "rules": "Be brief.",
    "goals": "Help users."
  },
  "openrouterApiKey": "sk-or-...",
  "telegram": {
    "botToken": "123456:ABC...",
    "webhookUrl": "https://gumm.example.com",
    "allowedChatIds": "12345678"
  }
}

// Response
{ "ok": true }

Chat

`POST /api/chat`

Send a message and get an AI response.

// Request
{
  "messages": [{ "role": "user", "content": "Hello!" }],
  "conversationId": "optional-uuid"
}

// Response
{
  "content": "Hello! How can I help?",
  "conversationId": "conversation-uuid"
}

If conversationId is omitted, a new conversation is created automatically.

Conversations

`GET /api/conversations`

List all conversations.

// Response
[
  {
    "id": "uuid",
    "title": "Hello!",
    "createdAt": 1709500000000,
    "updatedAt": 1709500000000
  }
]

`GET /api/conversations/:id`

Get a conversation with all its messages.

`DELETE /api/conversations/:id`

Delete a conversation and all its messages.

Brain

`GET /api/brain/config`

Get all brain configuration entries.

`PUT /api/brain/config`

Update one or more configuration entries.

// Request
{
  "entries": [
    { "key": "identity.name", "value": "Atlas" },
    { "key": "brain.language", "value": "en" }
  ]
}

`GET /api/brain/stats`

Get aggregated statistics (conversations, messages, modules, memory, knowledge).

`GET /api/brain/memory`

List memory entries. Optional query params: namespace, type, limit.

`DELETE /api/brain/memory/:id`

Delete a memory entry.

Modules

`GET /api/modules`

List all installed modules with their status.

`POST /api/modules/install`

Install a module from GitHub.

// Request
{
  "repo": "owner/repo",
  "ref": "main"
}

`PUT /api/modules/:id/toggle`

Enable or disable a module.

// Request
{ "enabled": true }

`DELETE /api/modules/:id`

Uninstall a module.

Schedules

`GET /api/schedules`

List all registered schedule tasks.

`PUT /api/schedules/:id/toggle`

Enable or disable a schedule.

Storage

`GET /api/storage`

List stored files.

`POST /api/storage/upload`

Upload a file.

`GET /api/storage/:key`

Download a file.

`DELETE /api/storage/:key`

Delete a file.

Health

`GET /api/health`

Health check endpoint. Returns 200 when the server is running. No authentication required.

{ "status": "ok" }

Notes

All endpoints return JSON
Error responses use standard HTTP status codes: 400 (bad request), 401 (unauthenticated), 403 (forbidden), 404 (not found), 429 (rate limited), 500 (server error)
Rate limits: 30 requests/minute on /api/chat, 10 requests/5 minutes on auth endpoints