DEV Community

Anton Illarionov
Anton Illarionov

Posted on

ODEI API Reference: Complete Developer Guide

#agents #documentation #api #ai

ODEI API Reference: Complete Guide for Developers

Complete reference for ODEI's constitutional world model API.

Base URL 

https://api.odei.ai
Enter fullscreen mode Exit fullscreen mode

Authentication 

Authorization: Bearer YOUR_TOKEN
Enter fullscreen mode Exit fullscreen mode

Get your token at https://api.odei.ai/integrate/

Endpoints

GET /api/v2/health

Public. Returns API status and world model statistics.

curl https://api.odei.ai/api/v2/health
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "ok": true,
  "data": {
    "service": "odei-api-v2",
    "status": "healthy",
    "version": "2.0.0",
    "graph": {
      "node_count": 91,
      "domain_counts": {
        "FOUNDATION": 25,
        "VISION": 12,
        "STRATEGY": 16,
        "TACTICS": 8,
        "EXECUTION": 11,
        "TRACK": 19
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

GET /api/v2/world-model/live

Returns the full world model graph state.

curl -H "Authorization: Bearer TOKEN" \
  https://api.odei.ai/api/v2/world-model/live
Enter fullscreen mode Exit fullscreen mode

POST /api/v2/world-model/query

Query the knowledge graph with structured queries.

curl -X POST \
  -H "Authorization: Bearer TOKEN" \
  -d '{"queryType": "search", "searchTerm": "AI safety"}' \
  https://api.odei.ai/api/v2/world-model/query
Enter fullscreen mode Exit fullscreen mode

Query types: schema, domain, search, traverse

POST /api/v2/guardrail/check

Constitutional validation before agent actions.

curl -X POST \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "action": "transfer 500 USDC to 0x...",
    "severity": "high",
    "context": {"requester": "trading_agent"}
  }' \
  https://api.odei.ai/api/v2/guardrail/check
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "verdict": "ESCALATE",
  "score": 45,
  "layers": [
    {"layer": "immutability", "result": "PASS"},
    {"layer": "provenance", "result": "WARN", "note": "Unknown wallet"},
    {"layer": "constitutional", "result": "WARN", "note": "Exceeds daily limit"}
  ],
  "reasoning": "Transfer to unverified wallet exceeds daily limit."
}
Enter fullscreen mode Exit fullscreen mode

Severity options: low, medium, high, critical
Verdict options: APPROVED, REJECTED, ESCALATE

SDKs

Python (unofficial):

import requests

class ODEI:
    def __init__(self, token):
        self.token = token
        self.base = "https://api.odei.ai/api/v2"

    def check(self, action, severity="medium"):
        return requests.post(
            f"{self.base}/guardrail/check",
            headers={"Authorization": f"Bearer {self.token}"},
            json={"action": action, "severity": severity}
        ).json()
Enter fullscreen mode Exit fullscreen mode

MCP (works without token for basic usage):

{"mcpServers": {"odei": {"command": "npx", "args": ["@odei/mcp-server"]}}}
Enter fullscreen mode Exit fullscreen mode

Rate Limits

  • Free tier: 100 requests/day
  • Authenticated: Higher limits (contact api.odei.ai/integrate/)

Virtuals ACP (no auth needed)

Call ODEI without an API key via Virtuals Protocol ACP:

  • Agent #3082: app.virtuals.io/acp/agent-details/3082
  • Services from $0.05/call

Support

Top comments (0)