# Local collector API

> Integrate with the authenticated loopback HTTP API for ingest, scans, review state, and redacted export.

Source: https://docs.agentbeam.com/agent-cli/collector-api

The collector listens on HTTP loopback, normally `http://127.0.0.1:4319`. API routes require `Authorization: Bearer TOKEN`. Studio's HTML shell is public on that origin, but its data requests are authenticated. This API is different from the remote workspace API.

## Pair an API client

Start the collector and obtain its pairing token using `beam token` in a private terminal. Supply it through your client's secret handling. A token is generated for the data directory and reused across collector restarts.

```sh
curl --fail --silent --show-error \
  -H "Authorization: Bearer $BEAM_TOKEN" \
  http://127.0.0.1:4319/health
```

Do not expose the listener publicly or point `BEAM_COLLECTOR_URL` at a remote dashboard. Browser callers must also satisfy the configured origin policy.

## Endpoint reference

| Method and path      | Request or response                                               |
| -------------------- | ----------------------------------------------------------------- |
| `GET /health`        | Collector version and retention information                       |
| `GET /state`         | Retained events, scans, reviews, and rule catalog                 |
| `GET /agents`        | Agent config/artifact existence and hook status; no file contents |
| `POST /ingest`       | A normalized JSON object, array, or NDJSON stream                 |
| `POST /v1/logs`      | OTLP/HTTP JSON; protobuf is not supported                         |
| `POST /scan`         | `{ "name", "kind", "content" }`, with kind `skill` or `mcp`       |
| `POST /review`       | `{ "id": "EVENT_ID", "reviewed": true }`                          |
| `POST /rules/reload` | Reload local custom rules; returns path, loaded count, and errors |
| `GET /export`        | Redacted event NDJSON                                             |

## Submit a scan

```sh
curl --fail --silent --show-error \
  -H "Authorization: Bearer $BEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"example.md","kind":"skill","content":"Read the project README before editing."}' \
  http://127.0.0.1:4319/scan
```

This persists through the collector and may forward to an enrolled workspace. Use `beam scan` without `--save` for an offline, non-persisted file review.

## Respect request bounds

Ingestion is limited to 2 MB and 2,000 records per request, with a 100 KB per-record limit. The scan route has a 500 KB body/content boundary. Split large imports into meaningful batches and inspect accepted, duplicate, and skipped counts instead of assuming every source line was retained.

Retention keeps the latest 10,000 events and 500 scan reports. `/state` and `/export` represent bounded history. A review toggle records an assessment marker rather than approval or enforcement.

## Diagnose authentication and delivery

For rejected tokens, check the data directory and any `BEAM_TOKEN` override. For refused connections, confirm port and service status. For browser-origin errors, explicitly configure only the required local origins. A successfully stored record may still fail remote forwarding; local ingestion and workspace delivery are separate outcomes.