Quick Start

Make your first API call to Quox. This example sends a chat message and receives Claude's response.

Base URL

All Collector API endpoints use http://YOUR_HOST:9848 as the base URL. Replace with your actual QuoxCORE server address.

Your First API Call

cURL

# Send a message to Quox
curl -X POST http://localhost:9848/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the fleet status?",
    "sessionId": "my-session-123"
  }'

Response

{
  "success": true,
  "response": "Fleet Status Report:\n\n- Total Agents: 12\n- Online: 11\n- Offline: 1 (kuma02)\n\nAll systems operational.",
  "sessionId": "my-session-123",
  "tokens": {
    "input": 156,
    "output": 89
  }
}

Quick Examples

JavaScript / Fetch

javascript

const response = await fetch('/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: 'List all hosts',
    sessionId: 'session-001'
  })
});
const data = await response.json();
console.log(data.response);

Python

python

import requests

response = requests.post(
    'http://localhost:9848/api/chat',
    json={
        'message': 'List all hosts',
        'sessionId': 'session-001'
    }
)
print(response.json()['response'])

Authentication

Quox supports multiple authentication methods depending on the endpoint type. Most internal APIs do not require authentication, while external integrations use API keys or JWT tokens.

API Key Setup

API keys are configured in the .env file at the root of your QuoxCORE installation:

Environment Variables

# Required for AI conversations
ANTHROPIC_API_KEY=sk-ant-...

# Required for semantic memory (embeddings)
OPENAI_API_KEY=sk-...

# Optional - voice features
ELEVENLABS_API_KEY=...     # TTS synthesis

# Optional - vector memory (if remote)
QDRANT_API_KEY=...

# After changes, restart services:
docker compose restart collector

Request Format

All API requests should use JSON format with the following headers:

Required Headers

Content-Type: application/json
Accept: application/json

# For authenticated endpoints (future):
Authorization: Bearer <your-jwt-token>
X-API-Key: <your-api-key>

Security Note

The dashboard currently has no authentication. All endpoints are accessible within your network. See the Safety & Security docs for security best practices.

Collector API

The Collector is the primary integration layer. These endpoints handle chat, voice, and quick actions - routing requests through Claude and the agent hierarchy.

Method	Endpoint	Purpose
`POST`	`/webhook/chat`	Send message to Claude
`POST`	`/webhook/speak`	Text-to-speech synthesis
`POST`	`/webhook/transcribe`	Speech-to-text transcription
`POST`	`/webhook/quick-action`	Infrastructure quick actions

Chat Endpoint

POST/webhook/chat

Send a message to Claude through Quox. Supports context injection, memory retrieval, and multi-turn conversations.

Request Body

json

{
  "message": "string (required) - The user's message",
  "sessionId": "string (optional) - Session ID for conversation continuity",
  "assistant": "string (optional) - Target assistant (quox, sentinel, nova, etc.)",
  "context": {
    "includeMemory": true,    // Include relevant memories
    "includeWSM": true,       // Include working set memory
    "maxTokens": 4096         // Max response tokens
  }
}

Response

json

{
  "success": true,
  "response": "string - Claude's response text",
  "sessionId": "string - Session ID for follow-up",
  "assistant": "quox",
  "tokens": {
    "input": 156,
    "output": 89,
    "total": 245
  },
  "routed": false,           // true if handled by Smart Router
  "routerPattern": null,     // Pattern name if routed
  "memories": [              // Relevant memories used
    { "type": "episodic", "content": "...", "score": 0.85 }
  ]
}

Text-to-Speech

POST/webhook/speakAuth Required

Convert text to speech using ElevenLabs. Returns audio data in the specified format.

Request Body

json

{
  "text": "string (required) - Text to synthesize",
  "voice": "string (optional) - Voice ID (default: Rachel)",
  "voiceMode": "string (optional) - JARVIS | Cyberpunk | HAL",
  "format": "string (optional) - mp3 | wav | ogg (default: mp3)"
}

Response

json

{
  "success": true,
  "audio": "base64-encoded-audio-data",
  "format": "mp3",
  "duration": 3.2,
  "voice": "Rachel"
}

Speech-to-Text

POST/webhook/transcribeAuth Required

Transcribe audio to text using OpenAI Whisper. Supports multiple audio formats.

