Brain REST API

HTTP endpoints exposed by the Brain service for chat, memory, and system management.

Brain REST API

The Brain service exposes a REST API for managing conversations, memory, jobs, and system status. All endpoints are served on port 3000 by default and require JWT authentication unless noted otherwise.

Authentication

Include a Bearer token in the Authorization header:

Authorization: Bearer <jwt-token>

Tokens are issued by the Brain's /auth/login endpoint or configured statically via the JWT_SECRET environment variable.

Chat Endpoints

POST /api/chat

Send a message and receive a streaming response via Server-Sent Events.

// Request
POST /api/chat
Content-Type: application/json

{
  "message": "What do you know about my Kubernetes setup?",
  "conversationId": "conv_abc123"  // optional, creates new if omitted
}

// Response (SSE stream)
data: {"type": "token", "content": "Based on"}
data: {"type": "token", "content": " what I remember"}
data: {"type": "tool_call", "name": "memory_search", "input": {...}}
data: {"type": "tool_result", "content": "..."}
data: {"type": "token", "content": "..."}
data: {"type": "done", "conversationId": "conv_abc123"}

The response streams tokens as they arrive from Claude. Tool calls and their results are included in the stream so the client can display them in real time.

GET /api/conversations

List all conversations with metadata.

// Response
{
  "conversations": [
    {
      "id": "conv_abc123",
      "title": "Kubernetes setup discussion",
      "lastMessage": "2025-03-15T10:30:00Z",
      "messageCount": 24
    }
  ]
}

GET /api/conversations/:id

Get full conversation history including all messages and tool calls.

Memory Endpoints

POST /api/memory/search

Search vector memory by semantic similarity.

// Request
POST /api/memory/search
Content-Type: application/json

{
  "query": "Kubernetes cluster configuration",
  "category": "fact",    // optional filter
  "limit": 10            // default 10
}

// Response
{
  "memories": [
    {
      "id": "mem_xyz789",
      "content": "User runs a k3s cluster on 3 Raspberry Pi 4 nodes",
      "category": "fact",
      "similarity": 0.87,
      "createdAt": "2025-02-20T14:00:00Z"
    }
  ]
}

POST /api/memory

Store a new memory.

// Request
POST /api/memory
Content-Type: application/json

{
  "content": "User prefers Helm charts over raw manifests",
  "category": "preference"
}

DELETE /api/memory/:id

Delete a specific memory by ID.

Job Endpoints

GET /api/jobs

List recent jobs with status.

GET /api/jobs/:id

Get job details including status history and output.

System Endpoints

GET /api/health

Health check endpoint. Returns 200 when the Brain is ready to accept requests. Does not require authentication.

// Response
{
  "status": "healthy",
  "nats": "connected",
  "qdrant": "connected",
  "uptime": 86400
}

GET /api/extensions

List currently registered MCP extensions and their tools.

// Response
{
  "extensions": [
    {
      "name": "weather",
      "version": "1.0.0",
      "tools": ["get_weather", "get_forecast"],
      "status": "connected"
    }
  ]
}

GET /api/status

System status including active conversations, running jobs, and connected workers. Includes the X-Trace-Id header for distributed tracing correlation.