Intelligence Routing Hub
HeadyAI is the central intelligence routing hub for the Heady™ platform — dynamically dispatching requests to the optimal AI provider using φ-scaled algorithms and adaptive pressure.
What We Offer
Powered by Heady™ Liquid Latent OS
Platform Overview
HeadyAI serves as the central intelligence routing hub for the Heady™ platform, dynamically dispatching AI requests to the optimal provider using φ-scaled algorithms and adaptive pressure routing.
Central Intelligence Hub
Single entry point that unifies 8+ AI providers under one API, intelligently routing every request for optimal performance.
φ-Scaled Algorithms
Golden-ratio-based scaling algorithms that dynamically balance load, latency, and cost across all connected providers.
Adaptive Pressure Routing
Real-time pressure signals from each provider inform routing decisions, ensuring requests always hit the fastest available endpoint.
Quick Start
Get up and running with HeadyAI in three simple steps. From API key to your first routed request in under five minutes.
1. Get Your API Key
Sign up at headyme.com to generate your HeadyAI API key. Keys are scoped per project with configurable rate limits.
2. Make Your First Request
Send a POST to /v1/route with your prompt and let HeadyAI select the optimal provider automatically based on context.
3. View Routing Dashboard
Monitor routing decisions, latency metrics, and provider health in real time from your HeadyAI dashboard.
Installation
Install HeadyAI via your preferred package manager or deploy as a containerized service. Supports npm, pip, Docker, and Cloudflare Workers.
npm & pip Packages
Install with npm install @heady/ai or pip install heady-ai. Both packages include TypeScript types and full async support.
Docker Setup
Pull the official headyai/router image and run with your provider credentials mounted. Includes built-in health checks and metrics.
Cloudflare Worker Deployment
Deploy HeadyAI at the edge with the Cloudflare Worker template. Sub-millisecond cold starts with global distribution.
Architecture
HeadyAI uses a multi-layer routing architecture designed for resilience, speed, and intelligent failover across all connected providers.
Edge Layer
Global edge nodes handle TLS termination, request validation, and geographic routing before forwarding to the gateway.
Gateway & Orchestration
The gateway applies rate limiting and auth, then the orchestration layer scores providers using φ-pressure algorithms in real time.
Provider Mesh
A self-healing mesh of AI provider connections with automatic failover, circuit breaking, and weighted load balancing.
Data Model
Understand the core data structures that power HeadyAI's routing engine — from request objects to session state tracking.
Request Objects
Typed request payloads containing prompt, model preferences, routing hints, and budget constraints for each API call.
Routing Decisions
Immutable decision records capturing provider selection rationale, scoring breakdown, and fallback chain for every routed request.
Provider Responses & Session State
Normalized provider responses with token counts, latency data, and persistent session state for multi-turn conversations.
Security
HeadyAI implements defense-in-depth security with mutual TLS, zero-trust provider access, and comprehensive audit logging.
mTLS & API Key Rotation
All provider connections use mutual TLS. API keys support automatic rotation with configurable expiry and revocation policies.
Zero-Trust Provider Access
Every provider call is authenticated and authorized independently. No implicit trust — each request is verified against scoped permissions.
Audit Logging
Complete audit trail of all routing decisions, access events, and configuration changes with tamper-evident log integrity.
API Reference
Full REST API documentation for HeadyAI's core endpoints. All endpoints accept JSON and return structured responses with routing metadata.
/route & /chat
The /route endpoint auto-selects the best provider. The /chat endpoint provides a conversational interface with session continuity.
/complete
Single-shot completion endpoint with provider targeting, temperature control, and streaming support via Server-Sent Events.
/models
Lists all available models across connected providers with real-time availability, pricing, and capability metadata.
Webhooks
Subscribe to real-time events from HeadyAI's routing engine. Receive notifications for routing changes, failovers, budget alerts, and health status.
Routing Events
Get notified on routing decisions, provider switches, and latency threshold breaches with full decision context in the payload.
Provider Failover Notifications
Instant alerts when a provider fails over, including the reason, fallback provider selected, and estimated recovery time.
Budget Alerts & Health Checks
Configurable budget threshold alerts and periodic health check summaries for all connected providers and routing nodes.
SDKs & Libraries
Official SDK support for major languages. Each SDK provides type-safe clients, automatic retries, and built-in streaming support.
JavaScript / TypeScript
Full-featured SDK with tree-shakeable modules, native fetch support, and first-class TypeScript types for all API surfaces.
Python
Async-first Python SDK with Pydantic models, streaming generators, and seamless integration with LangChain and LlamaIndex.
Go & Rust
High-performance Go and Rust SDKs for latency-sensitive applications. Zero-copy deserialization and compile-time API validation.
Ecosystem
HeadyAI is part of the broader Heady™ platform. Connect with other Heady services for a complete AI infrastructure stack.
HeadyOS & HeadyAPI
HeadyOS provides the Liquid Latent operating layer. HeadyAPI offers the unified gateway for all Heady platform services.
HeadyBuddy & HeadyMCP
HeadyBuddy is the conversational AI assistant widget. HeadyMCP provides the Model Context Protocol layer for tool integration.
HeadyMe
Personal AI dashboard and identity layer. Manage your API keys, usage analytics, and provider preferences from one place.
Support
Get help from the HeadyAI community and team. We offer multiple support channels for developers of all levels.
Discord Community
Join the Heady Discord for real-time help, feature discussions, and direct access to the engineering team.
GitHub Issues & Docs
Report bugs and request features on GitHub. Browse the full documentation site for guides, tutorials, and API references.
Enterprise Support
Dedicated support engineers, custom SLAs, priority routing, and private Slack channel for enterprise customers.