Collector API Reference

HTTP endpoints exposed by the @useaop/collector server.

All endpoints are served on the same port as the dashboard (default 4317).

POST /events

Ingest a single AOP event. This is the primary endpoint the SDK sends events to.

POST /events
Content-Type: application/json

{
  "spec": "aop/1.0",
  "session_id": "sess_abc123",
  "agent_id": "my-agent",
  "sequence": 1,
  "timestamp": "2026-04-03T10:00:00.000Z",
  "type": "session.started",
  "payload": { "goal": "Summarize document" }
}

Response: 200 OK with body {"ok": true}

GET /stream

Server-Sent Events (SSE) stream of all incoming events in real time. The dashboard connects to this endpoint for live updates.

GET /stream
Accept: text/event-stream

// Response (SSE format):
data: {"spec":"aop/1.0","type":"session.started",...}

data: {"spec":"aop/1.0","type":"cognition.thought",...}

The stream stays open indefinitely. Each event is sent as a data: line with the full JSON event object. Use an EventSource or SSE client library to consume it.

GET /sessions

List all sessions, ordered by most recent activity.

GET /sessions

Response: 200 OK
{
  "sessions": [
    {
      "id": "sess_abc123",
      "agent_id": "my-agent",
      "parent_session_id": null,
      "status": "completed",
      "started_at": "2026-04-03T10:00:00.000Z",
      "ended_at": "2026-04-03T10:05:00.000Z",
      "total_steps": 24,
      "total_tokens": 4200
    }
  ]
}

GET /sessions/:id

Get a single session with all its events and alerts.

GET /sessions/sess_abc123

Response: 200 OK
{
  "session": {
    "id": "sess_abc123",
    "agent_id": "my-agent",
    "status": "completed"
  },
  "events": [
    { "sequence": 1, "type": "session.started", ... },
    { "sequence": 2, "type": "cognition.thought", ... }
  ],
  "alerts": []
}

GET /sessions/:id/export

Export a session as JSONL (newline-delimited JSON), suitable for sharing or analysis.

GET /sessions/sess_abc123/export

Response: 200 OK
Content-Type: application/x-ndjson
Content-Disposition: attachment; filename="session-sess_abc123.jsonl"

DELETE /sessions/:id

Delete a session and all its events from the local database.

DELETE /sessions/sess_abc123

Response: 200 OK
{ "ok": true }

GET /health

Health check endpoint.

GET /health

Response: 200 OK
{
  "ok": true,
  "version": "0.2.1",
  "subscribers": 1
}

Related