Request Body

json

{
  "audio": "base64-encoded-audio (required)",
  "format": "string - mp3 | wav | webm | m4a",
  "language": "string (optional) - ISO language code (default: en)"
}

Response

json

{
  "success": true,
  "text": "The transcribed text content",
  "language": "en",
  "confidence": 0.95,
  "duration": 5.2
}

QuoxAgent Collector API

The QuoxAgent Collector runs on the Quox host (port 9848) and aggregates data from all QuoxAgent agents across your infrastructure.

Method	Endpoint	Purpose
`GET`	`/api/v1/agents`	List all registered agents
`GET`	`/api/v1/agents/:id`	Get single agent details
`GET`	`/api/v1/fleet/summary`	Fleet summary statistics
`GET`	`/api/v1/check/:hostId`	Check if host has QuoxAgent installed
`POST`	`/api/v1/heartbeat`	Receive agent heartbeat
`GET`	`/health`	Collector health check
`GET`	`/metrics`	Prometheus metrics
`GET`	`/install`	Serve install script

GET/api/v1/agents

Returns a list of all registered QuoxAgent agents with their current status and metadata.

Example Response

json

{
  "agents": [
    {
      "id": "nw-web-01",
      "hostname": "nw-web-01.local",
      "ip": "10.20.0.101",
      "status": "online",
      "version": "1.2.0",
      "lastSeen": "2025-01-25T10:30:00Z",
      "uptime": 864000,
      "os": "ubuntu-22.04",
      "resources": {
        "cpu": 23.5,
        "memory": 68.2,
        "disk": 45.0
      }
    }
  ],
  "total": 12,
  "online": 11,
  "offline": 1
}

GET/api/v1/fleet/summary

Returns aggregate statistics for the entire QuoxAgent fleet.

Example Response

json

{
  "total": 12,
  "online": 11,
  "offline": 1,
  "byStatus": {
    "healthy": 10,
    "warning": 1,
    "critical": 0
  },
  "byOs": {
    "ubuntu-22.04": 8,
    "debian-12": 3,
    "rocky-9": 1
  },
  "avgCpu": 34.2,
  "avgMemory": 52.8,
  "lastUpdated": "2025-01-25T10:30:00Z"
}

QuoxAgent Agent API

Each QuoxAgent agent exposes a local API on port 9847. These endpoints are accessible from the host where the agent is running.

Method	Endpoint	Purpose
`GET`	`/health`	Agent health check
`GET`	`/api/v1/jobs`	List pending/completed jobs
`POST`	`/api/v1/jobs`	Submit a new job
`GET`	`/api/v1/sessions`	List Claude sessions
`GET`	`/metrics`	Prometheus metrics

POST/api/v1/jobsMEDIUM RISK

Submit a job to the QuoxAgent agent. Jobs are executed in order and results are stored.

Request Body

json

{
  "type": "shell | script | file",
  "command": "string - Command to execute",
  "timeout": 300,          // Timeout in seconds
  "workdir": "/tmp",       // Working directory
  "env": {                 // Environment variables
    "KEY": "value"
  }
}

Response

json

{
  "jobId": "job-abc123",
  "status": "queued",
  "createdAt": "2025-01-25T10:30:00Z",
  "estimatedStart": "2025-01-25T10:30:05Z"
}

AEE Protocol

The Agent Envelope Exchange (AEE) protocol provides structured message passing between agents with full audit trails. Envelopes are stored on the collector.

Method	Endpoint	Purpose
`POST`	`/aee/store`	Store single envelope
`POST`	`/aee/sync`	Batch sync from browser
`GET`	`/aee/:id`	Get envelope by ID
`GET`	`/aee/conversation/:corr`	Get full conversation
`GET`	`/aee/conversations`	List all conversations
`GET`	`/aee/query`	Query with filters
`GET`	`/aee/stats`	AEE statistics

Envelope Structure

Every AEE envelope follows this structure:

AEE Envelope

