Agents API Reference

Agent enable/disable and status management.

Disable Agent

Endpoint: POST /v1/agents/{agent_id}/disable

Prevent agent from making any API calls. Requires Agency plan or higher (kill switch feature).

Request

curl -X POST https://api.onceonly.tech/v1/agents/support_bot/disable \
  -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"reason": "suspicious_activity_detected"}'

Response

{
  "agent_id": "support_bot",
  "is_enabled": false,
  "disabled_reason": "suspicious_activity_detected",
  "disabled_at": "2025-01-15T10:30:00Z"
}

Enable Agent

Endpoint: POST /v1/agents/{agent_id}/enable

Re-enable a previously disabled agent. Requires Agency plan or higher (kill switch feature).

Request

curl -X POST https://api.onceonly.tech/v1/agents/support_bot/enable \
  -H "Authorization: Bearer once_live_xxxxxxxxxxxxx"

Response

{
  "agent_id": "support_bot",
  "is_enabled": true,
  "disabled_reason": null,
  "disabled_at": null
}

Agent Logs

Endpoint: GET /v1/agents/{agent_id}/logs Requires Pro plan or higher (agent observability feature).

Request

curl -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  "https://api.onceonly.tech/v1/agents/support_bot/logs?limit=50"

Query Parameters

limit - Results (1-500, default: 100)

Response

[
  {
    "ts": 1705322400,
    "agent_id": "support_bot",
    "tool": "send_email",
    "allowed": true,
    "decision": "executed",
    "policy_reason": "ok",
    "risk_level": "low",
    "args_hash": "a1b2c3d4",
    "spend_usd": 0.001
  }
]

Agent Metrics

Endpoint: GET /v1/agents/{agent_id}/metrics Requires Pro plan or higher (agent observability feature).

Request

curl -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  "https://api.onceonly.tech/v1/agents/support_bot/metrics?period=day"

Query Parameters

period - “hour”, “day”, or “week”

Response

{
  "agent_id": "support_bot",
  "period": "day",
  "total_actions": 450,
  "blocked_actions": 12,
  "total_spend_usd": 125.50,
  "top_tools": [
    {"tool": "send_email", "count": 400},
    {"tool": "create_ticket", "count": 50}
  ]
}