HeadyAPI
Unified AI Gateway
API v1.0 · All Endpoints Operational

HeadyAPI

Unified AI Gateway REST API

FLOWER OF LIFE · SACRED GEOMETRY v3

One API endpoint, every AI provider. HeadyAPI gives you multi-provider inference, liquid gateway routing, semantic caching, and budget-aware orchestration — all through a single REST interface. Ship AI features in minutes, not months.

⚡ API Endpoints

Complete REST API for the 77-service Heady ecosystem

POST
/api/brain/chat
Send a message to HeadyBrain. Auto-routes through the Liquid Gateway to the fastest available intelligence engine with automatic failover.
POST
/api/brain/analyze
Analyze code, text, or data for patterns, bugs, security issues, and optimization opportunities. Supports code, text, security, and performance analysis types.
POST
/api/brain/embed
Generate text embeddings using state-of-the-art models. Powers semantic search, similarity matching, and 3D vector memory across the ecosystem.
POST
/api/brain/search
Search the Heady knowledge base across all indexed documentation, code, and knowledge items. Returns ranked results with relevance scoring.
POST
/api/gateway/race
Race a prompt across all providers simultaneously. Returns the fastest valid response with full latency, cost, and provider metadata.
POST
/api/gateway/decompose
Split complex tasks across multiple AI providers. Each subtask runs in parallel, results are merged and quality-scored automatically.
GET
/api/gateway/stats
Real-time gateway statistics: provider health, cache hit rates, budget usage, request counts, and average latency per provider.
GET
/api/registry/components
List all 77 registered services across 14 groups. Returns service metadata including status, criticality, layer, version, and health checks.
POST
/api/battle/validate
Run AI-vs-AI validation on code changes. Multiple AI models review the same change independently and vote on quality, security, and correctness.

🧪 Live Playground

Try the API right here — no signup required

Request
// POST /api/brain/chat
{
  "message": "What is the Heady ecosystem?",
  "model": "heady-brain",
  "max_tokens": 1024,
  "temperature": 0.7
}
ResponseReady
// Click "Run" to see the response
// The API routes through the Liquid Gateway
// to the fastest available provider.

🔐 Enterprise-Grade Security

Built with Heady-style security at every layer

🔑

API Key Auth

Bearer token authentication with scoped permissions, rate limiting, and automatic key rotation.

🔒

mTLS Mesh

Internal service-to-service communication secured with mutual TLS and automatic certificate management.

🛡️

Circuit Breakers

Automatic provider failover with health monitoring, circuit breakers, and graceful degradation.

💰

Budget Guards

Real-time cost tracking with daily/monthly budget caps. Never exceed your AI spend limits.

🔄

Secret Rotation

Automated 7-key rotation with audit trails. Secrets are never hardcoded or exposed.

🏥

Auto-Heal

Self-healing infrastructure that detects failures and automatically recovers without human intervention.

📦 Official SDKs

📜
JavaScript / Node.js
npm install heady-hive-sdk
🐍
Python
pip install heady-sdk
🦀
CLI
npx heady "ask anything"