HIVV Gateway API v2 Public

An OpenAI-compatible inference proxy, autonomous agent tri-state governance engine, and distributed compute pool. Plug in standard OpenAI SDKs or communicate with local on-premise Gemma-4 running at ~64 tokens/sec.

Base URL: https://hivv.org/v1 Streaming: Server-Sent Events (SSE) Local Inference: ~64 tps hardware-accelerated Rate Limit: 60 req/min (free open tier)

⚡ 1. OpenAI-Compatible Chat API

Direct drop-in replacement for OpenAI's Chat Completions endpoint. Supports full multi-turn dialog, token-by-token streaming, reasoning trace accordions (reasoning_content), and automatic local-to-cloud failover.

POST /v1/chat/completions Streaming & non-streaming chat
ParameterTypeRequiredDescription
messages array Yes Array of conversation messages: [{"role": "user", "content": "..."}]
model string No Model identifier (e.g., local-model, gemma-4, gpt-4o, claude-3-5-sonnet). Defaults to fastest local engine.
stream boolean No Set to true (default) for real-time SSE streaming, or false for JSON completion.
provider string No Override provider selection (e.g. llamacpp, ollama, local, anthropic, openai).
api_url string No Direct custom AI endpoint URL (e.g. http://localhost:8080/v1/chat/completions). Routes directly to any local or remote worker.
temperature number No Sampling temperature between 0.0 and 2.0 (default 0.7).
max_tokens integer No Maximum tokens to generate.

Code Examples

cURL (Streaming SSE) 
curl -N -X POST https://hivv.org/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local-model",
    "stream": true,
    "messages": [
      {"role": "system", "content": "You are a concise, ultra-fast assistant."},
      {"role": "user", "content": "Explain quantum computing in two sentences."}
    ]
  }'
Python (Official OpenAI SDK) 
from openai import OpenAI

# Initialize client pointing to HIVV gateway
client = OpenAI(
    base_url="https://hivv.org/v1",
    api_key="public-spectator"  # Any string for public tier; or user X-Session-Token
)

response = client.chat.completions.create(
    model="local-model",
    messages=[
        {"role": "user", "content": "Hello HIVV, what is 42 * 9?"}
    ],
    stream=True
)

for chunk in response:
    content = chunk.choices[0].delta.content or ""
    print(content, end="", flush=True)
print()
JavaScript / TypeScript (Fetch Streaming) 
const response = await fetch('https://hivv.org/v1/chat/completions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    stream: true,
    messages: [{ role: 'user', content: 'What is the speed of light?' }]
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop();

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = line.slice(6).trim();
      if (data === '[DONE]') break;
      const parsed = JSON.parse(data);
      const delta = parsed.choices?.[0]?.delta?.content || '';
      process.stdout.write(delta);
    }
  }
}
GET /v1/models List registered models & providers
cURL 
curl https://hivv.org/v1/models

🛡️ 2. Autonomous Agent Governance API

Inspect agent states under the Tri-State model (YES Autonomous, MAYBE Human Approval Required, NO Blocked) and manage access permissions.

GET /api/dashboard/agents Query agent fleet (public & authenticated)

Query parameters: perspective=public (default, safe for guests) or perspective=private (requires authenticated X-Session-Token).

JSON Response 
{
  "success": true,
  "perspective": "public",
  "agents": [
    {
      "id": "1",
      "public_name": "Autonomous Weaver",
      "agent_type": "orchestrator",
      "state": "yes",
      "trust_score": 92,
      "pending_permissions": 0
    }
  ]
}
GET /api/agents/approvals/pending Pending permission requests
POST /api/agents/approvals/:id/decide Approve or deny pending permission
cURL 
curl -X POST https://hivv.org/api/agents/approvals/perm_123/decide \
  -H "Content-Type: application/json" \
  -H "X-Session-Token: YOUR_SESSION_TOKEN" \
  -d '{"decision": "approve"}'
