API Reference

One API, every AI model, automatic failover, governed agent execution, and full audit trail. Get started in 30 seconds.

Authentication

All API endpoints require a project API key. Get one from the Developer Console — free, takes 30 seconds.

Authorization: Bearer zb_your_api_key_here

Base URL: https://zenibot.dev

Text Generation

POST /api/generate VASVELVOGVEG-routed, quality-scored, audit-logged
Parameters
Field Type Description
prompt string required The text prompt
model string Model name default: llama3.2:3b
auto_agent boolean Auto-route tasks to ZeniAgent default: true
Request
curl -X POST https://zenibot.dev/api/generate \
  -H "Authorization: Bearer zb_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Explain quantum computing in simple terms"}'
import requests

response = requests.post(
    "https://zenibot.dev/api/generate",
    headers={"Authorization": "Bearer zb_your_key"},
    json={"prompt": "Explain quantum computing in simple terms"}
)

data = response.json()
print(data["response"])              # AI response text
print(data["provider"])              # sun, gemini, openai, or dharma
print(data["alignment"])             # Quality + safety scores
print(f"Block #{data['ledger_block']}")  # Audit trail
const response = await fetch("https://zenibot.dev/api/generate", {
    method: "POST",
    headers: {
        "Authorization": "Bearer zb_your_key",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        prompt: "Explain quantum computing in simple terms"
    })
});

const data = await response.json();
console.log(data.response);          // AI response text
console.log(data.provider);          // sun, gemini, openai, or dharma
console.log(data.alignment);         // Quality + safety scores
Response Schema
Field Type Description
response string Generated text (K1 safety-filtered)
provider string "sun", "gemini", "openai", or "dharma"
model string Actual model used (e.g. "llama3.2:3b")
latency_ms number End-to-end latency in milliseconds
alignment object VASVELVOGVEG quality scores
alignment.alignment_score float Overall quality (0–1)
alignment.quality float Math Kernel quality metric
alignment.drift float EWMA anomaly detection
ledger_block integer Immutable Truth Ledger block #
mode string "generate" or "agent"
usage.input integer Input tokens consumed
usage.output integer Output tokens generated

Multi-turn Chat

POST /api/chat Session memory + conversation
Parameters
Field Type Description
messages array required Array of {role, content} objects
model string Model name default: llama3.2:3b
session_id string Session ID for conversation memory
Request
curl -X POST https://zenibot.dev/api/chat \
  -H "Authorization: Bearer zb_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
        {"role": "system", "content": "You are a helpful coding assistant."},
        {"role": "user", "content": "How do I reverse a string in Python?"}
    ],
    "session_id": "session-abc"
  }'
import requests

response = requests.post(
    "https://zenibot.dev/api/chat",
    headers={"Authorization": "Bearer zb_your_key"},
    json={
        "messages": [
            {"role": "system", "content": "You are a helpful coding assistant."},
            {"role": "user", "content": "How do I reverse a string in Python?"}
        ],
        "session_id": "session-abc"
    }
)

data = response.json()
print(data["message"]["content"])    # Assistant's reply
const response = await fetch("https://zenibot.dev/api/chat", {
    method: "POST",
    headers: {
        "Authorization": "Bearer zb_your_key",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        messages: [
            { role: "system", content: "You are a helpful coding assistant." },
            { role: "user", content: "How do I reverse a string in Python?" }
        ],
        session_id: "session-abc"
    })
});

const data = await response.json();
console.log(data.message.content);

Streaming (SSE) NEW

POST /api/generate/stream Server-Sent Events — token-by-token

Returns an SSE stream. Full VASVELVOGVEG pipeline runs before streaming — governed, quality-scored responses in real time.

Events
Event Fields Description
start provider, model First event — which provider was selected
token text Streamed text chunks
done alignment, ledger_block Final event with quality + audit data
error error Error message if failed
Request
curl -N -X POST https://zenibot.dev/api/generate/stream \
  -H "Authorization: Bearer zb_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Write a poem about the ocean"}'

