Documentation

Quickstart

Get your AI agent sending events to Canary in under 60 seconds.

1. Register your agent

Your agent can self-register by calling the registration endpoint:

curl -X POST https://canary.bot/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "platform": "custom"}'

Save the api_key from the response — you'll need it for all requests.

Self-hosting? Replace https://canary.bot with your deployment's base URL.

2. Send events

Send events to track your agent's activity:

curl -X POST https://canary.bot/api/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{ 
    "type": "tool_call",
    "session_id": "session_123",
    "payload": {
      "tool": "web_search",
      "input": "weather in NYC"
    }
  }'

3. Claim your agent

The registration response includes a claim_url. Open it in your browser and sign in with GitHub to link the agent to your account.

The same host replacement applies here if you run your own stack.

OpenClaw Integration

Canary has native support for OpenClaw agents. Just install the hook and you're done.

Automatic setup

Tell your OpenClaw agent to join Canary:

Read https://canary.bot/skill.md and follow the instructions

Manual setup

Run the install script:

curl -fsSL https://canary.bot/install | bash

This installs the Canary hook and configures your OpenClaw agent automatically.

API Reference

POST/api/agents/register

Request body

{
  "name": "string (required)",
  "platform": "openclaw | claude-code | custom",
  "description": "string (optional)"
}

POST/api/ingest

Send events (requires API key)

Headers

X-API-Key: your_api_key

Request body

{
  "type": "tool_start | tool_result | message_in | message_out | error | cost",
  "session_id": "string (optional)",
  "payload": {
    "tool": "string (for tool events)",
    "tool_call_id": "string (links start/result)",
    "input": "any",
    "output": "any",
    "status": "success | error | timeout",
    "tokens_in": "number",
    "tokens_out": "number",
    "model": "string",
    "cost_usd": "number",
    "duration_ms": "number (auto-calculated)",
    "error": "string (for errors)"
  }
}

GET/api/events

Retrieve events (requires auth or API key)

Query parameters

agent_id: Filter by agent
session_id: Filter by session
type: Filter by event type
since: ISO timestamp
limit: Max results (default 100)

GET/api/stats

Get aggregated statistics

Query parameters

agent_id: Filter by agent
period: 24h | 7d | 30d

GET/api/agents/me

Agent self-query: check your own stats (requires API key)

Query parameters

period: 1h | 24h | 7d | 30d (default: 24h)

Response

{
  "agent": { "id", "name", "status" },
  "stats": {
    "total_events", "total_cost", "tokens_in",
    "tokens_out", "error_rate", "session_count"
  },
  "plan": {
    "events_this_month", "events_limit",
    "events_remaining", "events_percentage"
  },
  "alerts": ["warnings if any"]
}

GET/api/events?format=csv

Export events as CSV (requires auth or API key)

Query parameters

format: json (default) | csv
agent_id: Filter by agent
session_id: Filter by session
since: ISO timestamp
limit: Max results (default 10000 for CSV)

GET/api/sessions/{id}

Get detailed session replay data (requires auth)

Response

{
  "session": {
    "id", "agent_name", "started_at", "ended_at",
    "duration_formatted", "child_sessions"
  },
  "stats": {
    "total_events", "total_cost", "tokens_total",
    "tool_calls", "unique_tools", "messages", "errors"
  },
  "events": [...],
  "conversation": [...]  // Simplified chat view
}

Event Types

▶️

tool_start

When your agent begins using a tool. Include tool_call_id to correlate with result.

✅

tool_result

When a tool completes. Duration auto-calculated if tool_call_id matches a tool_start.

⚡

tool_call

Legacy: single event for tool start+result combined. Still supported.

📨

message_in

Messages received by your agent

📤

message_out

Messages sent by your agent

❌

error

Errors and exceptions

💰

cost

API cost events (tokens, model usage)

Alerts

Canary automatically detects anomalies and sends alerts. Available on Pro and Team plans.

Error Rate Alerts

Triggered when error rate exceeds 10% over a 5-minute window.

Cost Spike Alerts

Triggered when a single event costs more than $1.00.

Notification Channels

Alerts can be sent to Discord webhooks or email. Configure in your environment variables.

Rate Limits & Plans

Limit	Free	Pro	Team
Agents	2	Unlimited	Unlimited
Events per month	50K	200K	500K
Data retention	7 days	30 days	90 days
Team members	2	Unlimited	Unlimited
Alerts	❌	✅	✅
API access	❌	✅	✅

Ready to get started?

Start monitoring your AI agents in under a minute.