{
  "v": "1",                        // Protocol version
  "id": "01JFX...",                // ULID - unique identifier
  "ts": "2025-01-25T10:30:00Z",    // ISO timestamp
  "type": "task | result | event | error | stream",
  "from": "human.adam",            // Sender address
  "to": "agent.cipher",            // Recipient address
  "intent": "quox.chat.query",  // Action intent
  "corr": "CONV_01JFX...",         // Conversation correlation ID
  "reply_to": "01JFX..." | null,   // Parent message ID
  "payload": {
    "text": "Your message here",
    // Additional data fields
  }
}

WebSocket API

Real-time updates are delivered via WebSocket connections. The Universal Agent Monitor (UAM) provides live agent session tracking.

WS/ws/agents/events

Real-time stream of agent session events. Connect to receive live updates as agents work.

Query Parameters

Parameter	Type	Description
`agent_type`	string	Filter: cli, api, local, custom (comma-separated)
`host_id`	string	Filter by host ID (comma-separated)
`session_id`	string	Filter by session ID (comma-separated)

Event Types

Session Events

session.start - New session started
session.end - Session completed
session.status - Status change

Activity Events

activity.message - User/agent message
activity.thinking - Agent reasoning
activity.tool_call - Tool invocation
activity.tool_result - Tool response

Connection Example

javascript

const ws = new WebSocket('ws://localhost:9848/ws/agents/events');

ws.onopen = () => {
  console.log('Connected to UAM');

  // Update filters dynamically
  ws.send(JSON.stringify({
    agent_types: ['cli'],
    host_ids: ['nw-web-01', 'nw-db-01']
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data.type, data.payload);
};

Plugin API

The Plugin API provides license and plugin management functionality from the browser client.

Plugin Client Usage

import {
  getLicenseStatus,
  activateLicense,
  getPlugins,
  enablePlugin,
  disablePlugin,
  requestTrialLicense
} from './services/pluginClient'

// Check license status
const license = await getLicenseStatus()
// { valid: true, tier: 'professional', expiresAt: '2026-01-25' }

// Get all plugins
const { plugins } = await getPlugins()
// [{ id: 'soc', name: 'Security Ops', enabled: true, tier: 'professional' }]

// Enable/disable plugins (requires appropriate license)
await enablePlugin('soc')
await disablePlugin('soc')

// Activate a license key
await activateLicense(licenseKeyJSON)

// Request a 30-day trial
await requestTrialLicense('Acme Corp')

Error Codes

All Quox APIs return consistent error responses. Use the error code to determine the appropriate action.

Code	HTTP Status	Description	Resolution
`INVALID_REQUEST`	400	Malformed request body	Check JSON syntax and required fields
`MISSING_FIELD`	400	Required field missing	Include all required fields
`UNAUTHORIZED`	401	Invalid or missing auth	Provide valid API key or token
`FORBIDDEN`	403	Permission denied	Check user permissions
`NOT_FOUND`	404	Resource not found	Verify endpoint path and IDs
`RATE_LIMITED`	429	Too many requests	Wait and retry with backoff
`AGENT_OFFLINE`	503	Target agent unavailable	Check agent status, retry later
`LLM_ERROR`	502	Claude API error	Check API key, retry
`TIMEOUT`	504	Request timed out	Reduce request complexity, retry

Error Response Format

json

{
  "success": false,
  "error": {
    "code": "MISSING_FIELD",
    "message": "Required field 'message' is missing",
    "field": "message",
    "docs": "/docs/api#chat-endpoint"
  },
  "requestId": "req-abc123"
}

Rate Limits

API endpoints are rate limited to ensure fair usage and system stability.

Endpoint Category	Limit	Window
Chat endpoints	60 requests	per minute
Voice endpoints	30 requests	per minute
QuoxAgent read operations	120 requests	per minute
QuoxAgent write operations	30 requests	per minute
WebSocket connections	10 connections	per client

Rate Limit Headers

Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers to track your usage.

API Reference

Quick Start

Your First API Call

Response

Quick Examples

JavaScript / Fetch

Python

Authentication

API Key Setup

Request Format

Collector API

Chat Endpoint

Request Body

Response

Text-to-Speech

Request Body

Response

Speech-to-Text

Request Body

Response

QuoxAgent Collector API

Example Response

Example Response

QuoxAgent Agent API

Request Body

Response

AEE Protocol

Envelope Structure

WebSocket API

Query Parameters

Event Types

Connection Example

Plugin API

Error Codes

Error Response Format

Rate Limits