API Reference

Authentication

Include your API key in the Authorization header as a Bearer token.

Authorization: Bearer hx_live_YOUR_API_KEY

Auth methods

Response headers

Every API response includes useful metadata headers:

Idempotency

Include an Idempotency-Key header to safely retry requests. If the same key is sent again within 24 hours, the cached response is returned instead of creating a new generation.

Bring Your Own Key (BYOK)

Pass your own provider API key via the X-Provider-Key header to route directly to the provider. BYOK requests are charged a 5% platform fee (minimum 1 credit) instead of the full credit cost.

Quickstart

Send your first request in seconds. HexaClaw is OpenAI-compatible -- just change the base URL and API key.

curl -X POST https://api.hexaclaw.com/v1/chat/completions \
  -H "Authorization: Bearer hx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Hello, world!"}]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://api.hexaclaw.com/v1",
    api_key="hx_live_YOUR_KEY",
)

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Hello, world!"}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.hexaclaw.com/v1",
  apiKey: "hx_live_YOUR_KEY",
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "Hello, world!" }],
});
console.log(response.choices[0].message.content);

Models

Discover available models and their pricing. All tiers have access to all models.

Model aliases

You can use convenient short aliases instead of full model IDs. For example, claude-sonnet resolves to claude-sonnet-4-6.

50+ aliases are supported in total. Use GET /v1/models to see the full list.

Chat Completions

OpenAI-compatible chat completions endpoint. Supports streaming, function calling, JSON mode, and vision across all providers.

Request body

curl -X POST https://api.hexaclaw.com/v1/chat/completions \
  -H "Authorization: Bearer hx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "stream": true,
    "messages": [{"role": "user", "content": "Write a haiku about APIs"}]
  }'

Messages (Anthropic Native)

Native Anthropic Messages API for Claude models. Use this if you need Anthropic-specific features like extended thinking or cache control. Also supports x-api-key header authentication (Anthropic SDK convention). The anthropic-version and anthropic-beta headers are forwarded to the upstream provider.

Request body

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.hexaclaw.com/v1",
    api_key="hx_live_YOUR_KEY",
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain quantum computing"}],
)
print(message.content[0].text)

Web Search

Request body

curl -X POST https://api.hexaclaw.com/v1/search \
  -H "Authorization: Bearer hx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "latest AI research papers 2026"}'

Image Generation

Generate images using Flux models via fal.ai. Three quality tiers available.

Request body

curl -X POST https://api.hexaclaw.com/v1/images/generate \
  -H "Authorization: Bearer hx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A cyberpunk city at sunset", "model": "dev"}'

Text-to-Speech

Request body

Speech-to-Text

Request body (multipart/form-data)

Embeddings

Generate text embeddings for semantic search, clustering, and RAG pipelines. OpenAI-compatible endpoint.

Request body

Available embedding models

Vector Storage

Managed vector database for RAG, semantic search, and long-term memory. Each user gets an isolated namespace.

Upsert request body

curl -X POST https://api.hexaclaw.com/v1/vectors/upsert \
  -H "Authorization: Bearer hx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      {"id": "doc-1", "vector": [0.1, 0.2, ...], "payload": {"text": "Hello world"}},
      {"id": "doc-2", "vector": [0.3, 0.4, ...], "payload": {"text": "Goodbye world"}}
    ]
  }'

Query request body

Browser Sessions

Launch headless browser sessions for web scraping, testing, and automation via Browserbase. Billed per minute of session time.

Create session body

Guardian Security Max Plan

AI security scanning for prompt injection, PII leaks, and malicious content. Guardian runs automatically on all Max plan requests. These endpoints are for explicit on-demand scanning.

API Key Management

Create, list, update, and deactivate API keys. These endpoints require Firebase ID token authentication (not API key auth).

Usage & Credits

Track credit balance, usage history, and spending across models and services.

Pricing

1 credit = $0.01 USD. Credits are deducted per request based on token usage.

LLM Models

Services

Rate Limits

Rate limits are applied per API key. Exceeding limits returns HTTP 429.

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Errors

All errors return a consistent JSON format with an error object.

{
  "error": {
    "message": "Insufficient credits",
    "type": "payment_required",
    "code": 402
  }
}

Status codes

SDKs & Libraries

HexaClaw is compatible with existing OpenAI and Anthropic SDKs. No custom SDK needed -- just change the base URL.

pip install openai

from openai import OpenAI
client = OpenAI(base_url="https://api.hexaclaw.com/v1", api_key="hx_live_YOUR_KEY")

npm install openai

import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.hexaclaw.com/v1", apiKey: "hx_live_YOUR_KEY" });

pip install anthropic

import anthropic
client = anthropic.Anthropic(base_url="https://api.hexaclaw.com/v1", api_key="hx_live_YOUR_KEY")

