API Reference

All endpoints require Authorization: Bearer YOUR_API_KEY header. Agent-specific endpoints also require X-Agent-ID: AGENT_ID header.

POST
/api/v1/agents

Register Agent

Register a new AI agent with your organization.

Request Body

{
  "name": "My Agent",          // required
  "type": "CHATBOT",           // required: CHATBOT | WORKFLOW | ASSISTANT | SALES | SUPPORT | CONTENT | ANALYTICS | CUSTOM
  "purpose": "What it does",   // required
  "description": "Details...", // optional
  "vendor": "OpenAI",          // optional
  "model": "gpt-4",            // optional
  "riskLevel": "LIMITED",      // optional: UNCLASSIFIED | MINIMAL | LIMITED | HIGH | CRITICAL
  "externalId": "my-id-123"   // optional: your internal ID
}

Response

{
  "id": "clx...",
  "name": "My Agent",
  "status": "ACTIVE",
  "type": "CHATBOT",
  ...
}
GET
/api/v1/agents/:id/status

Check Agent Status

Poll this endpoint to check if your agent should continue running. This is how the kill switch works.

Response

{
  "id": "clx...",
  "status": "ACTIVE",        // ACTIVE | PAUSED | STOPPED | ERROR
  "shouldContinue": true,    // false = stop your agent
  "name": "My Agent"
}
POST
/api/v1/events

Log Event

Record an agent action or event. Events are hash-chained for tamper evidence.

Request Body

{
  "eventType": "ACTION",       // required: ACTION | DECISION | ERROR | WARNING | COMMUNICATION | DATA_ACCESS | ESCALATION
  "action": "What happened",   // required: human-readable description
  "category": "COMMUNICATE",   // required: READ | WRITE | COMMUNICATE | DECIDE | ESCALATE | SYSTEM
  "input": {},                 // optional: what the agent received
  "output": {},                // optional: what the agent produced
  "duration": 1200,            // optional: milliseconds
  "success": true,             // optional: default true
  "errorMessage": null         // optional: error details
}

Response

{
  "id": "clx...",
  "eventHash": "a1b2c3...",
  "previousHash": "d4e5f6...",
  "timestamp": "2026-03-01T..."
}
POST
/api/v1/decisions

Log Decision

Record an agent decision with reasoning for audit purposes.

Request Body

{
  "decision": "What was decided",     // required
  "reasoning": "Why this decision",   // optional
  "confidence": 0.95,                 // optional: 0-1
  "dataUsed": ["source1", "source2"], // optional
  "outcome": "What happened"          // optional
}

Response

{
  "id": "clx...",
  "decisionHash": "a1b2c3...",
  "timestamp": "2026-03-01T..."
}
POST
/api/v1/health

Submit Health Check

Report your agent health status. If unhealthy, the agent status may be set to ERROR.

Request Body

{
  "isHealthy": true,       // required
  "responseTime": 250,     // optional: milliseconds
  "errorRate": 1.5,        // optional: percentage
  "actionCount": 42        // optional: actions since last check
}

Response

{
  "id": "clx...",
  "isHealthy": true,
  "timestamp": "2026-03-01T..."
}