Ingest API

For agents the collector can't read. This is the same REST API the collector itself uses — there is no second, privileged path.

Authentication

Every endpoint takes a collector token as a bearer token. Create one under Settings → Collector tokens. Tokens are scoped to one workspace; the server resolves the workspace from the token, so no org id is sent in the body.

Authorization: Bearer al_...

A missing, invalid or revoked token returns 401.

GET /api/ingest — verify a token

Checks a token and URL before sending any data. This is what agentlens connect calls.

curl -sS https://agentlensapp.sinaispace.com/api/ingest \
  -H "Authorization: Bearer al_..."

{ "ok": true, "version": 1, "orgId": "..." }

version is the ingest contract version the server speaks. Send that same value in your payloads.

POST /api/ingest — send sessions

The body is a JSON payload describing one machine and the sessions read from it. Each session carries its events — messages, tool calls and errors — with token counts and cost.

curl -sS -X POST https://agentlensapp.sinaispace.com/api/ingest \
  -H "Authorization: Bearer al_..." \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "machine": { "hostname": "...", "os": "darwin" },
    "sessions": [
      {
        "externalId": "...",
        "agent": { "kind": "claude-code", "displayName": "Claude Code" },
        "events": [
          {
            "seq": 1,
            "kind": "message",
            "role": "assistant",
            "model": "claude-opus-5",
            "inputTokens": 1200,
            "outputTokens": 340
          }
        ]
      }
    ]
  }'

version and machine are required. Event kind is one of message, tool_call or error. Token count and cost fields default to zero when omitted.

On success the response is { "ok": true, ... } with per-batch write counts.

Responses and limits

400 — body isn't valid JSON, or fails contract validation. The message names the problem. Sending a version the server doesn't speak lands here too.
401 — invalid or revoked token.
413 — payload over 32 MB. Split the batch across more requests.
500 — the batch was not accepted and retrying is safe.

Retries are safe at every status. The server deduplicates on session and event identity, so re-sending a batch never double-counts.

POST /api/config — apply agentlens.yml

Applies a mapping file that assigns repositories to projects and teams. It takes the same collector token, because the file lives in the repo the collector is already reading — a second credential on every developer machine would buy nothing.

curl -sS -X POST https://agentlensapp.sinaispace.com/api/config \
  -H "Authorization: Bearer al_..." \
  --data-binary @agentlens.yml

Limit is 256 KB; a larger file is a mistake rather than a big configuration.

GET /api/status — workspace totals

What agentlens status reports: counts of agents, projects and teams, plus month-to-date sessions, spend and budget for the whole workspace.

curl -sS https://agentlensapp.sinaispace.com/api/status \
  -H "Authorization: Bearer al_..."

Self-hosted

Replace the host with your own install and everything above is identical — see self-hosting. For the CLI route instead, start at the docs.