← DocumentationAPI Reference

Events API

Report agent activity and query the immutable activity log. Activity data feeds trust score computation.

POST /activity/report

Report a single activity event for an agent. Requires API key authentication with activity:report or write permission.

Request
POST /api/v1/activity/report
Authorization: Bearer asn_live_k1a2b3c4...
Content-Type: application/json

{
  "asn": "ASN-2026-0384-7721-A",
  "event_type": "task_completed",
  "severity": "info",
  "metadata": {
    "task_id": "scan-42",
    "duration_ms": 1230,
    "result": "3 vulnerabilities found"
  }
}
asn required — The agent's ASN
event_type required — Event type (max 50 chars). Common types:
task_completed — Agent completed a task successfully
task_failed — Agent failed to complete a task
error — Agent encountered an error
incident — Safety or reliability incident
startup — Agent came online
shutdown — Agent went offline
severity optional — info (default), warning, error, critical
metadata optional — Arbitrary JSON object with event details
Response — 201 Created
{
  "id": "event-uuid-...",
  "agent_id": "agent-uuid-...",
  "event_type": "task_completed",
  "severity": "info",
  "metadata": {
    "task_id": "scan-42",
    "duration_ms": 1230,
    "result": "3 vulnerabilities found"
  },
  "reported_by": "operator",
  "created_at": "2026-03-18T14:30:00Z"
}
Error Codes
400 VALIDATION_ERROR — Invalid input
401 UNAUTHORIZED — Invalid or missing API key
403 FORBIDDEN — Insufficient permissions or not agent owner
404 NOT_FOUND — Agent not found
410 AGENT_DEACTIVATED — Cannot report for deactivated agents

POST /activity/report/batch

Report multiple activity events in a single request. Same authentication and permissions as the single report endpoint.

Request
POST /api/v1/activity/report/batch
Authorization: Bearer asn_live_k1a2b3c4...
Content-Type: application/json

{
  "events": [
    {
      "asn": "ASN-2026-0384-7721-A",
      "event_type": "task_completed",
      "metadata": { "task_id": "scan-42" }
    },
    {
      "asn": "ASN-2026-0384-7721-A",
      "event_type": "task_completed",
      "metadata": { "task_id": "scan-43" }
    }
  ]
}

GET /agents/:asn/activity

Query the activity log for an agent. Public endpoint — limited to the 50 most recent events. Authenticated owner access returns full history with pagination.

Request
GET /api/v1/agents/ASN-2026-0384-7721-A/activity?type=task_completed&page=1&per_page=20
type — Filter by event type
from — ISO 8601 start date
to — ISO 8601 end date
page — Page number (default: 1)
per_page — Results per page (default: 20, max: 50)
Response — 200 OK
{
  "data": [
    {
      "id": "event-uuid-...",
      "event_type": "task_completed",
      "severity": "info",
      "metadata": {
        "task_id": "scan-42",
        "duration_ms": 1230
      },
      "reported_by": "operator",
      "created_at": "2026-03-18T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 67891,
    "total_pages": 3395
  }
}

Activity logs are immutable. Once written, they cannot be modified or deleted. This ensures trust scores are computed from tamper-proof data.

← Trust Scores APIVerification API →