Event ingestion

Not every action an AI agent takes passes through Perihelium. Your LLM gateway sees the tool calls it brokers; your own application sees the policy it enforced; your router sees the budget it spent. Event ingestion lets those systems report what they observed into the same record the platform keeps for its own actions, so one detection catalogue, one audit chain and one console cover the agent's whole day.

HTTP

POST /api/v1/telemetry/events
Authorization: Bearer <api key or client-credentials token with events:write>

{ "action": "ingest.tool_invoked", "agent_id": "…", "delegating_user_id": "…",
  "tool": "crm.update_record", "outcome": "ok", "duration_ms": 412 }

A registered vocabulary

The endpoint accepts only the actions in a published vocabulary. Each is a first-class action: it has a detection decision, an audit decision and a compliance mapping, exactly like an action the platform performs itself.

Action	Report when
`ingest.tool_invoked`	the agent called a tool, with the outcome
`ingest.tool_refused`	your system refused a tool call and why (a short code)
`ingest.policy_violation`	the agent's request broke a policy your system enforces
`ingest.injection_suspected`	your system judged an input to be a prompt-injection attempt
`ingest.budget_exceeded`	the agent exhausted a budget your system meters

The vocabulary grows by a release, never by a caller's string: an unknown action is refused with 422. The console lists the vocabulary with the schema of each action, so an integrator can read what to send without leaving the product.

Metadata only, enforced by schema

Every action has a closed schema: identifiers, enumerated outcomes, bounded short codes, counts and durations. There is no free-text field of unbounded length, and a field whose name denotes content — prompt, completion, messages, content, body, input, output — is refused by name. A client that tries to send a transcript gets a 422, never silent storage. The platform keeps the record that an agent acted; what the model was told or said stays in your systems, under your retention.

The report is checked against your organization

The caller is an API key or a client-credentials token of your organization holding events:write (API keys).
Every identifier in a report — the agent, the delegating person — must exist in the caller's organization. A reference into any other organization is refused, not stored.
The platform assigns severity and actor. The envelope records the reporting client as the actor and the agent as the subject, marked source=external, so a detection or an auditor can always tell an asserted fact from one the platform observed itself.
Volume is bounded: a per-organization rate cap answers 429 when exceeded, and audited actions carry a daily ceiling, so an integrator cannot grow the append-only audit store without bound.

What happens next

An ingested action is an event like any other (Security monitoring): each action in the vocabulary carries a detection decision, so the rules in the agents family evaluate it, it appears in the agent's record and in the audit chain, and your SIEM exporter ships it. The one thing the platform does with it that it would not do with its own observation is label it as reported.

The SDK report

The SDK's anomaly report (POST /api/v1/telemetry/sdk, sdk.anomaly_reported) is the same mechanism for your application code: a client that believes it has seen something wrong says so, and the platform records, scores and routes it with the same rules.