curl https://api.bitterlog.com/api/v1/status

The evidence ledger for agent runs.

BitterLog is the append-only evidence workbench for agent-run proof. It stores raw traces, receipts, prompt/output artifacts, and annotations with stable digests so operators can move from a run summary back to the exact source record.

Account-scoped access runs through Bitter. ClickHouse-backed search is a projected read model, not the ledger itself, and the public API status tells operators when analytics is available.

Create Bitter account Read the API contract

API and CLI ingest
Post operating events, upload raw traces, or bring the receipts your agent stack already emits.
Receipts stay intact
Prompts, stdout, stderr, manifests, and annotations keep stable digests and timestamps you can inspect later.
Account-scoped beta
One Bitter account scopes evidence, receipts, and annotations without introducing a BitterLog-only login.

evidence ledger

14:03:12events ingestedPOST /api/v1/events batch=12

14:03:15receipt storedagent_runs / builder / 5468

14:03:22trace fetchedbucket object 71 body-only

14:03:30status checkedanalytics.enabled=false

events, receipts, traces, annotations

01 / CLI

Start with the trace. Then move outward.

BitterLog is optimized for the way agent systems actually behave: lots of raw logs, repeated research, and constant need to pivot from a summary back to the original evidence.

Ingest raw evidence

bitter log put --bucket agent_runs --run-id 5468 --agent builder tmp/agent-runs/builder_5468.jsonl

Preserve the original trace first. Parse later.

Inspect and pivot

bitter log list --bucket agent_runs --run-id 5468
bitter log get --bucket agent_runs --id 71 --body-only

Move from run identity to the exact bytes that explain what happened.

Check projected reads

curl https://api.bitterlog.com/api/v1/status
curl https://api.bitterlog.com/api/v1

The public API says which read paths are available. Analytics are a projected model, not the ledger.

02 / Identity

Logging built for agents, not generic app noise.

Raw agent logs

Session JSONL, stdout, stderr, prompt snapshots, rendered output, and receipts stay intact with stable digests and timestamps.

Search and analysis

Use the public API index and status to see available read paths. Projected analytics stay separate from the source ledger.

Learning surface

Attach annotations, preserve judgment, and turn recurring agent behavior into evidence you can act on.

03 / Trust

From run receipt to reviewable proof.

BitterLog keeps source evidence separate from downstream analysis. Raw evidence remains the durable ledger while projected query paths, when enabled, explain what happened without rewriting the source record.

Source record stays inspectable

Raw traces stay tied to stable digests and timestamps. Projected reads work from refs and projections, not a rewritten source of truth.

Reviewable receipts

Each run can connect request context, stdout, stderr, annotations, and deploy receipts so operators can audit the same path.

Read-only query path

When analytics is enabled, projected query surfaces explain patterns over evidence without mutating the append-only ledger.

04 / Research

Projected reads stay separate from source evidence.

Use the public API index and status to see available evidence paths. ClickHouse sits behind BitterLog as a projected read model for structured analysis when analytics is enabled; it is not the append-only source ledger.

starter moves

GET /api/v1/status
GET /api/v1
GET /api/v1/buckets/:bucket/objects
GET /api/v1/buckets/:bucket/objects/:id
POST /api/v1/annotations
GET /api/v1/analytics/patterns when analytics is enabled

bitter log tables

bucketagent_runs

identityrun_id, agent, origin, digest, observed_at

analyticsprojected ClickHouse read model when enabled

learningannotations over retained traces

05 / Access

Use one Bitter account for account-scoped evidence.

Bitter is the account authority. BitterLog remains headless-first: the CLI or a constellation service exchanges an account assertion for a short-lived credential bundle, then writes receipts under your account scope.

launch access

Start from the Bitter account bridge, then use the public API index and status route to confirm which evidence paths are available. Evidence onboarding remains request-reviewed during launch.

Create Bitter account Sign in to Bitter

Check API status

Prefer email? founders@bitterlog.com