Events API

Moxxy provides real-time observability through Server-Sent Events (SSE) and a queryable audit log.

SSE Event Stream

GET /v1/events/stream

Query Parameters

Parameter	Type	Description
agent_id	string	Filter events by agent
run_id	string	Filter events by run
event_type	string	Filter by event type (comma-separated)

Example

curl -N -H "Authorization: Bearer mox_token" \
  "http://127.0.0.1:3000/v1/events/stream?agent_id=agent_abc123"

JavaScript

const eventSource = new EventSource(
  'http://127.0.0.1:3000/v1/events/stream?agent_id=agent_abc123',
);

eventSource.onmessage = (event) => {
  const envelope = JSON.parse(event.data);
  console.log(envelope.event_type, envelope.payload);
};

Event Envelope

Every event is wrapped in a standard envelope:

{
  "event_id": "evt_7f3a2b1c-...",
  "timestamp": "2025-01-15T10:00:00.123Z",
  "agent_id": "agent_abc123",
  "run_id": "run_def456",
  "sequence": 42,
  "event_type": "primitive.called",
  "payload": { ... }
}

Field	Description
event_id	UUID v7 unique identifier
timestamp	ISO 8601 timestamp
agent_id	Agent that generated the event
run_id	Run context (null for system events)
sequence	Monotonically increasing counter per run
event_type	Event category and type
payload	Event-specific data

Event Types

Moxxy emits 60+ event types across these categories:

Run Events

Event	Description
run.started	Agent run initiated
run.completed	Run finished successfully
run.failed	Run terminated with error

Message Events

Event	Description
message.user	User message received
message.assistant	Assistant response generated
message.system	System message injected

Model Events

Event	Description
model.request	LLM API call initiated
model.response	LLM response received
model.stream	Streaming token received

Primitive Events

Event	Description
primitive.called	Primitive invocation started
primitive.result	Primitive execution completed

Skill Events

Event	Description
skill.invoked	Skill execution started
skill.completed	Skill execution finished

Memory Events

Event	Description
memory.stored	Memory entry persisted
memory.recalled	Memory search executed

Vault Events

Event	Description
vault.accessed	Secret retrieved
vault.denied	Secret access denied (no grant)

Heartbeat Events

Event	Description
heartbeat.fired	Scheduled heartbeat triggered
heartbeat.created	New heartbeat registered

Sub-Agent Events

Event	Description
subagent.spawned	Sub-agent created
subagent.completed	Sub-agent finished

Security Events

Event	Description
security.violation	Security policy violated
security.redacted	Secret redacted from output

Channel Events

Event	Description
channel.message_received	Message from external channel
channel.message_sent	Message sent to external channel

Secret Redaction

All events pass through the RedactionEngine before being emitted. Any vault secret values that appear in event payloads are automatically replaced with [REDACTED]. This ensures secrets are never leaked through the event stream or audit log.

Audit Log

Query persisted events for historical analysis.

GET /v1/audit

Query Parameters

Parameter	Type	Description
agent_id	string	Filter by agent
event_type	string	Filter by type
since	string	ISO timestamp start
until	string	ISO timestamp end
limit	number	Max results (default: 100)

Response

{
  "events": [
    {
      "event_id": "evt_7f3a2b1c-...",
      "timestamp": "2025-01-15T10:00:00.123Z",
      "agent_id": "agent_abc123",
      "run_id": "run_def456",
      "event_type": "primitive.called",
      "payload": { "name": "fs.read", "args": { "path": "README.md" } }
    }
  ]
}

Required Scopes

Endpoint	Scope
GET /v1/events/stream	events:read
GET /v1/audit	events:read