Events API

The Events API is the primary ingestion endpoint. All agent actions flow through POST /v1/events.

Send an event

POST /v1/events

Auth: API Key (X-API-Key header)

Request body

{
  "eventId": "evt_001",
  "runId": "run_001",
  "agentId": "my-agent",
  "timestamp": "2026-03-19T10:00:00Z",
  "eventType": "tool.called",
  "status": "pending",
  "metadata": {
    "toolCallId": "tc_001",
    "toolName": "deploy",
    "inputPayload": {
      "environment": "production",
      "service": "api"
    },
    "actionHint": "deploy"
  }
}

Field	Type	Required	Description
eventId	string	Yes	Unique event identifier
runId	string	Yes	Run this event belongs to
agentId	string	Yes	Agent that generated this event
timestamp	ISO 8601	Yes	When the event occurred
eventType	string	Yes	One of the EventType values
status	string	No	Event status
metadata	object	No	Event-specific data (see below)

Metadata by event type

run.started

{
  "metadata": {
    "task": "Fix authentication bug",
    "model": "claude-sonnet-4-20250514",
    "reason": "Fix the session expiry bug reported in JIRA-1234",
    "agentContext": {
      "goal": "Fix the session expiry bug",
      "reasoning": "Sessions expire prematurely after re-login",
      "conversationId": "conv_abc123"
    }
  }
}

tool.called

{
  "metadata": {
    "toolCallId": "tc_001",
    "toolName": "create_pull_request",
    "inputPayload": {
      "repo": "my-org/api",
      "title": "Add caching layer"
    },
    "actionHint": "pr_create",
    "reason": "Opening a PR with the caching layer for review",
    "agentContext": {
      "goal": "Improve API response times",
      "reasoning": "Adding a Redis caching layer will reduce DB load by ~60%"
    }
  }
}

tool.completed

{
  "metadata": {
    "toolCallId": "tc_001",
    "outputPayload": {
      "prNumber": 42,
      "url": "https://github.com/..."
    }
  }
}

Response

{
  "eventId": "evt_001",
  "runId": "run_001",
  "processed": true,
  "toolCallStatus": "awaiting_approval",
  "reason": "Tool call deploy requires human approval per policy \"Require approval for production deploys\".",
  "approvalId": "ap_001",
  "approvalUrl": "http://localhost:4200/approvals?focus=ap_001",
  "matchedPolicies": [
    {
      "policyId": "pol_123",
      "policyName": "Require approval for production deploys",
      "action": "require_approval",
      "reason": "Tool call deploy requires human approval per policy \"Require approval for production deploys\"."
    }
  ]
}

The toolCallStatus field is only present for tool.called events and indicates the policy decision:

• allowed — no policy matched, or all matched policies allow
• blocked — a blocking policy matched
• awaiting_approval — a policy requires human approval

Examples

Start a run

curl -X POST http://localhost:3000/v1/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: acl_your_key" \
  -d '{
    "eventId": "evt_001",
    "runId": "run_001",
    "agentId": "my-agent",
    "timestamp": "2026-03-19T10:00:00Z",
    "eventType": "run.started",
    "status": "started",
    "metadata": { "task": "Deploy hotfix" }
  }'

Track a tool call

curl -X POST http://localhost:3000/v1/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: acl_your_key" \
  -d '{
    "eventId": "evt_002",
    "runId": "run_001",
    "agentId": "my-agent",
    "timestamp": "2026-03-19T10:00:01Z",
    "eventType": "tool.called",
    "status": "pending",
    "metadata": {
      "toolCallId": "tc_001",
      "toolName": "deploy",
      "inputPayload": { "environment": "production" },
      "actionHint": "deploy"
    }
  }'

Complete a run

curl -X POST http://localhost:3000/v1/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: acl_your_key" \
  -d '{
    "eventId": "evt_003",
    "runId": "run_001",
    "agentId": "my-agent",
    "timestamp": "2026-03-19T10:00:10Z",
    "eventType": "run.completed",
    "status": "completed"
  }'

tip

Use the SDK instead of raw HTTP when possible. The SDK handles event IDs, timestamps, retries, and error handling automatically.