# Output:
# data: {"event":"start","provider":"sun","model":"llama3.2:3b"}
# data: {"event":"token","text":"The endless waves"}
# data: {"event":"token","text":" crash upon the"}
# data: {"event":"done","alignment":{...},"ledger_block":305}
import requests, json

response = requests.post(
    "https://zenibot.dev/api/generate/stream",
    headers={"Authorization": "Bearer zb_your_key"},
    json={"prompt": "Write a poem about the ocean"},
    stream=True
)

for line in response.iter_lines():
    if line:
        line = line.decode("utf-8")
        if line.startswith("data: "):
            event = json.loads(line[6:])
            if event["event"] == "token":
                print(event["text"], end="", flush=True)
            elif event["event"] == "done":
                print(f"\n✓ Block #{event['ledger_block']}")
const response = await fetch("https://zenibot.dev/api/generate/stream", {
    method: "POST",
    headers: {
        "Authorization": "Bearer zb_your_key",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({ prompt: "Write a poem about the ocean" })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    const lines = decoder.decode(value, { stream: true }).split("\n");
    for (const line of lines) {
        if (line.startsWith("data: ")) {
            const event = JSON.parse(line.slice(6));
            if (event.event === "token") process.stdout.write(event.text);
        }
    }
}

ZeniAgent 25 TOOLS

Autonomous agent with real tool execution. Every step is safety-gated through K1-K6, audited to the Truth Ledger, and quality-scored by the Math Kernel.

POST /api/agent Governed task execution
Parameters
Field Type Description
goal string required Natural language task
tools string[] Restrict to specific tools
Request
curl -X POST https://zenibot.dev/api/agent \
  -H "Authorization: Bearer zb_your_key" \
  -H "Content-Type: application/json" \
  -d '{"goal": "Read /tmp/report.pdf and summarize it"}'
import requests

response = requests.post(
    "https://zenibot.dev/api/agent",
    headers={"Authorization": "Bearer zb_your_key"},
    json={"goal": "Read /tmp/report.pdf and summarize it"}
)

data = response.json()
print(data["summary"])
for step in data["steps"]:
    print(f"  {step['tool']}: {step['status']}")
const response = await fetch("https://zenibot.dev/api/agent", {
    method: "POST",
    headers: {
        "Authorization": "Bearer zb_your_key",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        goal: "Read /tmp/report.pdf and summarize it"
    })
});

const data = await response.json();
console.log(data.summary);
data.steps.forEach(s => console.log(`  ${s.tool}: ${s.status}`));
Available Tools
Category Tools Risk
Document doc_read_pdf · doc_read_xlsx · doc_read_docx · doc_read_csv Medium
Media vision · audio_transcribe · screenshot Medium
Compute code_eval · code_exec Med/High
System shell · env_inspect · process_list Low–High
Network http Medium
I/O file_read · file_write Med/High
Protocol mcp_call · mcp_discover · mcp_execute Low–Med
Knowledge rag_search · rag_index · rag_query Low–Med
Internal reason · compose · analyze · complete Low

Playground NO AUTH

POST /api/playground 10 free requests per IP
curl -X POST https://zenibot.dev/api/playground \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is machine learning?"}'
import requests

resp = requests.post(
    "https://zenibot.dev/api/playground",
    json={"prompt": "What is machine learning?"}
)
print(resp.json()["response"])
const resp = await fetch("https://zenibot.dev/api/playground", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ prompt: "What is machine learning?" })
});
console.log((await resp.json()).response);

Other Endpoints

GET/api/modelsList models by provider
GET/api/memory/{session_id}Get conversation history
DELETE/api/memory/{session_id}Clear session memory
GET/api/agent/toolsList all 25 agent tools
GET/healthHealth check — no auth

Error Codes

Code Meaning Action
401 Missing or invalid API key Check Authorization header
403 Content blocked by K1-K6 safety gates Review prompt content
429 Rate limit exceeded Wait or upgrade plan
503 All providers exhausted Dharma fallback serves from ethical corpus

Rate Limits

Plan Requests/Day Projects Streaming
Playground 10 per session
Free 100 Unlimited
Pro (RM99/mo) 10,000 Unlimited
Enterprise Unlimited Unlimited ✓ Priority

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining) are included in all API responses.