curl https://api.hexaclaw.com/v1/chat/completions \
  -H "Authorization: Bearer hx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"Hi"}]}'

CLI & Terminal

HexaClaw includes a full CLI for managing agents, channels, and cloud services from your terminal. Install it with a single command.

# One-line install (macOS / Linux)
curl -sSL https://hexaclaw.com/install-cli | bash

# Or install via npm
npm install -g hexaclaw

# Verify installation
hexaclaw --version

Agent Commands

Run AI agent turns directly from your terminal. The agent has access to 60+ skills, web search, image generation, file operations, scheduling, and more.

# Ask a question
hexaclaw agent --agent main --message "What is the capital of France?"

# Get JSON output (for scripting)
hexaclaw agent --agent main --message "What is 2+2?" --json

# Set thinking level
hexaclaw agent --agent main --message "Analyze this code" --thinking medium

hexaclaw agent --agent main \
  --message "Search the web for the latest AI news and summarize the top 3 stories"

hexaclaw agent --agent main \
  --message "Generate an image of a sunset over mountains, photorealistic style"

# The agent returns the image URL in its response

# Read a file
hexaclaw agent --agent main --message "Read ~/notes.txt and summarize it"

# Write a file
hexaclaw agent --agent main \
  --message "Write a Python script that sorts a list of numbers to ~/sort.py"

# List scheduled jobs
hexaclaw agent --agent main --message "List my cron jobs"

# Create a daily summary
hexaclaw agent --agent main \
  --message "Schedule a daily job at 9am that searches for AI news and sends me a summary"

{
  "runId": "ce6fcc29-c3f3-4653-ad16-9057c6d04ecf",
  "status": "ok",
  "summary": "completed",
  "result": {
    "payloads": [
      {
        "text": "The capital of France is Paris.",
        "mediaUrl": null
      }
    ],
    "meta": {
      "durationMs": 2270,
      "agentMeta": {
        "provider": "hexaclaw-cloud",
        "model": "gemini-2.5-flash",
        "usage": {
          "input": 49977,
          "output": 12,
          "total": 49989
        }
      }
    }
  }
}

Common Use Cases

Real-world examples showing how to use HexaClaw for everyday tasks. All commands below assume you have HexaClaw installed and authenticated.

# Simple prompt
hexaclaw agent --local --message "What is 2+2? Reply with just the number." --agent main --thinking low

# Specific model (use any of the 25+ models)
hexaclaw agent --local --message "Hello, who are you?" --agent main --thinking low

/search "latest news on AI agents"

/imagine a cyberpunk cat wearing sunglasses --model schnell
/imagine a mountain landscape at sunset --model dev
/imagine photorealistic portrait of a robot --model pro

/speak "Hello, this is HexaClaw speaking" --voice nova

/transcribe /path/to/audio.mp3

/browse

/video a cat walking on the moon --model wan-2.1-turbo

/music upbeat electronic lo-fi beat --duration 10

/scrape https://example.com

/remember HexaClaw launched in March 2026
/recall when did HexaClaw launch

/email user@example.com "Test Subject" This is a test email

/budget

# Agent will use web search tool
hexaclaw agent --local --message "Search the web for the latest Claude model and summarize" --agent main --thinking low

# Agent will use image gen tool
hexaclaw agent --local --message "Generate an image of a futuristic city" --agent main --thinking low

# Agent factory — spawn a specialist
hexaclaw agent --local --message "Analyze my system and create a Python data analysis agent" --agent main --thinking low

# Check auth status
hexaclaw login --status

# List available models
hexaclaw models list

# List agents
hexaclaw agents list

# List plugins
hexaclaw plugins list

# Check config
hexaclaw config get agents.defaults.model

Gateway & TUI

The HexaClaw gateway is a local server that provides a web-based control UI, WebSocket connections for real-time chat, and manages channel integrations.

# Start the gateway (runs as a background service)
hexaclaw gateway start

# Or run interactively
hexaclaw gateway run --bind loopback --port 18789

# Check gateway status
hexaclaw gateway status

# Open the dashboard
hexaclaw dashboard

# Or navigate directly to:
# http://127.0.0.1:18789/

# The agent automatically loads skills based on your message
# Examples of skill-powered tasks:

# Email (via himalaya / gmail skill)
hexaclaw agent --agent main --message "Check my inbox for unread emails"

# GitHub (via github / gh-issues skill)
hexaclaw agent --agent main --message "List open PRs in my repo"

# Calendar (via calendar skill)
hexaclaw agent --agent main --message "What meetings do I have today?"

# Weather
hexaclaw agent --agent main --message "What's the weather in San Francisco?"

# Research
hexaclaw agent --agent main --message "Do a deep research on quantum computing trends"