# Capless documentation (all pages)

> Capless is tiny, agent-native web analytics and session replay (one script tag: 2 KB analytics, 1.7 KB lazily loaded replay) on a headless data backend: append-only streams, CEL functions and ClickHouse materializations, with an HTTP API, an MCP server and a signup API that agents can call directly.

<!-- https://capless.sh/docs/index.md -->

# Capless documentation

Capless is analytics infrastructure for software that is written, run and queried by AI agents. It has two halves that share one data model:

* **Web analytics + session replay**: one script tag. 2.0 KB (brotli) for analytics; session replay is a separate 1.7 KB chunk loaded only for sampled sessions. No cookies.
* **A headless data backend**: three primitives behind one HTTP API at `https://api.capless.sh/v1`.
  1. **Streams**: durable, ordered, append-only collections of JSON records.
  2. **Functions**: deterministic, bounded [CEL](https://cel.dev) expressions for validation, filtering, mapping and erasure.
  3. **Materializations**: independently maintained copies of streams in ClickHouse, configured with real SQL.

Web analytics events land in a stream called `web.events` and replays in `web.replay`, so everything below applies to your web data too.

## Start here

* [Quickstart](https://capless.sh/docs/quickstart.md): account, snippet, first query. Five minutes.
* [For agents](https://capless.sh/docs/agents.md): the signup API, MCP and a curl-only flow an agent can run end to end.
* [MCP server](https://capless.sh/docs/mcp.md): connect Claude Code, Cursor or any MCP client.

## Reference

* [Web SDK](https://capless.sh/docs/web-sdk.md): snippet, JavaScript API, collected fields, replay privacy.
* [Streams & cursors](https://capless.sh/docs/streams.md): batches, positions, durability, idempotency.
* [Reading & change feed](https://capless.sh/docs/reading.md): `/read`, `/changes`, pagination and limits.
* [Time seeking](https://capless.sh/docs/time-seeking.md): jump to a commit time with `/locate`.
* [CEL functions](https://capless.sh/docs/cel.md): variables, number and regex rules, examples.
* [Erasures & GDPR](https://capless.sh/docs/erasures.md): delete by predicate, everywhere.
* [ClickHouse materializations](https://capless.sh/docs/materializations.md): tables, sources, lineage, status.
* [API reference](https://capless.sh/docs/api.md): every endpoint group; full [OpenAPI spec](https://capless.sh/openapi.yaml).
* [Limits & quotas](https://capless.sh/docs/limits.md) · [Security & privacy](https://capless.sh/docs/security.md)

## Conventions

* Base URL `https://api.capless.sh`. All endpoints are under `/v1`.
* Authenticate with your project API key: `authorization: Bearer cpl_…`.
* Bodies are JSON. Timestamps are UTC ISO 8601 with millisecond precision.
* IDs (`str_`, `ent_`, `era_`, `mat_`, `src_`) and cursors (`cur_`) are opaque strings.
* Errors are `{"error": {"code", "message", "details"?, "requestId"}}` with a stable `code`.
* Lists are paginated with `limit` + `pageToken` → `{data, nextPageToken}`.

Every page of these docs is also available as Markdown: append `.md` to its URL (this page: [/docs/index.md](https://capless.sh/docs/index.md)). [/llms.txt](https://capless.sh/llms.txt) indexes them, and [/llms-full.txt](https://capless.sh/llms-full.txt) is everything in one file.

---

<!-- https://capless.sh/docs/quickstart.md -->

# Quickstart

From zero to a SQL-free answer about your traffic in five minutes. You need an email address and a website you can edit.

## 1. Create an account

Enter your email on the [home page](https://capless.sh/#signup) or call the signup API yourself:

```sh
curl -s https://api.capless.sh/v1/signup \
  -d '{"email":"you@example.com","siteName":"my-site","allowedOrigins":["https://example.com"]}'
```

The response contains everything you need. Save `apiKey`: it is shown once.

```json
{
  "user": { "id": "…", "email": "you@example.com" },
  "project": { "id": "prj_…", "name": "…", "plan": "trial", "trialEndsAt": "…" },
  "apiKey": "cpl_…",
  "site": { "key": "cs_…", "snippet": "<script async src=\"https://c.capless.sh/c.js\" data-site=\"cs_…\"></script>" },
  "dashboardUrl": "https://app.capless.sh/…",
  "mcp": { "url": "https://mcp.capless.sh/mcp", "headers": { "Authorization": "Bearer cpl_…" } }
}
```

* `dashboardUrl` is a one-time sign-in link, valid for 15 minutes. Later, sign in at [app.capless.sh/login](https://app.capless.sh/login).
* We send a verification email. Your 14-day trial starts now, no credit card.
* `409 email_taken` means you already have an account: [log in](https://app.capless.sh/login) instead.

## 2. Add the snippet

Paste the snippet into every page, right before `</head>`:

```html
<script async src="https://c.capless.sh/c.js" data-site="cs_…"></script>
```

That's it: pageviews, clicks, form submits, errors, Web Vitals and session replays are collected automatically. Single-page apps are detected (`pushState`, back/forward). See [Web SDK](https://capless.sh/docs/web-sdk.md) for custom events and user identification.

## 3. Check that data arrives

Open your site in a browser, then read the newest events:

```sh
export CAPLESS_API_KEY=cpl_…
curl -s https://api.capless.sh/v1/streams/web.events -H "authorization: Bearer $CAPLESS_API_KEY"
# → {"name":"web.events","entryCount":3,"lastCommittedAt":"…", …}

curl -s https://api.capless.sh/v1/streams/web.events/read -H "authorization: Bearer $CAPLESS_API_KEY" \
  -d '{"filter":"entry.type == \"pageview\"","map":"{\"path\": entry.path, \"at\": entry.timestamp}"}'
```

Or open the dashboard at [app.capless.sh](https://app.capless.sh) to watch sessions and replays.

## 4. Ask questions

* **From your coding agent**: [connect the MCP server](https://capless.sh/docs/mcp.md) and ask "which pages had the most rage clicks this week?".
* **With CEL**: filter and reshape events server-side on `/read` ([CEL functions](https://capless.sh/docs/cel.md)).
* **With SQL** (Team plan): [materialize](https://capless.sh/docs/materializations.md) `web.events` into ClickHouse and run real SQL.

## Track your own events

```js
capless("track", "checkout_started", { plan: "pro" });
capless("identify", "user_42", { email: "jane@example.com" });
```

Custom events are `type: "custom"` records with `name` and `properties` in the same `web.events` stream.

---

<!-- https://capless.sh/docs/agents.md -->

# For agents

Capless is built to be set up and operated by coding agents. Everything a human can do in the dashboard, an agent can do with one HTTP API or the MCP server, and every docs page is plain Markdown.

## The one-liner

Tell your coding agent:

```text
Add Capless analytics to this site. Instructions: https://capless.sh/llms.txt
```

The agent follows [/AGENTS.md](https://capless.sh/AGENTS.md): create an account with the signup API, add the snippet, verify that events arrive, and hand you the dashboard link.

## Machine-readable docs

| URL | What |
|---|---|
| [/llms.txt](https://capless.sh/llms.txt) | Index in [llmstxt.org](https://llmstxt.org) format, linking every page as Markdown |
| [/llms-full.txt](https://capless.sh/llms-full.txt) | All docs in one file |
| `/docs/<page>.md` | Any docs page as Markdown, e.g. [/docs/cel.md](https://capless.sh/docs/cel.md) |
| [/AGENTS.md](https://capless.sh/AGENTS.md) | Install instructions an agent can follow verbatim |
| [api.capless.sh/v1/openapi.yaml](https://api.capless.sh/v1/openapi.yaml) | OpenAPI 3.1 spec |
| `GET /v1/functions` | The CEL environment: variables per context, limits, number and regex rules |

## Signup API

`POST https://api.capless.sh/v1/signup` creates a user, a project on the 14-day trial, an API key and (with `siteName`) a web analytics site, in one call. No authentication.

| Field | Type | |
|---|---|---|
| `email` | string, required | The human's email. A verification email is sent to it. |
| `password` | string, optional | Omit it to sign in with emailed links only. |
| `projectName` | string, optional | |
| `siteName` | string, optional | Creates a site and returns its snippet. |
| `allowedOrigins` | string[], optional | Origins allowed to send events for the site, e.g. `["https://example.com"]`. |

```sh
curl -s https://api.capless.sh/v1/signup \
  -d '{"email":"jane@example.com","projectName":"acme","siteName":"acme.com","allowedOrigins":["https://acme.com"]}'
```

`201 Created`:

```json
{
  "user": { "id": "…", "email": "jane@example.com" },
  "project": { "id": "prj_…", "name": "acme", "plan": "trial", "trialEndsAt": "…" },
  "apiKey": "cpl_…",
  "site": { "key": "cs_…", "snippet": "<script async src=\"https://c.capless.sh/c.js\" data-site=\"cs_…\"></script>" },
  "dashboardUrl": "https://app.capless.sh/…",
  "mcp": { "url": "https://mcp.capless.sh/mcp", "headers": { "Authorization": "Bearer cpl_…" } }
}
```

* `apiKey` is shown once. Store it where the project keeps secrets (e.g. `.env` as `CAPLESS_API_KEY`); never commit it and never put it in client-side code. The site key `cs_…` is public and write-only, so it is safe in HTML.
* `dashboardUrl` is a one-time sign-in link valid for 15 minutes. Give it to the human.
* `409 email_taken`: the human already has an account. Ask them for an API key from [the dashboard](https://app.capless.sh/login) instead of creating another account.
* `429 rate_limited`: wait and retry later; do not loop.

## End-to-end with curl

No CLI, no SDK. Replace the email and origin.

```sh
# 1. Account + site
curl -s https://api.capless.sh/v1/signup \
  -d '{"email":"jane@example.com","siteName":"acme.com","allowedOrigins":["https://acme.com"]}' > capless.json
export CAPLESS_API_KEY=$(node -p 'require("./capless.json").apiKey')
node -p 'require("./capless.json").site.snippet'    # paste before </head>
node -p 'require("./capless.json").dashboardUrl'    # give to the human

H="authorization: Bearer $CAPLESS_API_KEY"

# 2. After the site is loaded in a browser: events arrived?
curl -s https://api.capless.sh/v1/streams/web.events -H "$H"          # entryCount > 0
curl -s https://api.capless.sh/v1/streams/web.events/read -H "$H" -d '{"limitResultEntries":5}'

# 3. Your own data: a stream with a validator, an idempotent insert, a filtered read
curl -s https://api.capless.sh/v1/streams -H "$H" -d '{"name":"orders","validator":"entry.amount >= 0"}'
curl -s https://api.capless.sh/v1/streams/orders/entries -H "$H" \
  -d '{"idempotencyKey":"import-2026-10-30","entries":[{"user":"u1","amount":42},{"user":"u2","amount":7}]}'
curl -s https://api.capless.sh/v1/streams/orders/read -H "$H" -d '{"filter":"entry.amount > 10"}'

# 4. GDPR: erase one user everywhere
curl -s https://api.capless.sh/v1/streams/web.events/erasures -H "$H" -d '{"filter":"entry.userId == \"user_42\""}'
```

Delete `capless.json` once the key is stored safely.

## MCP

The signup response includes a ready-made MCP config. Install it for Claude Code:

```sh
claude mcp add --transport http capless https://mcp.capless.sh/mcp --header "Authorization: Bearer cpl_…"
```

Then call the `get_started` tool. See [MCP server](https://capless.sh/docs/mcp.md) for other clients and the full tool list.

## Rules of thumb for agents

* Retry writes with the same `idempotencyKey`; a retry returns the original result with `duplicate: true`.
* Read with cursors, not offsets. Persist `nextCursor`; it never skips or repeats.
* Dry-run CEL with `POST /v1/functions/evaluate` before using it on real data.
* Errors carry a stable `code`; branch on it, not on the message.

---

<!-- https://capless.sh/docs/mcp.md -->

# MCP server

Capless speaks the [Model Context Protocol](https://modelcontextprotocol.io), so Claude Code, Cursor and any MCP client can set up tracking, read your data and run SQL for you.

* URL: `https://mcp.capless.sh/mcp` (Streamable HTTP)
* Auth: header `Authorization: Bearer cpl_…` (your project API key)

## Install

Claude Code:

```sh
claude mcp add --transport http capless https://mcp.capless.sh/mcp --header "Authorization: Bearer cpl_…"
```

Cursor (`.cursor/mcp.json`), and most other clients:

```json
{
  "mcpServers": {
    "capless": {
      "url": "https://mcp.capless.sh/mcp",
      "headers": { "Authorization": "Bearer cpl_…" }
    }
  }
}
```

No API key yet? The [signup API](https://capless.sh/docs/agents.md#signup-api) returns one, together with this exact config in `mcp`. Keep the key out of version control: use your client's user-level config or an environment variable.

## Tools

| Tool | What it does |
|---|---|
| `get_started` | Start here: what is set up in the project and what to do next |
| `list_sites` | Web analytics sites and their snippets |
| `create_site` | Create a site (`name`, `allowedOrigins`, `replaySampleRate`) |
| `list_streams` | Streams with entry counts and heads |
| `create_stream` | Create a stream with an optional CEL validator |
| `insert_entries` | Insert a batch atomically (idempotent with a key) |
| `read_stream` | Read entries with CEL `filter`/`map`, cursor pagination |
| `locate` | Find the cursor for a commit time |
| `erase_entries` | Erase entries matching a CEL predicate |
| `list_materializations` | ClickHouse materializations |
| `create_materialization` | Create an isolated ClickHouse database |
| `run_sql` | Run one ClickHouse SQL statement in a materialization |
| `connect_stream` | Connect a stream to a table (backfill, then follow) |
| `materialization_status` | Insert and deletion freshness per source |
| `get_usage` | This month's events and replays against your plan's allowance |
| `cel_reference` | The CEL environment: variables, limits, number and regex rules |
| `evaluate_cel` | Dry-run a CEL expression against a sample record before using it in a read, erasure or materialization |

Each tool maps onto the [HTTP API](https://capless.sh/docs/api.md) with the same semantics, limits and error codes.

## Things to ask

* "Is Capless installed correctly on this site? Check that events are arriving."
* "Which pages had rage clicks in the last 7 days?"
* "Set up a ClickHouse table for pageviews and show me the top referrers this month."
* "Delete all data for user `user_42` and confirm when it is purged."
* "How close are we to this month's event limit?"

---

<!-- https://capless.sh/docs/web-sdk.md -->

# Web SDK

One tag. 2.0 KB (brotli) for analytics; session replay is a separate 1.7 KB chunk that is only downloaded for sampled sessions. No cookies, no dependencies.

```html
<script async src="https://c.capless.sh/c.js" data-site="cs_…"></script>
```

Put it before `</head>` on every page. The site key (`cs_…`) is public and write-only.

## Sites

A project can have several sites (one per domain or app). Sites are managed with the project API key:

```sh
H="authorization: Bearer $CAPLESS_API_KEY"

# Create
curl -s https://api.capless.sh/v1/web/sites -H "$H" \
  -d '{"name":"shop","allowedOrigins":["https://shop.example"],"replaySampleRate":1}'
# → {"key":"cs_…","name":"shop","allowedOrigins":["https://shop.example"],"replaySampleRate":1,"snippet":"<script async …>", …}

# List, update, delete
curl -s https://api.capless.sh/v1/web/sites -H "$H"
curl -s -X PATCH https://api.capless.sh/v1/web/sites/cs_… -H "$H" -d '{"replaySampleRate":0.25}'
curl -s -X DELETE https://api.capless.sh/v1/web/sites/cs_… -H "$H"
```

| Field | | |
|---|---|---|
| `name` | required | |
| `allowedOrigins` | optional | Restricts which origins may send to the site key, e.g. `["https://shop.example"]`. |
| `replaySampleRate` | 0–1, default `1` | Fraction of sessions recorded. |

## JavaScript API

```js
// Optional stub so calls made before the script loads are queued:
window.capless = window.capless || function () { (capless.q = capless.q || []).push(arguments) };

capless("track", "checkout_started", { plan: "pro" }); // custom event
capless("identify", "user_42", { email: "jane@example.com" }); // attach a user id (+ traits)
capless("reset");   // forget the user id (logout)
capless("optout");  // stop collecting on this browser; capless("optin") to resume
capless("page");    // record a pageview manually (SPA routing is detected automatically)
```

Name important elements for click analytics with `data-capless`:

```html
<button data-capless="upgrade-cta">Upgrade</button>
```

## What is collected automatically

| Event `type` | When | Notable fields |
|---|---|---|
| `pageview` | load, `pushState`/`replaceState`, back/forward | `title`, `referrer`, `referrerHost`, `navigation`, `ttfbMs`, `loadMs` |
| `pageleave` | navigating away / tab closing | `visibleMs`, `scrollDepthPct`, `vitals` (`lcpMs`, `fcpMs`, `cls`, `inpMs`) |
| `click` | any click | `element` (`tag`, `id`, `classes`, `text`, `href`, `selector`, `name` from `data-capless`), `x`, `y`, `rage` |
| `submit` | form submission (never field values) | `form` (`id`, `name`, `action`, `method`) |
| `error` | uncaught errors and unhandled rejections | `error` (`kind`, `message`, `stack`, `file`, `line`, `column`) |
| `hidden` | tab hidden | |
| `custom` | `capless("track", …)` | `name`, `properties` |
| `identify` | `capless("identify", …)` | `traits` |
| `replay_start` | a recording starts on a page load | |

Every event also carries:

* `timestamp` (client), `receivedAt` (server), `site`
* `anonymousId` (per browser, localStorage), `sessionId` (30 minutes of inactivity ends a session, shared across tabs), `tabId`, `userId`
* `url`, `host`, `path`, `query`, `hash`, `utm` (`source`, `medium`, `campaign`, `term`, `content`), `clickIds` (`gclid`, `fbclid`, …)
* `device` (`browser`, `browserVersion`, `os`, `deviceType`, `userAgent`, `screen`, `viewport`, `pixelRatio`, `language`, `timezone`)
* `geo` (`country`, `region`, `city`, `postalCode`, `continent`, `timezone`, `latitude`, `longitude`, `asn`, `asOrganization`)
* `isBot`, and `ipHash` (keyed hash; raw IPs are never stored)

## Streams

Each project's sites write to two [streams](https://capless.sh/docs/streams.md), created on first use:

* `web.events`: one record per event (above). Query it with [`/read` + CEL](https://capless.sh/docs/reading.md), or [materialize it into ClickHouse](https://capless.sh/docs/materializations.md).
* `web.replay`: session replay chunks with `sessionId`, `tabId`, `seq`, `part`, `startedAt`, `url`, `fromMs`, `toMs`, `frames`.

```sh
# Rage clicks and what was clicked
curl -s https://api.capless.sh/v1/streams/web.events/read -H "$H" \
  -d '{"filter":"entry.type == \"click\" && has(entry.rage)","map":"{\"path\": entry.path, \"element\": entry.element}"}'
```

[Erasures](https://capless.sh/docs/erasures.md) work on both streams, e.g. `entry.userId == 'user_42'`.

## Session replay privacy

Private by default:

* Input values are masked (`*`); password fields are never recorded. Opt specific fields in with `data-capless-unmask`.
* Text inside `.capless-mask` / `[data-capless-mask]` is masked.
* `.capless-block` / `[data-capless-block]` subtrees are replaced by an empty box.
* Script contents and inline event handlers are never recorded.

```html
<div class="capless-mask">Jane Doe · jane@example.com</div>
<iframe data-capless-block src="…"></iframe>
<input name="coupon" data-capless-unmask>
```

## Content Security Policy

If your site sends a CSP, allow the script and its collector:

```text
script-src https://c.capless.sh; connect-src https://c.capless.sh
```

---

<!-- https://capless.sh/docs/streams.md -->

# Streams & cursors

A **stream** is a durable, ordered, append-only collection of JSON records. Streams are immutable except for [erasures](https://capless.sh/docs/erasures.md).

```sh
H="authorization: Bearer $CAPLESS_API_KEY"

curl -s https://api.capless.sh/v1/streams -H "$H" -d '{"name":"events","validator":"entry.user_id != \"\""}'
curl -s https://api.capless.sh/v1/streams -H "$H"                       # list (by name)
curl -s https://api.capless.sh/v1/streams/events -H "$H"                # metadata: cursor (head), entryCount, …
curl -s -X PATCH https://api.capless.sh/v1/streams/events -H "$H" -d '{"validator":null}'
curl -s -X DELETE https://api.capless.sh/v1/streams/events -H "$H"      # asynchronous
```

* Names match `^[A-Za-z0-9][A-Za-z0-9_.\-]{0,127}$`. Use the name or the ID (`str_…`) in paths.
* A **validator** is a [CEL](https://capless.sh/docs/cel.md) expression over `entry` that must return `true` for every inserted record. A change (`PATCH`) applies to batches committed after it and increments `validatorVersion`.
* Deleting releases the name immediately; reads and writes return `410 stream_deleted`; storage is removed in the background (`deleting` → `deleted`), and rows are deleted from every materialization the stream fed.

## Inserting

```sh
curl -s https://api.capless.sh/v1/streams/events/entries -H "$H" \
  -d '{"idempotencyKey":"req-1","entries":[{"user_id":"u1","amount":100},{"user_id":"u2","amount":200}]}'
```

```json
{
  "batchId": "019a…",
  "committedAt": "2026-10-30T12:00:00.123Z",
  "inserted": 2,
  "duplicate": false,
  "startCursor": "cur_…",
  "committedCursor": "cur_…",
  "entries": [{ "id": "ent_…", "cursor": "cur_…" }, { "id": "ent_…", "cursor": "cur_…" }]
}
```

* **Atomic**: validation runs over all entries first; one failure rejects everything (`422 validation_failed`, failing indexes in `details.failures`).
* **Durable**: success is returned only after the batch is in object storage (R2) and appended to the stream's history. Acknowledged data is never lost.
* Batches hold 1–100 000 entries; each entry ≤ 1 MiB and ≤ 32 levels deep; request bodies ≤ 8 MiB (`413 request_too_large`). Split larger loads into several batches.
* `"returnEntryIds": false` omits the per-entry array from large responses.

## Idempotency

`idempotencyKey` (per stream, per operation type, ≤ 256 chars) makes retries safe:

* same key, identical body → the original result with `duplicate: true`;
* same key, different body → `409 idempotency_key_reused`;
* concurrent retries resolve to one commit. Keys are retained for 7 days.

## Batches and positions

A stream's history is a sequence of **batches** in commit order. A batch is either an *entries batch* (1..100 000 records) or an *erasure marker* (one position). Every item has a position `(batchId, offset)`.

* **Batch IDs** are UUIDv7 strings assigned *at commit*, never at upload. Within a stream they are strictly increasing, and lexicographic order equals commit order. The first 48 bits are the commit millisecond; clock regressions and bursts reuse the previous millisecond and increment a sequence, so the embedded time is *approximate but monotonic*.
* There is no per-entry sequence number; ordering batches is sufficient.

## Cursors

Cursors (`cur_…`, constant size) are **boundaries between items**, not items.

```text
origin │ B1[0] │ B1[1] │ B2[0] │ B2[1] │ head
       ↑       ↑               ↑
  cur(B1,0) cur(B1,1)       cur(B2,1)
```

In this two-batch stream, `afterCursor: null` reads from the origin, `cur(B1,1)` sits between `B1[0]` and `B1[1]` (it is `B1[0]`'s `cursor`), and `B2[1]`'s `cursor` is the head.

* `cur(B, k)` sits immediately before item `k` of batch `B`. An entry's `cursor` is the boundary right *after* it.
* The **origin cursor** is the boundary before everything; `afterCursor: null` means origin.
* The **head** (`stream.cursor`) is the boundary after the last committed item; `null` for an empty stream.
* Cursors and entry IDs are stable forever: compaction and physical purges rewrite storage objects, never offsets.

## Visibility: no gaps

Each stream has exactly one sequencer (a Durable Object). The head moves in the same storage transaction that appends a batch, and batch IDs are assigned in that transaction, so a reader can never observe batch *N+1* while batch *N* could still appear: **there are no uncommitted gaps**. A consumer that persists its cursor never misses a record committed before it.

## Throughput

One stream handles on the order of a thousand commits per second. Batching amortizes this (100 000 entries per commit). Shard a very hot logical stream across several streams.

---

<!-- https://capless.sh/docs/reading.md -->

# Reading & change feed

Two endpoints read a stream in cursor order: `/read` returns entries (what is in the stream), `/changes` returns inserts *and* erasures (what happened to it). Both share the cursor space, limits and pagination rules.

## `/read`

```sh
H="authorization: Bearer $CAPLESS_API_KEY"

curl -s https://api.capless.sh/v1/streams/events/read -H "$H" -d '{
  "afterCursor": null,
  "filter": "entry.amount > 50",
  "map": "{\"user\": entry.user_id, \"amount\": entry.amount}"
}'
```

```json
{
  "entries": [{ "id": "ent_…", "cursor": "cur_…", "value": { "user": "u2", "amount": 200 } }],
  "readEntries": 2, "readBytes": 81, "resultEntries": 1, "resultBytes": 64, "errorEntries": 0,
  "nextCursor": "cur_…", "snapshotCursor": "cur_…", "hasMore": false
}
```

* Items are returned in ascending cursor order, strictly between `afterCursor` and `beforeCursor` (both exclusive boundaries).
* `filter` and `map` are [CEL](https://capless.sh/docs/cel.md) and run server-side. Mapped values keep the original `id` and `cursor` alongside `value`.
* Erased entries are never returned, even before an erasure is resolved.

## Paging without skips or repeats

1. Omit `beforeCursor` on the first page. The head at request start is captured and returned as `snapshotCursor`.
2. Pass `nextCursor` as `afterCursor` and `snapshotCursor` as `beforeCursor` on later pages for a stable snapshot.
3. Stop when `hasMore` is `false`. Then `nextCursor == snapshotCursor`.

```sh
AFTER=null; BEFORE=null
while :; do
  PAGE=$(curl -s https://api.capless.sh/v1/streams/events/read -H "$H" \
    -d "{\"afterCursor\":$AFTER,\"beforeCursor\":$BEFORE}")
  echo "$PAGE" | node -e 'for (const e of JSON.parse(require("fs").readFileSync(0)).entries) console.log(JSON.stringify(e.value))'
  [ "$(echo "$PAGE" | node -p 'JSON.parse(require("fs").readFileSync(0)).hasMore')" = true ] || break
  AFTER=$(echo "$PAGE" | node -p 'JSON.stringify(JSON.parse(require("fs").readFileSync(0)).nextCursor)')
  BEFORE=$(echo "$PAGE" | node -p 'JSON.stringify(JSON.parse(require("fs").readFileSync(0)).snapshotCursor)')
done
```

`nextCursor` is the boundary after the last **examined** position: everything before it has been examined. A page may return zero entries and still advance (for example, everything was filtered out), so always continue from `nextCursor`, never from the last returned entry. To tail a stream, keep calling with `afterCursor` = your last `nextCursor` and no `beforeCursor`.

## Limits

| Limit | Counts | Default | Max |
|---|---|---|---|
| `limitReadEntries` | positions examined, including filtered-out and erased | 10 000 | 1 000 000 |
| `limitResultEntries` | entries returned | 1 000 | 100 000 |
| `limitReadBytes` | stored bytes examined | 16 MiB | 256 MiB |
| `limitBytes` | serialized result bytes | 1 MiB | 32 MiB |

Limits end a page; they never drop data. A matching entry that does not fit in `limitBytes` is **not** consumed; the page ends before it. If even the first entry cannot fit, the request fails (`422 result_too_large` / `limit_too_small`) instead of skipping data.

## Evaluation errors

A CEL error on any entry (for example a missing field) fails the request with `422 expression_evaluation_failed`, including the entry's ID and cursor. With `"onError": "exclude"`, such entries are skipped and counted in `errorEntries`.

```sh
curl -s https://api.capless.sh/v1/streams/web.events/read -H "$H" \
  -d '{"filter":"entry.geo.country == \"DE\"","onError":"exclude"}'
```

Or guard with `has()`: `has(entry.geo) && entry.geo.country == "DE"`.

## `/changes`: the change feed

`/changes` is the feed materializers and sync jobs consume. Same request as `/read`, plus `types` (default `["insert","erase"]`).

```sh
curl -s https://api.capless.sh/v1/streams/events/changes -H "$H" -d '{"afterCursor":"cur_…","types":["insert","erase"]}'
```

```json
{
  "changes": [
    { "type": "insert", "id": "ent_…", "cursor": "cur_…", "entry": { "user_id": "u3", "amount": 5 } },
    { "type": "erase", "id": "era_…", "cursor": "cur_…", "upToCursor": "cur_…", "filter": "entry.user_id == 'u1'",
      "status": "logically_applied", "affectedCount": 1, "affectedIds": ["ent_…"] }
  ],
  "blockedBy": null,
  "nextCursor": "cur_…", "snapshotCursor": "cur_…", "hasMore": false
}
```

* Inserts already covered by any accepted erasure are omitted: replaying from any cursor never resurrects erased records.
* **Barrier**: with `erase` in `types`, an erasure that is not yet resolved stops the page right before it (`blockedBy` is set, `nextCursor` is the boundary before the erasure). A consumer can therefore never advance its deletion checkpoint past an erasure it has not applied. Retry shortly; resolution is asynchronous.
* Resolved erasures carry the affected entry IDs inline (≤ 1000) or a paginated `affectedIdsRef`.
* Consumers that only want inserts pass `"types": ["insert"]` and are never blocked.
* Pagination never skips or repeats eligible items under a stable snapshot and erasure state.

---

<!-- https://capless.sh/docs/time-seeking.md -->

# Time seeking

`/locate` turns a commit time into a cursor with an index seek (no scan). Combine it with [`/read`](https://capless.sh/docs/reading.md) to read a time window.

```sh
H="authorization: Bearer $CAPLESS_API_KEY"

curl -s https://api.capless.sh/v1/streams/web.events/locate -H "$H" \
  -d '{"committedAt":"2026-10-29T00:00:00Z","mode":"at_or_after"}'
# → {"cursor":"cur_…","batchId":"019a…","committedAt":"2026-10-29T00:00:00.412Z","snapshotCursor":"cur_…"}
```

| `mode` | Returns |
|---|---|
| `at_or_after` (default) | the boundary right before the first batch committed at or after `committedAt` |
| `at_or_before` | the boundary before the last batch committed at or before `committedAt` |

`/read` with `afterCursor: cursor` therefore starts with the selected batch. If no batch qualifies, `batchId` and `committedAt` are `null`, and `cursor` is the head (`at_or_after`) or the origin (`at_or_before`).

## Reading a window

Everything committed on 29 October (UTC):

```sh
FROM=$(curl -s https://api.capless.sh/v1/streams/web.events/locate -H "$H" -d '{"committedAt":"2026-10-29T00:00:00Z"}' | node -p 'JSON.parse(require("fs").readFileSync(0)).cursor')
TO=$(curl -s https://api.capless.sh/v1/streams/web.events/locate -H "$H" -d '{"committedAt":"2026-10-30T00:00:00Z"}' | node -p 'JSON.parse(require("fs").readFileSync(0)).cursor')
curl -s https://api.capless.sh/v1/streams/web.events/read -H "$H" -d "{\"afterCursor\":\"$FROM\",\"beforeCursor\":\"$TO\"}"
```

## Commit time vs. event time

* `committedAt` is the **ingestion commit time** encoded in the batch ID (the first 48 bits of the UUIDv7), not a timestamp inside your records.
* It is approximate but monotonic: bursts within one millisecond and clock regressions reuse the previous millisecond.
* To filter on a time inside your records, use CEL, e.g. `timestamp(entry.timestamp) > timestamp("2026-10-29T00:00:00Z")`. Seek by commit time first to bound the scan.
* In `filter`/`map`, `committedAt` is available as a CEL `timestamp`: `committedAt >= timestamp("2026-10-29T00:00:00Z")`.

All timestamps are UTC ISO 8601 with millisecond precision.

---

<!-- https://capless.sh/docs/cel.md -->

# CEL functions

Capless uses [CEL](https://cel.dev) (Common Expression Language) everywhere logic runs on your data: stream validators, read filters and maps, erasure predicates and materialization mappings. One environment, deterministic and bounded.

## Contexts and variables

| Context | Used by | Variables | Must return |
|---|---|---|---|
| `validator` | `POST /v1/streams` (`validator`) | `entry` | `bool` |
| `filter` | `/read`, `/changes`, sources | `entry`, `id`, `cursor`, `batchId`, `committedAt` | `bool` |
| `map` | `/read`, `/changes`, sources | `entry`, `id`, `cursor`, `batchId`, `committedAt` | any JSON value (sources: an object) |
| `erasure` | `POST …/erasures` (`filter`) | `entry`, `id`, `cursor`, `batchId`, `committedAt` | `bool` |

`entry` is the JSON record (`dyn`). `id`, `cursor` and `batchId` are strings; `committedAt` is a `timestamp` (the batch's commit time). `GET /v1/functions` returns this description as JSON.

## Try it: dry runs

```sh
curl -s https://api.capless.sh/v1/functions/evaluate -H "authorization: Bearer $CAPLESS_API_KEY" \
  -d '{"kind":"map","expression":"{\"user\": entry.user_id, \"cents\": int(entry.amount * 100.0)}","entry":{"user_id":"u1","amount":1.5}}'
# → {"result":{"user":"u1","cents":150}}
```

`kind` is `validator`, `filter`, `map` (default) or `erasure`; `variables` optionally sets `id`, `cursor`, `batchId`, `committedAt`.

## Examples

```text
# Validators
has(entry.user_id) && entry.user_id != ""
entry.amount >= 0 && entry.currency in ["EUR", "USD"]

# Filters
entry.type == "pageview" && entry.path.startsWith("/docs")
entry.type == "click" && has(entry.rage)
has(entry.utm) && entry.utm.source == "newsletter"
entry.sku.matches("^SKU-[0-9]{6}$")
committedAt >= timestamp("2026-10-29T00:00:00Z")
entry.items.exists(i, i.price > 100.0)

# Maps
{"user": entry.user_id, "total": double(entry.amount)}
{"path": entry.path, "lcp": has(entry.vitals) ? entry.vitals.lcpMs : null}
entry.tags.filter(t, t != "internal")
{"id": id, "committedAt": committedAt, "hourUtc": committedAt.getHours()}

# Erasures
entry.userId == "user_42"
entry.email.endsWith("@example.com")
```

## Numbers

* JSON numbers with an integral value are `int`; all others are `double`. `1` is an `int`, `1.5` and `1.0e3` are `double`.
* Comparisons work across both (`entry.amount > 1`), but arithmetic does not mix them: `entry.amount * 100` fails when `amount` is `1.5`. Normalize with `double(x)` / `int(x)`: `double(entry.amount) * 100.0`.
* Integers beyond 2^53 stay exact end to end (storage, CEL, results).

## Missing fields

Selecting a field that does not exist is an evaluation error. Guard with `has()`:

```text
has(entry.geo) && entry.geo.country == "DE"
```

On reads, an evaluation error fails the request (`422 expression_evaluation_failed`) unless you pass `"onError": "exclude"`. In an erasure predicate, an error on an entry simply does not select it.

## Regular expressions

`matches` takes a **string-literal** ECMAScript pattern. Patterns that could backtrack catastrophically are rejected at compile time (`400 invalid_expression`):

* no backreferences (`\1`, `\k<name>`);
* no lookaround (`(?=…)`, `(?!…)`, `(?<=…)`, `(?<!…)`);
* no quantified group that contains a quantifier or an alternation: `(a+)+`, `(a|aa)*`, `(.*a){3}` are rejected; `^(foo|bar)-[a-z]{2,8}$` is fine.

## Limits

| Limit | Value |
|---|---|
| Expression length | 4096 characters |
| AST nodes | 1000 |
| Nesting depth | 32 |
| Nested comprehension macros (`all`, `exists`, `exists_one`, `map`, `filter`) | 2 |
| Literal list elements / map entries | 256 / 256 |
| Records | ≤ 1 MiB, ≤ 32 levels |

Every request also runs under the Workers CPU limit. Programs are compiled once and cached.

## Determinism

There is no clock, randomness, I/O or user-defined function in the environment, so the same expression on the same entry always returns the same result. That is what makes materializations rebuildable and erasures exact.

---

<!-- https://capless.sh/docs/erasures.md -->

# Erasures & GDPR

Streams are immutable except for **erasures**: delete every entry matching a [CEL](https://capless.sh/docs/cel.md) predicate, in the stream and in every [materialization](https://capless.sh/docs/materializations.md) it feeds, with a status you can prove.

```sh
H="authorization: Bearer $CAPLESS_API_KEY"

curl -s https://api.capless.sh/v1/streams/web.events/erasures -H "$H" \
  -d '{"idempotencyKey":"gdpr-request-123","filter":"entry.userId == \"user_42\""}'
# 202 → {"id":"era_…","status":"pending","upToCursor":"cur_…", …}

curl -s https://api.capless.sh/v1/streams/web.events/erasures/era_… -H "$H"          # status, progress, downstream
curl -s https://api.capless.sh/v1/streams/web.events/erasures/era_…/entries -H "$H"  # exact affected IDs
curl -s https://api.capless.sh/v1/streams/web.events/erasures -H "$H"                # all erasures, stream order
```

For web analytics, erase both streams: `web.events` and `web.replay`.

## Scope

* An erasure occupies a position in the stream's history, ordered with batches.
* It affects entries strictly before its `upToCursor` (default: the head when it is accepted) for which `filter` is `true`. **Later inserts are never affected.**
* A predicate that errors on an entry (for example a missing field) does not select it.
* `filter` sees `entry`, `id`, `cursor`, `batchId` and `committedAt`, so you can erase by time too: `committedAt < timestamp("2026-01-01T00:00:00Z")`.

## Status

| Status | Meaning |
|---|---|
| `pending`, `resolving` | Accepted. Every reader (`/read`, `/changes`, materializers) **already hides** matching entries by evaluating the predicate on the fly. |
| `logically_applied` | The exact affected set is recorded; `GET …/erasures/{id}/entries` lists it (paginated, cursor order). Earlier: `409 erasure_not_resolved`. |
| `physically_purged` | Every storage segment that held an affected record was rewritten without it, and the superseded objects were deleted from canonical storage (after a short grace period for in-flight readers, 10 minutes by default). |

`progress` reports `scannedEntries`, `affectedCount`, `affectedBatches` and `purgedBatches`; `downstream` lists every materialization source and whether it has `applied` the erasure.

## Guarantees

* **Immediate**: matching entries are hidden from every reader from the moment the erasure is accepted.
* **Never resurrected**: replaying `/changes` from any cursor omits inserts covered by any accepted erasure.
* **Physical**: affected records are removed from storage, not just flagged. Offsets are preserved (a purged record becomes an empty line), so cursors stay valid.
* **Downstream, exactly**: materializations delete the affected rows by their lineage column (`_capless_id`). A source reports `deletionCurrent: false` until it has applied every erasure, and the change feed's barrier prevents a consumer from skipping one.

## A GDPR deletion request, end to end

```sh
# 1. Erase the user everywhere their data lives
for S in web.events web.replay orders; do
  curl -s https://api.capless.sh/v1/streams/$S/erasures -H "$H" \
    -d "{\"idempotencyKey\":\"dsr-881-$S\",\"filter\":\"has(entry.userId) && entry.userId == 'user_42'\"}"
done

# 2. Poll until physically_purged and every downstream source has applied it
curl -s https://api.capless.sh/v1/streams/orders/erasures/era_… -H "$H"

# 3. Keep the affected IDs as your record of what was deleted
curl -s "https://api.capless.sh/v1/streams/orders/erasures/era_…/entries?limit=10000" -H "$H"
```

## Caveats

* Data you copied out of Capless (exports, derived ClickHouse tables built with `INSERT … SELECT` or materialized views) is outside these guarantees. See [materializations](https://capless.sh/docs/materializations.md#supported-and-unsupported-patterns).
* Session replay records only what the [privacy rules](https://capless.sh/docs/web-sdk.md#session-replay-privacy) allow, so most personal data is never captured in the first place.

---

<!-- https://capless.sh/docs/materializations.md -->

# ClickHouse materializations

A **materialization** is an isolated ClickHouse database that Capless keeps in sync with one or more streams. You define tables with real ClickHouse SQL, connect streams to them, and query them with SQL. Available on the Team plan.

Materializations read streams only through the public API (the [change feed](https://capless.sh/docs/reading.md#changes-the-change-feed)), so they can be dropped and rebuilt from scratch at any time.

## 1. Create a materialization

```sh
H="authorization: Bearer $CAPLESS_API_KEY"

curl -s https://api.capless.sh/v1/materializations -H "$H" -d '{"name":"analytics","type":"clickhouse"}'
# 201 → {"id":"mat_…","name":"analytics","type":"clickhouse","status":"…","config":{"engine":"clickhouse","database":"…"}, …}
export MAT=mat_…
```

This creates an empty database with its own credentials. No tables or sources.

## 2. Create a table

Managed tables must use a MergeTree-family engine and have a `_capless_id String` column: the **lineage column**.

```sh
curl -s https://api.capless.sh/v1/materializations/$MAT/query -H "$H" -d '{"sql":"CREATE TABLE pageviews (_capless_id String, ts DateTime64(3), path String, country String, session String) ENGINE = MergeTree ORDER BY ts"}'
```

## 3. Connect a stream (a source)

```sh
curl -s https://api.capless.sh/v1/materializations/$MAT/sources -H "$H" -d '{
  "stream": "web.events",
  "table": "pageviews",
  "filter": "entry.type == \"pageview\"",
  "map": "{\"ts\": entry.timestamp, \"path\": entry.path, \"country\": has(entry.geo) && has(entry.geo.country) ? entry.geo.country : \"\", \"session\": entry.sessionId}"
}'
```

* The source backfills from the beginning (or from `startCursor`), then follows the stream.
* `map` must return an object; its keys are column names. Without `map`, the record itself is the row.
* One destination row per source entry; `filter` drops entries.

## 4. Query

```sh
curl -s https://api.capless.sh/v1/materializations/$MAT/query -H "$H" -d '{
  "sql": "SELECT path, count() AS views, uniq(session) AS sessions FROM pageviews WHERE ts > now() - INTERVAL {days:UInt32} DAY GROUP BY path ORDER BY views DESC LIMIT 10",
  "parameters": {"days": 7}
}'
```

```json
{
  "columns": [{ "name": "path", "type": "String" }, { "name": "views", "type": "UInt64" }, { "name": "sessions", "type": "UInt64" }],
  "rows": [["/", 1204, 811], ["/pricing", 342, 290]],
  "truncated": false,
  "statistics": { "elapsedMs": 12, "readRows": 5121, "readBytes": 204840 }
}
```

* Real ClickHouse SQL, one statement per request (DDL or query); do not add a `FORMAT` clause.
* Use `{name:Type}` placeholders with `parameters` instead of string concatenation.
* Limits: 30 s, 4 GB memory, `maxRows` returned rows (default 10 000, max 100 000; `truncated: true` when cut).
* 64-bit integers are returned as JSON numbers with exact digits.
* Managed tables cannot be written, truncated, dropped or have columns altered by your SQL (`403 query_forbidden`); Capless owns their contents.

## Status

```sh
curl -s https://api.capless.sh/v1/materializations/$MAT/status -H "$H"
```

`status` is `ready` (no sources), `syncing`, `current` (every source has applied all inserts and all erasures up to the head) or `error`. Per source:

| Field | |
|---|---|
| `status` | `backfilling`, `streaming`, `detached`, `stream_deleted`, `dropped` |
| `entriesThroughCursor` | every insert before it is in the table |
| `erasuresThroughCursor` | every erasure before it has been applied |
| `entriesCurrent` / `deletionCurrent` | insert and deletion freshness, reported separately; `deletionCurrent` is only `true` when no erasure at or after `erasuresThroughCursor` exists |
| `pendingErasures`, `lastError` | |

Inserts do not wait for erasure resolution: entries covered by an erasure are already hidden from the insert feed.

## Guarantees

* **Exactly-once**: the end of each insert page is written ahead before inserting; after a crash the identical range is re-read and re-inserted with the same ClickHouse deduplication token, so a page is applied once. Deletes are idempotent and resumable.
* **One writer per source**: each source is driven by exactly one Durable Object.
* **Lineage**: Capless fills `_capless_id` with the source entry ID, and [erasures](https://capless.sh/docs/erasures.md) delete by it.
* Deleting a stream deletes its rows from every table it fed. Detaching a source (`DELETE …/sources/{id}`) stops inserts but keeps applying future erasures to the rows it wrote until the table is dropped.

## Supported and unsupported patterns

Supported: one destination row per source entry (`map` returns an object, or no `map`), with `filter` dropping entries.

Rejected or reported, never silently wrong:

* `map` returning a list (fan-out) or a scalar → source error `map_must_return_object`.
* Setting `_capless_id` to anything but the entry ID → `lineage_overwritten`.
* Non-MergeTree target tables → `422 unsupported_table_engine`; tables without the lineage column → `422 missing_lineage_column`.
* **Derived data inside ClickHouse** (materialized views, `INSERT … SELECT`, `CREATE TABLE … AS SELECT`, aggregating tables fed from a managed table) is allowed for convenience but is *outside* the erasure guarantees: erasures only delete rows from the managed table. Prefer plain views or query-time aggregation, or rebuild derived tables after erasures.

## Other endpoints

```sh
curl -s https://api.capless.sh/v1/materializations -H "$H"                          # list
curl -s https://api.capless.sh/v1/materializations/$MAT/sources -H "$H"             # sources + checkpoints
curl -s -X DELETE https://api.capless.sh/v1/materializations/$MAT/sources/src_… -H "$H"
curl -s -X DELETE https://api.capless.sh/v1/materializations/$MAT -H "$H"           # drops the database; streams untouched
```

## Isolation

One database and one ClickHouse user per materialization, a settings profile with hard maxima (time, memory, result size), no external table functions (`url`, `file`, `s3`, `remote`, …), and partial revokes on managed tables.

---

<!-- https://capless.sh/docs/api.md -->

# API reference

Base URL `https://api.capless.sh`. Every endpoint is under `/v1` and takes `authorization: Bearer cpl_…` (except signup). The complete, machine-readable contract is the OpenAPI 3.1 spec: [/openapi.yaml](https://capless.sh/openapi.yaml) (also served at [api.capless.sh/v1/openapi.yaml](https://api.capless.sh/v1/openapi.yaml)).

## Account

| Method | Path | |
|---|---|---|
| `POST` | `/v1/signup` | Create user, project (trial), API key and optional site. No auth. [Details](https://capless.sh/docs/agents.md#signup-api) |

## Streams

| Method | Path | |
|---|---|---|
| `POST` | `/v1/streams` | Create a stream (`name`, optional `validator`) |
| `GET` | `/v1/streams` | List streams, ordered by name |
| `GET` | `/v1/streams/{stream}` | Metadata: head `cursor`, `entryCount`, `lastCommittedAt`, status |
| `PATCH` | `/v1/streams/{stream}` | Rename and/or change the validator |
| `DELETE` | `/v1/streams/{stream}` | Delete (asynchronous, `202`) |

`{stream}` is the ID (`str_…`) or the name. [Streams & cursors](https://capless.sh/docs/streams.md)

## Entries

| Method | Path | |
|---|---|---|
| `POST` | `/v1/streams/{stream}/entries` | Insert a batch atomically, idempotently |
| `POST` | `/v1/streams/{stream}/read` | Read in cursor order with CEL `filter`/`map` |
| `POST` | `/v1/streams/{stream}/changes` | Ordered feed of inserts and erasures |
| `POST` | `/v1/streams/{stream}/locate` | Cursor for a commit time (index seek) |

[Reading & change feed](https://capless.sh/docs/reading.md) · [Time seeking](https://capless.sh/docs/time-seeking.md)

## Erasures

| Method | Path | |
|---|---|---|
| `POST` | `/v1/streams/{stream}/erasures` | Erase entries matching a CEL predicate (`202`) |
| `GET` | `/v1/streams/{stream}/erasures` | List erasures in stream order |
| `GET` | `/v1/streams/{stream}/erasures/{erasure}` | Status, progress, downstream propagation |
| `GET` | `/v1/streams/{stream}/erasures/{erasure}/entries` | Exact affected entry IDs (once `logically_applied`) |

[Erasures & GDPR](https://capless.sh/docs/erasures.md)

## Functions

| Method | Path | |
|---|---|---|
| `GET` | `/v1/functions` | Describe the CEL environment |
| `POST` | `/v1/functions/evaluate` | Evaluate an expression against a sample entry |

[CEL functions](https://capless.sh/docs/cel.md)

## Web analytics sites

| Method | Path | |
|---|---|---|
| `POST` | `/v1/web/sites` | Create a site (`name`, `allowedOrigins`, `replaySampleRate`); returns `key` and `snippet` |
| `GET` | `/v1/web/sites` | List sites |
| `PATCH` | `/v1/web/sites/{key}` | Update a site |
| `DELETE` | `/v1/web/sites/{key}` | Delete a site |

[Web SDK](https://capless.sh/docs/web-sdk.md)

## Materializations

| Method | Path | |
|---|---|---|
| `POST` | `/v1/materializations` | Create (`name`, `type: "clickhouse"`) |
| `GET` | `/v1/materializations` | List |
| `GET` | `/v1/materializations/{id}` | Get |
| `DELETE` | `/v1/materializations/{id}` | Delete with all its data (streams untouched) |
| `POST` | `/v1/materializations/{id}/query` | Run one ClickHouse SQL statement |
| `POST` | `/v1/materializations/{id}/sources` | Connect a stream to a table |
| `GET` | `/v1/materializations/{id}/sources` | List sources with checkpoints |
| `DELETE` | `/v1/materializations/{id}/sources/{sourceId}` | Detach a source |
| `GET` | `/v1/materializations/{id}/status` | Insert and deletion freshness |

[ClickHouse materializations](https://capless.sh/docs/materializations.md)

## Conventions

* Bodies are JSON, ≤ 8 MiB. Timestamps are UTC ISO 8601 with millisecond precision.
* Lists: `?limit=` (1–1000, default 100) and `?pageToken=` → `{"data": [...], "nextPageToken": "…" | null}`.
* Writes accept `idempotencyKey` (kept 7 days).

## Errors

```json
{ "error": { "code": "validation_failed", "message": "1 of 2 entries failed validation; nothing was committed.",
  "details": { "failedCount": 1, "failures": [{ "index": 1, "message": "validator returned false" }] }, "requestId": "1b4e…" } }
```

| HTTP | Codes |
|---|---|
| 400 | `invalid_json`, `invalid_request`, `invalid_name`, `invalid_expression`, `invalid_cursor`, `invalid_limit`, `invalid_timestamp`, `invalid_page_token`, `cursor_out_of_range`, `query_failed`, `unsupported_output_format`, `unsupported_type`, `project_required` |
| 401 / 403 | `unauthenticated`, `forbidden`, `query_forbidden` |
| 404 | `stream_not_found`, `erasure_not_found`, `materialization_not_found`, `source_not_found`, `site_not_found`, `route_not_found` |
| 409 | `stream_name_taken`, `materialization_name_taken`, `idempotency_key_reused`, `erasure_not_resolved`, `email_taken` |
| 410 | `stream_deleted` |
| 413 | `request_too_large`, `batch_too_large`, `entry_too_large` |
| 422 | `validation_failed`, `expression_evaluation_failed`, `result_too_large`, `limit_too_small`, `table_not_found`, `missing_lineage_column`, `unsupported_table_engine` |
| 429 | `rate_limited` |
| 502 / 503 | `engine_error`, `engine_unavailable`, `engine_unreachable` |

Branch on `code`; messages are for humans and may change.

---

<!-- https://capless.sh/docs/limits.md -->

# Limits & quotas

## Plan allowances

Allowances are per project, per calendar month. See [pricing](https://capless.sh/pricing.md) for prices.

| | Free trial (14 days) | Starter | Team | Enterprise |
|---|---|---|---|---|
| Members | 1 | 1 | unlimited | custom |
| Events / month | 250,000 | 250,000 | 2M per member, pooled | custom |
| Session replays / month | 2,500 | 2,500 | 10,000 per member, pooled | custom |
| Sites | 3 | 3 | unlimited | custom |
| API, MCP, CEL, streams, erasures | ✓ | ✓ | ✓ | ✓ |
| ClickHouse SQL materializations | — | — | ✓ | ✓ |
| Beyond the allowance | collection pauses | collection pauses | pay as you go | contract |

* An **event** is each web analytics event (pageview, click, …) or each entry inserted via the API.
* A **replay** is one recorded session in one browser tab.
* Trial and Starter limits are hard: when you reach one, collection pauses until next month or until you upgrade. You never get a surprise bill. Data you already collected is untouched.
* Data is kept until you delete it ([erasures](https://capless.sh/docs/erasures.md), or deleting a stream).

## API

| Limit | Value |
|---|---|
| Request body | 8 MiB (`413 request_too_large`) |
| Entries per batch | 1–100 000 |
| Entry size / depth | 1 MiB / 32 levels |
| Idempotency key | ≤ 256 characters, kept 7 days |
| Stream and materialization names | `^[A-Za-z0-9][A-Za-z0-9_.\-]{0,127}$` |
| List page size | 1–1000 (default 100) |
| Commits per stream | on the order of 1000/s; batch, or shard hot streams |

## Reads

| Limit | Default | Max |
|---|---|---|
| `limitReadEntries` (positions examined) | 10 000 | 1 000 000 |
| `limitResultEntries` | 1 000 | 100 000 |
| `limitReadBytes` (stored bytes examined) | 16 MiB | 256 MiB |
| `limitBytes` (result bytes) | 1 MiB | 32 MiB |
| Inlined erasure IDs in `/changes` | 1000 | |
| Erasure affected-ID page (`limit`) | 1000 | 10 000 |

## CEL

| Limit | Value |
|---|---|
| Expression length | 4096 characters |
| AST nodes / depth | 1000 / 32 |
| Nested comprehensions | 2 |
| Literal list elements / map entries | 256 / 256 |

## ClickHouse queries

| Limit | Value |
|---|---|
| Statements per request | 1 |
| Time / memory | 30 s / 4 GB |
| Returned rows (`maxRows`) | default 10 000, max 100 000 |

## Web collector

| Limit | Value |
|---|---|
| Payload per request | 1 MiB compressed, 4 MiB decompressed |
| Session timeout | 30 minutes of inactivity |

---

<!-- https://capless.sh/docs/security.md -->

# Security & privacy

## Keys

* **API keys** (`cpl_…`) authorize everything in a project. They are 200-bit secrets; only their SHA-256 is stored. Keep them server-side.
* **Site keys** (`cs_…`) are public and write-only: they can only send web analytics events for their site. Restrict them with `allowedOrigins`.

## Privacy by default

* No cookies. The SDK keeps an anonymous ID in `localStorage`.
* Raw IP addresses are never stored; events carry `ipHash`, a keyed hash.
* Form submissions record the form, never field values.
* Session replay masks every input value and never records password fields, script contents or inline event handlers. Mask text with `.capless-mask` and remove whole subtrees with `.capless-block` ([details](https://capless.sh/docs/web-sdk.md#session-replay-privacy)).
* `capless("optout")` stops collection in a browser.
* [Erasures](https://capless.sh/docs/erasures.md) delete data by predicate from storage and every materialization, with auditable status.
* Data is kept until you delete it.

## Isolation and bounds

* CEL has no I/O, clock, randomness or user functions. Expressions and inputs are size and depth bounded; `matches` rejects patterns that can backtrack catastrophically; every request runs under the Workers CPU limit.
* ClickHouse: one database and user per materialization, a settings profile with hard maxima (time, memory, result size), no external table functions (`url`, `file`, `s3`, `remote`, …), partial revokes on managed tables.
* Per-materialization ClickHouse credentials are stored in the project's Durable Object (encrypted at rest by Cloudflare).

## Infrastructure

Capless runs on Cloudflare: Workers for the API and collector, Durable Objects (one per stream, project and materialization source) for ordering and metadata, R2 for record storage. Materializations run on ClickHouse Cloud. There are no servers or VMs to patch.

* Writes are acknowledged only after they are durable in R2 and committed to the stream's history.
* Everything is served over HTTPS.

## Supply chain

The codebase installs no dependency lifecycle scripts, pins exact versions, refuses releases younger than 7 days and refuses provenance downgrades. The browser SDK has no dependencies at all.

## Reporting a vulnerability

Email [hello@capless.sh](mailto:hello@capless.sh). Please do not open public issues for security reports.

---

<!-- https://capless.sh/pricing.md -->

# Pricing

Per project, in USD, billed monthly via Stripe. Every plan starts with a 14-day free trial with Starter limits. No credit card.

## Plans

| | Starter | Team | Enterprise |
|---|---|---|---|
| Price | $5 / month | $29 per member / month | [Contact us](mailto:hello@capless.sh) |
| Members | 1 | unlimited | custom |
| Events / month | 250,000 | 2M per member, pooled | custom |
| Session replays / month | 2,500 | 10,000 per member, pooled | custom |
| Sites | 3 | unlimited | custom |
| API, MCP, CEL, streams, erasures | ✓ | ✓ | ✓ |
| ClickHouse SQL materializations | — | ✓ | ✓ |
| Beyond the allowance | collection pauses, never a surprise bill | events $2 per 1M (first 100M), then $1 per 1M; replays $0.50 per 1,000 (first 100,000), then $0.25 per 1,000 | custom contract |
| Also | | | SSO, custom contracts, EU data residency |

## Compared at scale

What one month costs at a given volume, each row on its own.

| Monthly volume | Capless Team, 1 member | PostHog¹ | Mixpanel Growth² |
|---|---|---|---|
| 10M events | **$45** | $324.40 | $840 (annual billing), $1,176 (monthly billing) |
| 100M events | **$225** | $2,618.40 | contact sales |
| 10k session replays | **$29** | $25 | $0 (Free plan, 10K replays) |
| 100k session replays | **$74** | $272.50 | not published |
| 10M events + 100k replays | **$90** | $596.90 | not published |

How the Capless numbers add up: $29 for one member includes 2M events and 10,000 replays. 10M events = $29 + 8 × $2 = $45. 100M events = $29 + 98 × $2 = $225. 100k replays = $29 + 90 × $0.50 = $74.

1. PostHog product analytics (standard events) and web session replay, from the tier tables on [posthog.com/pricing](https://posthog.com/pricing), checked 2026-10-30. Free allowance (1M events, 5,000 recordings) applied; each volume band charged at its own rate. Add-ons such as identified events are not included.
2. Mixpanel Growth plan, from [mixpanel.com/pricing](https://mixpanel.com/pricing/), checked 2026-10-30. The page lists 10M events/month at $840/month billed yearly or $1,176/month billed monthly, asks plans above 20M events to contact sales, and lists no price for replays beyond those included.

LogRocket, FullStory and Hotjar do not publish prices at these volumes, so they are not listed. Competitor prices change; check their pages for current numbers.

## FAQ

### What counts as an event?

Each web analytics event (a pageview, click, form submit, error, custom `track` call, …) and each entry inserted through the API counts as one event. Reads, queries and erasures do not count as events.

### What counts as a session replay?

One recorded session in one browser tab. Sessions that are not sampled (see `replaySampleRate`) are not recorded and do not count.

### What happens when I reach my limit?

On the trial and Starter, limits are hard: collection pauses at the cap until the next month starts or you upgrade. You never get a surprise bill, and the data you already collected is untouched.

On Team, collection never pauses: usage beyond the pooled allowance is billed at the overage rates (see the next answer).

### How is Team overage calculated?

Each member adds 2M events and 10,000 replays to a shared monthly allowance. Usage beyond it costs $2 per 1M events for the first 100M, then $1 per 1M; and $0.50 per 1,000 replays for the first 100,000, then $0.25 per 1,000.

**3 members, 9M events, 45,000 replays.** Allowance: 6M events, 30,000 replays. Overage: 3M events × $2 = $6; 15,000 replays × $0.50 per 1,000 = $7.50. Seats: 3 × $29 = $87. **Total: $100.50.**

**1 member, 150M events, 10,000 replays.** Allowance: 2M events. Overage: 148M events = 100M × $2 + 48M × $1 = $248. Seat: $29. **Total: $277.**

**2 members, 3M events, 250,000 replays.** Allowance: 4M events, 20,000 replays. Overage: 230,000 replays = 100,000 × $0.50 per 1,000 + 130,000 × $0.25 per 1,000 = $50 + $32.50 = $82.50. Seats: $58. **Total: $140.50.**

### What happens after the 14-day trial?

Pick Starter or Team in the dashboard to keep collecting. The trial needs no credit card, so nothing is charged unless you choose a plan.

### Can I cancel?

Yes, anytime from the dashboard. Plans are billed monthly through Stripe; there are no annual commitments. Your data stays yours: delete it whenever you want with [erasures](https://capless.sh/docs/erasures.md) or by deleting streams.

### How long do you keep my data?

Until you delete it. There is no retention window that silently drops old events.

### Do I need Team for SQL?

ClickHouse SQL [materializations](https://capless.sh/docs/materializations.md) are on Team and Enterprise. Every plan can query with CEL filters and maps through the API and MCP.

### What about Enterprise?

SSO, custom contracts and EU data residency. Email [hello@capless.sh](mailto:hello@capless.sh).