Quick Start

1. Sign up and get your API key

After creating your account at getzos.ai/signup, find your API key in Dashboard → Settings → API Keys.

2. Make your first API call

curl -H "X-API-Key: YOUR_API_KEY" \
     https://getzos.ai/api/overview

3. List your agents

curl -H "X-API-Key: YOUR_API_KEY" \
     https://getzos.ai/api/agents

Core Concepts

ZOS is built around three concepts: Agents, Tasks, and the Evolution Engine.

Agents

Agents are autonomous AI workers. Each agent has a role, a fitness score, and a task history. Agents run on a schedule or can be triggered via API or Telegram command.

Tasks

A task is a unit of work assigned to an agent. Tasks have inputs, outputs, status, cost, and duration. The dashboard shows all task history in real-time.

Fitness

Every agent has a fitness score (0.0 – 1.0) that reflects its performance history. Higher fitness = better reliability. The Evolution Engine promotes high-fitness agents and mutates or retires low-fitness ones.

Your Agents

Authentication

All API requests require an API key passed in the X-API-Key header.

X-API-Key: zos-your-api-key-here

Get your API key from the dashboard under Settings → API Keys. Keys can be rotated at any time.

API Endpoints

Spawn an Agent — Example

curl -X POST https://getzos.ai/api/agents/spawn \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CryptoWatcher",
    "role": "Monitor BTC and ETH for 10%+ moves",
    "config": {
      "tickers": ["BTC", "ETH"],
      "threshold": 0.10,
      "alert_channel": "telegram"
    }
  }'

WebSocket Streams

ZOS provides two real-time WebSocket streams for live data.

Live Logs

wss://getzos.ai/ws/logs?api_key=YOUR_KEY

System Events

wss://getzos.ai/ws/events?api_key=YOUR_KEY

Events include: agent_spawned, agent_killed, task_completed, approval_decided, evolution_event

JavaScript Example

const ws = new WebSocket('wss://getzos.ai/ws/events?api_key=YOUR_KEY');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  if (data.type === 'task_completed') {
    console.log('Task done:', data.task_id, data.output);
  }
  
  if (data.type === 'agent_spawned') {
    console.log('New agent:', data.name, data.agent_id);
  }
};

Telegram Bot — @ZOSBOSSBOT

@ZOSBOSSBOT is your primary interface with ZOS. All agents can send you alerts, reports, and requests through it. You can also control ZOS entirely from Telegram.

Connect Your Account

/connect YOUR_TOKEN

Commands Reference

Building Custom Agents

The BUILDER agent can create new specialized agents from a plain English description. Use it via Telegram, the dashboard, or the API.

Via Telegram

/build monitor Bitcoin fear & greed index and alert me when it drops below 20

Via API

curl -X POST https://getzos.ai/api/agents/spawn \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FearGreedMonitor",
    "role": "Monitor crypto fear and greed index, alert on extreme readings",
    "config": {
      "lower_threshold": 20,
      "upper_threshold": 80,
      "check_interval_hours": 1
    }
  }'

Evolution Engine

ZOS automatically improves your agents over time through an evolutionary loop:

1. Measure — track task success rate, speed, cost-per-result
2. Score — update each agent's fitness score (0.0–1.0)
3. Evolve — mutate high-performing agents, retire consistently poor ones
4. Promote — spin up new variants of top agents for high-demand tasks

You can view the full evolution history at /api/evolution or in the dashboard under the Evolution tab.

Code Examples

Python — Get System Overview

import requests

ZOS_KEY = "your-api-key"
BASE    = "https://getzos.ai"

def get_overview():
    r = requests.get(
        f"{BASE}/api/overview",
        headers={"X-API-Key": ZOS_KEY}
    )
    data = r.json()
    print(f"Agents online: {data['active_agents']}")
    print(f"Tasks today:   {data['tasks_today']}")
    print(f"Cost today:    ${data['cost_today']:.4f}")
    print(f"Budget used:   {data['budget_pct']}%")

get_overview()

Python — Stream Live Events

import websocket, json

def on_message(ws, message):
    event = json.loads(message)
    if event.get('type') == 'task_completed':
        print(f"✅ Task done: {event['task_id']}")
    elif event.get('type') == 'agent_spawned':
        print(f"🤖 New agent: {event['name']}")

ws = websocket.WebSocketApp(
    "wss://getzos.ai/ws/events?api_key=YOUR_KEY",
    on_message=on_message
)
ws.run_forever()

JavaScript — Monitor Agent Fitness

const ZOS_KEY = process.env.ZOS_API_KEY;

async function checkFitness() {
  const res = await fetch('https://getzos.ai/api/agents', {
    headers: { 'X-API-Key': ZOS_KEY }
  });
  const agents = await res.json();
  
  const lowFitness = agents.filter(a => a.fitness < 0.5);
  if (lowFitness.length > 0) {
    console.warn('Low-fitness agents:', lowFitness.map(a => a.name));
  }
  
  return agents;
}

checkFitness();