POST /api/dashboard/agents/:id/state Toggle agent tri-state (yes / maybe / no)

📡 3. Gateway Telemetry & Public Pulse

High-frequency, unauthenticated metrics for monitoring health, provider status, and live request latency.

GET /api/public/heartbeat 3-second heartbeat probe
JSON Response 
{
  "ok": true,
  "ts": 1788855296527,
  "local_backends_online": 2
}
GET /api/public/status Full gateway throughput, uptime, and active backends
GET /api/public/activity Anonymized recent request stream

🔐 4. Authentication & Compute Pool

Users can create accounts, securely store private LLM API keys in an encrypted vault, or donate idle quota to the crowdsourced compute pool.

POST /api/auth/login Authenticate and receive session token
cURL 
curl -X POST https://hivv.org/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}'
POST /api/keys/donate Contribute unused API key to the community pool

Donate any AI provider key (OpenAI, Anthropic, Google, MiniMax, etc.) to the community compute pool. When local AI isn't available, your donated key helps others get responses. Keys are encrypted at rest with AES-256-GCM.

cURL 
curl -X POST https://hivv.org/api/keys/donate \
  -H "Content-Type: application/json" \
  -H "X-Session-Token: YOUR_SESSION_TOKEN" \
  -d '{
    "provider": "openai",
    "api_key": "sk-proj-...",
    "model_preference": "gpt-4o",
    "priority": 5
  }'
ParameterTypeRequiredDescription
provider string Yes Provider name: openai, anthropic, google, minimax, etc.
api_key string Yes Your API key. Encrypted immediately on receipt — never stored in plaintext.
model_preference string No Preferred model to use with this key (e.g. gpt-4o, claude-3-5-sonnet).
priority integer No Priority 1-10 (higher = used first). Default: 5.

🐝 5. Distributed Node Network

Every hivv start machine registers with the hub and appears in the cluster. Monitor node health, view per-node performance, and see which models are available across the network.

GET /api/control/nodes List all registered nodes with metrics

Public endpoint — no auth required. Returns node details including status, capabilities, local models, system info, and live metrics.

JSON Response 
{
  "total": 3,
  "online": 2,
  "nodes": [
    {
      "id": "a1b2c3d4",
      "name": "office-gpu",
      "ip": "203.0.113.42",
      "lan_ip": "192.168.1.42",
      "version": "1.2.3",
      "status": "online",
      "registered_at": 1694800000000,
      "last_heartbeat": 1694800060000,
      "capabilities": ["llama.cpp", "ollama"],
      "local_models": [
        { "source": "llama.cpp", "models": ["gemma-4-9b"], "port": 8080 }
      ],
      "system": {
        "cpus": 16,
        "arch": "x64",
        "platform": "linux"
      },
      "metrics": {
        "cpu_percent": 34.2,
        "mem_percent": 62.1,
        "active_jobs": 1,
        "uptime_seconds": 86400,
        "workers": 4,
        "available_capacity": 3
      },
      "stats": {
        "tasks_completed": 142,
        "tasks_failed": 2,
        "total_tokens_processed": 1850000,
        "total_cost": 0.42
      }
    }
  ]
}
GET /api/control/stats Cluster-wide performance stats

Aggregated stats across all nodes — perfect for dashboards. Shows per-node breakdown plus cluster totals.

JSON Response 
{
  "count": 3,
  "totals": {
    "tasks_completed": 587,
    "tasks_failed": 4,
    "tokens": 7250000,
    "requests": 612,
    "cost": 1.84
  },
  "nodes": [
    {
      "id": "a1b2c3d4",
      "name": "office-gpu",
      "ip": "192.168.1.42",
      "status": "online",
      "models": 2,
      "cpu": 34.2,
      "mem": 62.1,
      "tasks_completed": 142,
      "tokens": 1850000,
      "requests": 156,
      "cost": 0.42,
      "uptime_s": 86400,
      "hw": "AMD Ryzen 9 7950X"
    }
  ]
}