API Reference

API Reference

Mingly exposes a REST and WebSocket API when running in Server mode. The server listens on port 3939 by default.

Authentication

When requireAuth is enabled, all requests must include:

Authorization: Bearer YOUR_API_KEY

Unauthenticated requests receive 401 Unauthorized.

REST Endpoints

Health Check

GET /health

Returns server health status, provider availability, uptime, and version.

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 3600,
  "providers": {
    "anthropic": true,
    "openai": false,
    "google": true,
    "local": true
  }
}

Server Info

GET /info

Returns server name, available providers, models, and active session count.

List Providers

GET /providers

Returns available LLM providers and their models.

Response:

[
  {
    "id": "anthropic",
    "name": "Anthropic",
    "models": ["claude-sonnet-4-5-20250514", "claude-4-opus-20250514"],
    "configured": true
  }
]

Chat (Non-Streaming)

POST /chat
Content-Type: application/json

Request Body:

{
  "message": "Hello, how are you?",
  "provider": "anthropic",
  "model": "claude-sonnet-4-5-20250514",
  "conversationId": "optional-existing-id"
}

Response:

{
  "response": "I'm doing well! How can I help you?",
  "conversationId": "conv-123",
  "metadata": {
    "tokensUsed": 42,
    "cost": 0.00012,
    "latencyMs": 850,
    "provider": "anthropic",
    "model": "claude-sonnet-4-5-20250514"
  }
}

Chat (Streaming)

POST /chat/stream
Content-Type: application/json
Accept: text/event-stream

Same request body as /chat. Returns Server-Sent Events (SSE):

data: {"type":"token","content":"Hello"}
data: {"type":"token","content":" there!"}
data: {"type":"done","metadata":{"tokensUsed":10,"cost":0.00003}}

List Conversations

GET /conversations

Returns all conversations with metadata (title, provider, model, timestamps).

Create Conversation

POST /conversations
Content-Type: application/json

Request Body:

{
  "title": "New Chat",
  "provider": "anthropic",
  "model": "claude-sonnet-4-5-20250514"
}

Get Conversation

GET /conversations/:id

Returns conversation details with full message history.

WebSocket API

Connect to ws://hostname:3939/ws

Authentication

Include the API key in the first message or as a query parameter:

ws://hostname:3939/ws?token=YOUR_API_KEY

Message Format

Send:

{
  "type": "chat",
  "message": "Hello!",
  "provider": "anthropic",
  "model": "claude-sonnet-4-5-20250514",
  "conversationId": "optional-id"
}

Receive (streaming):

{"type": "token", "content": "Hello"}
{"type": "token", "content": " there!"}
{"type": "done", "metadata": {"tokensUsed": 10}}

Session Limits

The server enforces a maximum number of concurrent WebSocket sessions (default: 50). Connections beyond the limit receive an error and are closed.

Error Responses

All errors follow a consistent format:

{
  "error": "Error description",
  "code": "ERROR_CODE"
}

Status	Meaning
400	Bad request (missing/invalid parameters)
401	Unauthorized (missing or invalid API key)
429	Rate limited (too many requests)
500	Internal server error

CORS

The server includes CORS headers on all responses. Configure allowed origins via the corsOrigins setting.

Rate Limiting

Requests are throttled per handler:

Operation	Limit
LLM calls	20/min
RAG operations	30-60/min
MCP tool execution	30/min
Global (all handlers)	500/min

---

Back to: Home | Related: Architecture | Deployment