Report agent activity

Prototype (AG-285). Reports activity observed by an agent runtime on a developer’s machine - today, Claude Code hook events.

This is telemetry from cooperating machines, not attestation. Opal can only see what a configured, consenting client chooses to send, cannot verify that a fleet is configured at all, and has no way to detect a machine that is reporting nothing. Absence of activity for an agent therefore means “nothing was reported”, never “the agent did nothing”.

The request body is either a batch envelope ({"events": [...]}), a bare JSON array of events, or a single raw Claude Code hook payload - the last so a hook can POST here directly with no relay in between.

The bearer token establishes the organization and nothing finer. No field in the payload is treated as an identity claim Opal trusts: the actor headers below are used for best-effort attribution and display only. Events that cannot be attributed to an agent are retained and surfaced as unattributed activity rather than dropped.

POST /agent-activity

Report agent activity

cURL

curl --request POST \
  --url https://api.opal.dev/v1/agent-activity \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "events": [
    {
      "hook_event_name": "<string>",
      "tool_input": {},
      "session_id": "<string>",
      "prompt_id": "<string>",
      "agent_id": "<string>",
      "agent_type": "<string>",
      "permission_mode": "<string>",
      "actor_email": "<string>",
      "opal_reported": {
        "configured_email": "<string>",
        "claude_account_email": "<string>",
        "git_email": "<string>",
        "os_user": "<string>",
        "hostname": "<string>"
      },
      "duration_ms": "<unknown>",
      "transcript_path": "<string>",
      "tool_name": "<string>",
      "mcp_server": {
        "name": "<string>",
        "source": "<string>"
      },
      "tool_use_id": "<string>",
      "cwd": "<string>",
      "timestamp": "2023-11-07T05:31:56Z"
    }
  ]
}
'

200

{
  "received": 123,
  "stored": 123,
  "attributed": 123,
  "unattributed": 123
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Opal-Actor · string

The identity the reporting client claims this activity belongs to - an email or an Anthropic user id. Unverified: a Claude Code hook payload contains no user identity, so this has to be injected by whoever deploys the hook (via the http handler's headers map and allowedEnvVars interpolation), and whoever controls the machine controls the header. Used only when the API key itself does not identify a developer. When the email belongs to a person in the organization, that person is recorded as who the activity was reported for (always as a claim), and the activity is attributed to the one Claude agent they own, if they own exactly one. The API key's own email is never treated this way: a key belongs to whoever created it, which with a shared key is not who is at the keyboard. Omitting it is valid. When an event's opal_reported object carries other emails, Opal also tries them, in the order configured_email, claude_account_email, git_email, after this header and skipping any that repeat it. The first one that resolves to an agent wins.

X-Opal-Host · string

The name of the machine that sent this request, as that machine reports it (hostname -s). Unverified: two machines can share a name, and whoever controls the machine controls the header. Stored with each event, so a reader can tell which machine reported it. When an event's own opal_reported.hostname names a different machine, this header wins and the body's value is kept beside it. Omitting it is valid.

Body

application/json

AgentActivityIngestRequest Object

Description

A batch of agent activity events.

Three body shapes are accepted: this envelope ({"events": [...]}), a bare JSON array of AgentActivityEvent, and a single AgentActivityEvent object. The last exists so a Claude Code hook can POST here directly, since a hook sends one bare payload per event and cannot wrap it.

events · object[]

Show child attributes

Response

200

application/json

A per-batch accounting of what was accepted, stored, and attributed. An organization that has agent activity turned off gets a 200 with an empty body for every body shape, so a sender does not keep the events and try again.

AgentActivityIngestResult Object

Description

What one ingest request actually did.

received and stored differ when a delivery was retried and deduplicated. attributed and unattributed sum to received rather than to stored, because attribution happens before deduplication. Unattributed events are kept, not dropped: activity Opal cannot tie to a governed agent is itself a governance finding.

received · integer · required

Events parsed out of the request body.

stored · integer · required

Rows actually written. Lower than received when a retried delivery was deduplicated on tool_use_id.

attributed · integer · required

Events that resolved to an agent in this organization.

unattributed · integer · required

Events that resolved to no agent, and are therefore visible only in the unattributed activity list. A persistently high value means the reporting clients are not sending an identity Opal can resolve.