API Reference

HeadyMe — Your Sovereign AI

📖 Documentation ⚡ API Reference 🔌 MCP Protocol

REST Endpoints

POST /api/chat

Send a message to HeadyBuddy with multi-provider routing. Supports streaming via SSE.

POST /api/embed

Generate embeddings using Nomic, Jina, Cohere, or Voyage with automatic model selection.

POST /api/search

Hybrid BM25 + vector similarity search across your knowledge base with RRF fusion.

GET /api/health

System health check returning provider status, latency metrics, and active connections.

GET /api/providers

List all available AI providers with current status, rate limits, and capabilities.

POST /api/signup

Create a new account with email/password or connect via OAuth/API key providers.

POST /api/login

Authenticate and receive a session token. Supports email, OAuth, and API key auth.

WebSocket Streams

ws://host/stream

Real-time bidirectional channel for chat, events, and buddy interactions.

ws://host/events

Server-sent events for system health, bee swarm status, and deployment notifications.

Authentication

API Key Header

Include your key as Authorization: Bearer HY-xxx in all requests.

Session Cookies

Browser-based auth via heady_session cookie, set automatically on sign-in.

OAuth Tokens

Exchange OAuth codes from 12 providers for Heady session tokens.