Talk to Maylyn over HTTP

Reference for the HTTP API exposed by maylyn serve (and maylyn hub, which mounts the same routes with inference off). The route table is registered in NewServeMux in backend/serve.go and is the source of truth; if this page and that file disagree, the code wins.

Version this page was checked against: v0.44.1.

Contents

• Quick start
• Conventions
• Authentication
• Streaming chat
• Endpoint reference
• Limits and hardening

Quick start

MAYLYN_SERVE_TOKEN=$(openssl rand -hex 32) maylyn serve
# maylyn serve listening on 127.0.0.1:8787

curl http://127.0.0.1:8787/health

curl -N http://127.0.0.1:8787/ask/stream \
  -H "Authorization: Bearer $MAYLYN_SERVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "say hello in one short sentence", "tools": false}'

If MAYLYN_SERVE_TOKEN is unset, a random token is generated and printed on startup.

MAYLYN_SERVE_ALLOW_TOOLS=true means a POST body can run a shell as the user that owns the process. Do not combine it with a non-loopback address unless that is exactly what you intend.

Conventions

• Base URL: http://127.0.0.1:8787 unless MAYLYN_SERVE_ADDR says otherwise.
• Bodies: JSON (Content-Type: application/json) unless noted. Request bodies are capped at 4 MiB; an invalid or oversized body returns 400.
• Errors: standard HTTP status (400, 401, 403, 404, 429, 5xx). Most handlers answer with a plain-text body; the rate and concurrency limiters answer 429 with {"error": "..."} and a Retry-After header. A missing or bad credential returns 401 with unauthorized: log in, or send Authorization: Bearer <token>.
• Path parameters are written {like_this}.
• Per-person scoping: with a Kratos session, conversations, artifacts, memories and agents resolve to that person's own store. The static token resolves to the machine's shared store.
• Client hint: the optional X-Maylyn-Client header (desktop or webapp) tells the server which shell is calling and may change how a turn is shaped.

Authentication

Every route is in one of these classes. The tables below label each route with the class that applies.

Details:

• The static token is compared in constant time over SHA-256 digests.
• A verified Kratos session wins over the static token and scopes the request to that person's store. Banned profiles get 403.
• With Kratos active, unverified accounts get 403 unless they are the machine owner.
• The webhook route POST /automation/webhook/{id} is Bearer-authenticated and additionally reads an X-Maylyn-Webhook-Token header.

Streaming chat

Two routes run the agent loop and answer as Server-Sent Events (Content-Type: text/event-stream).

POST /ask/stream

One-shot prompt. Bearer.

{ "prompt": "what changed in the repo?", "agent": "maylyn", "tools": true }

POST /chat/stream

Multi-message chat. Bearer.

{
  "messages": [{ "role": "user", "content": "hello" }],
  "agent": "maylyn",
  "tools": true
}

The full struct is chatStreamRequest in backend/serve.go.

Stream events

Event payloads are JSON. Names that the server emits include:

Other chat routes

Endpoint reference

Routes are grouped by area. "Bearer" includes verified Kratos sessions.

Health and downloads

Web UI shell (only when the web app is enabled)

All Public: GET / (shell), /styles.css, /app.js, /bootstrap.js, /thinking_phrases.json, /manifest.webmanifest, /sw.js, /favicon.ico, /icon-192.png, /icon-512.png, /icon-192-maskable.png, /icon-512-maskable.png, /apple-touch-icon.png, /mascot.png, and the prefixes /voice/canned/, /controllers/, /vendor/, /icons/achievements/, /icons/weather/. When the web app is off these return 404.

Sign-in and accounts

Agents, models and setup

Skills and library

Conversations, shares and attachments

Knowledge bases and projects

Files and artifacts

Studio, canvas and sound

Voice

Browser automation

Automations

Packs and mesh

Authority layer

See architecture/AUTHORITY_LAYER.md.

Achievements

Image backend (embedded canvas server)

When Maylyn Canvas runs in-process it also answers on its own listener with GET /health, POST /generate, POST /edit, POST /upscale, and the OpenAI-shaped POST /v1/images/generations, /v1/images/edits and /v1/images/upscale. These are served by the image backend, not by the main maylyn serve listener. See backend/canvas_embedded.go.

Profiling (opt-in)

Setting MAYLYN_PPROF=6060 (or 127.0.0.1:6060) starts a separate profiling listener serving /debug/pprof/* and /debug/goroutines. It refuses to bind anywhere but loopback and is not part of the main maylyn serve listener. See backend/pprof.go.

Limits and hardening

• Loopback-only bind by default; widening it is a deliberate act.
• Conservative header, read and idle timeouts; bounded header size.
• Per-IP rate limiting with burst control; 429 with Retry-After: 1 when exceeded.
• Stream concurrency limit returns 429 with Retry-After: 5.
• Concurrency caps and time budgets on /ask/stream and /chat/stream.
• Baseline security headers and panic containment on every response.
• Tools that require approval are refused over HTTP unless MAYLYN_SERVE_ALLOW_TOOLS is set; read-only tools always work.

Design background: architecture/SECURITY_INVARIANTS.md.