API Reference

The Hermes Ouroboros API lets you submit queries to the multi-agent council and retrieve results programmatically.

Base URL: https://hermes-ouroboros.online

Authentication

Three auth methods are supported:

To get an API key, log in to the dashboard and create one in the API Keys section.

Endpoints

POST /api/query

Submit a question to the council. Returns the full verdict with all agent responses.

curl -X POST https://hermes-ouroboros.online/api/query \
  -H "X-API-Key: ho_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the tradeoffs of proof-of-stake vs proof-of-work?", "mode": "default"}'

{
  "runtime": { "backend": "openai_compatible", "provider": "NousResearch", "model": "Hermes-4-70B" },
  "result": {
    "session_id": "abc-123",
    "query": "What are the tradeoffs...",
    "confidence_score": 87,
    "conflict_detected": true,
    "arbiter_verdict": "The Arbiter's synthesized analysis...",
    "agent_responses": {
      "advocate": "...", "skeptic": "...", "oracle": "...",
      "contrarian": "...", "arbiter": "..."
    }
  }
}

POST /api/query/stream

Same as /api/query but returns Server-Sent Events (SSE) as each agent completes.

curl -N -X POST https://hermes-ouroboros.online/api/query/stream \
  -H "X-API-Key: ho_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "Explain zero-knowledge proofs", "mode": "default"}'

# Events:
# data: {"type":"agent_complete","role":"advocate","duration_seconds":3.2,"preview":"..."}
# data: {"type":"agent_complete","role":"skeptic",...}
# ...
# data: {"type":"final","result":{...},"runtime":{...}}

GET /api/health

Health check. No auth required.

{"status": "ok"}

GET /api/loop/status

Returns the Ouroboros DPO training loop status. No auth required.

GET /api/sessions

List your sessions (requires auth). Supports query params: limit, q, backend, conflict.

GET /api/sessions/{id}

Get a full session by ID (requires auth, scoped to owner unless admin).

API Keys

POST /api/keys

Create a new API key (requires session auth, max 5 per user).

curl -X POST https://hermes-ouroboros.online/api/keys \
  -H "Cookie: hermes_session=..." \
  -H "X-CSRF-Token: ..." \
  -H "Content-Type: application/json" \
  -d '{"label": "my-app"}'

# Response: {"key_id": "abc", "api_key": "ho_xxx...", "label": "my-app"}

Important: The full API key is only shown once at creation time. Store it securely.

GET /api/keys

List your API keys (prefix, label, usage stats).

DELETE /api/keys/{key_id}

Revoke an API key.

Rate Limits

Python Example

import requests

API_KEY = "ho_your_key_here"
BASE = "https://hermes-ouroboros.online"

resp = requests.post(f"{BASE}/api/query", json={
    "query": "Should Ethereum switch to a different VM?",
    "mode": "default",
}, headers={"X-API-Key": API_KEY})

data = resp.json()
print(f"Confidence: {data['result']['confidence_score']}")
print(f"Verdict: {data['result']['arbiter_verdict'][:200]}...")

JavaScript Example

const resp = await fetch('https://hermes-ouroboros.online/api/query', {
  method: 'POST',
  headers: { 'X-API-Key': 'ho_your_key_here', 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: 'Explain DeFi composability risks', mode: 'default' }),
});
const { result } = await resp.json();
console.log('Verdict:', result.arbiter_verdict);

Built for the NousResearch Hermes Agent Hackathon · GitHub