# 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://analytics.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 built-in stream called `$web.events` and replays in `$web.replay`, so everything below applies to your web data too.

## Start here

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

## Reference

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

## Conventions

* Base URL `https://api.capless.sh`. All endpoints are under `/v1`.
* Authenticate with your project API key: `authorization: Bearer cpl_…`. An unclaimed project can be read with its claim secret (`Bearer csk_…`).
* Bodies are JSON. Timestamps are UTC ISO 8601 with millisecond precision.
* IDs (`prj_`, `str_`, `ent_`, `era_`, `mat_`, `src_`) and cursors (`cur_`) are opaque strings.
* In shell commands, single-quote URLs that contain `$web.events` or `$web.replay`.
* 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://analytics.capless.sh/docs/index.md)). [/llms.txt](https://analytics.capless.sh/llms.txt) indexes them, and [/llms-full.txt](https://analytics.capless.sh/llms-full.txt) is everything in one file.

---

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

# Quickstart

From zero to an answer about your traffic in five minutes. You need a website you can edit. An account is optional until you want to keep the data.

## 1. Get a snippet

Copy the snippet from the [home page](https://analytics.capless.sh/#install). Its key was generated in your browser and belongs to you. In a terminal, or from a coding agent, use:

```sh
curl -s https://analytics.capless.sh/new
```

It prints a snippet and a claim link. With `-H 'accept: application/json'` it returns the same as JSON:

```json
{
  "snippet": "<script async src=\"https://c.capless.sh/c.js\" data-key=\"cs_…\"></script>",
  "key": "cs_…",
  "claimSecret": "csk_…",
  "claimUrl": "https://app.capless.sh/claim#csk_…",
  "unclaimedDays": 14
}
```

* The key (`cs_…`) is public and can only send events. It is safe in HTML.
* The claim secret (`csk_…`) is the only way to see the data and to take ownership of the project. Keep it out of pages and version control.

## 2. Add the snippet

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

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

Pageviews, clicks, form submits, errors, Web Vitals and session replays are collected automatically. Single-page apps are detected (`pushState`, back/forward). One snippet works on any number of domains. See [Web SDK](https://analytics.capless.sh/docs/web-sdk.md) for custom events and user identification.

The first event creates the project. Until someone claims it, the project is **unclaimed**: it collects up to 250,000 events, 2,500 replays and 10 GB, has no SQL, API keys or members, and is deleted 14 days after it was created.

## 3. Open the claim link

Open the claim link (`https://app.capless.sh/claim#csk_…`). It shows what the project has collected so far, without an account, and has a form to claim it with your email. On the home page, the same form is below the snippet.

Claiming starts a 14-day trial with no credit card (or asks for a plan if your account already had a trial). The data collected so far is kept, and the key stays the same, so the snippet does not change.

The claim secret also works as a read-only bearer token while the project is unclaimed:

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

## 4. Check that data arrives

After claiming, use an API key (`cpl_…`, created in the dashboard or returned by the [signup API](#signup-api-for-agents)):

```sh
export CAPLESS_API_KEY=cpl_…
curl -s 'https://api.capless.sh/v1/streams/$web.events' -H "authorization: Bearer $CAPLESS_API_KEY"

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}"}'
```

Single-quote URLs that contain `$web.events`, so the shell does not expand `$web`.

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

## 5. Ask questions

* **From your coding agent**: [connect the MCP server](https://analytics.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://analytics.capless.sh/docs/cel.md)).
* **With SQL**: [materialize](https://analytics.capless.sh/docs/materializations.md) `$web.events` into ClickHouse and run real SQL.

## Signup API (for agents)

An agent that needs an account and an API key at once can call the signup API instead. With `claimSecret`, the new account takes over the project behind that snippet; without it, the account gets a new project and key.

```sh
curl -s https://api.capless.sh/v1/signup \
  -d '{"email":"you@example.com","claimSecret":"csk_…"}'
```

The response contains `apiKey` (shown once), `web` (the snippet and settings) and `dashboardUrl` (a one-time sign-in link, valid for 15 minutes). `409 email_taken` means the address already has an account: [log in](https://app.capless.sh/login) and open the claim link instead. Details: [For agents](https://analytics.capless.sh/docs/agents.md#signup-api).

## 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://analytics.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. Run `curl -s https://analytics.capless.sh/new` and follow what it prints.
```

`GET https://analytics.capless.sh/new` returns a fresh snippet and a claim link. The agent adds the snippet before `</head>` and gives you the claim link; nothing else is needed to start collecting. The longer version of these instructions is [/AGENTS.md](https://analytics.capless.sh/AGENTS.md).

## Machine-readable docs

| URL | What |
|---|---|
| [/llms.txt](https://analytics.capless.sh/llms.txt) | Index in [llmstxt.org](https://llmstxt.org) format, linking every page as Markdown |
| [/llms-full.txt](https://analytics.capless.sh/llms-full.txt) | All docs in one file |
| `/docs/<page>.md` | Any docs page as Markdown, e.g. [/docs/cel.md](https://analytics.capless.sh/docs/cel.md) |
| [/AGENTS.md](https://analytics.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 |

## New snippet

`GET https://analytics.capless.sh/new` needs no authentication and stores nothing. It returns plain text for a terminal, or JSON with `accept: application/json`:

```sh
curl -s https://analytics.capless.sh/new -H 'accept: application/json'
```

```json
{
  "snippet": "<script async src=\"https://c.capless.sh/c.js\" data-key=\"cs_…\"></script>",
  "key": "cs_…",
  "claimSecret": "csk_…",
  "claimUrl": "https://app.capless.sh/claim#csk_…",
  "unclaimedDays": 14
}
```

* `key` (`cs_…`) is public and write-only, so it is safe in HTML. It is derived from the claim secret, and the project ID is derived from the key, so the project needs no setup call: the snippet's first event creates it.
* `claimSecret` and `claimUrl` prove ownership. Give `claimUrl` to the human; never commit it or put it on a page.
* Until it is claimed, the project is unclaimed: it collects up to 250,000 events, 2,500 replays and 10 GB, has no SQL, API keys or members, and is deleted `unclaimedDays` after it was created.
* While unclaimed, `Authorization: Bearer csk_…` reads the project ([allowed endpoints](https://analytics.capless.sh/docs/api.md#claiming)). Use it to check that events arrive.

## Signup API

`POST https://api.capless.sh/v1/signup` creates a user, a project on the 14-day trial and an API key in one call. No authentication. With `claimSecret`, the account takes over the project behind that snippet instead of creating a new one.

| Field | Type | |
|---|---|---|
| `email` | string, required | The human's email. A verification email is sent to it. |
| `claimSecret` | string, optional | A `csk_…` claim secret. The account claims that project (the snippet stays the same). |
| `password` | string, optional | Omit it to sign in with emailed links only. |
| `projectName` | string, optional | |

```sh
curl -s https://api.capless.sh/v1/signup \
  -d '{"email":"jane@example.com","projectName":"acme","claimSecret":"csk_…"}'
```

`201 Created`:

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

* `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.
* `dashboardUrl` is a one-time sign-in link valid for 15 minutes. Give it to the human.
* `plan` is `trial`, or `none` if this email already used its trial (then a plan is needed to collect).
* `409 email_taken`: the human already has an account. Give them the claim link (they claim it after logging in), or ask for an API key from [the dashboard](https://app.capless.sh/login).
* `409 already_claimed`: another account owns the project behind `claimSecret`.
* `429 rate_limited`: wait and retry later; do not loop.

## End-to-end with curl

No CLI, no SDK.

```sh
# 1. A snippet and its claim link
curl -s https://analytics.capless.sh/new -H 'accept: application/json' > capless.json
node -p 'require("./capless.json").snippet'     # paste before </head>
node -p 'require("./capless.json").claimUrl'    # give to the human
export CAPLESS_CLAIM_SECRET=$(node -p 'require("./capless.json").claimSecret')

# 2. After the site is loaded in a browser: events arrived? (read-only while unclaimed)
C="authorization: Bearer $CAPLESS_CLAIM_SECRET"
curl -s 'https://api.capless.sh/v1/streams/$web.events' -H "$C"          # entryCount > 0
curl -s 'https://api.capless.sh/v1/streams/$web.events/read' -H "$C" -d '{"limitResultEntries":5}'

# 3. Optional: an account and an API key now, claiming the project
curl -s https://api.capless.sh/v1/signup \
  -d "{\"email\":\"jane@example.com\",\"claimSecret\":\"$CAPLESS_CLAIM_SECRET\"}" > account.json
export CAPLESS_API_KEY=$(node -p 'require("./account.json").apiKey')
node -p 'require("./account.json").dashboardUrl'    # give to the human
H="authorization: Bearer $CAPLESS_API_KEY"

# 4. 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"}'

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

Single-quote URLs that contain `$web.events`, so the shell does not expand `$web`. Delete `capless.json` and `account.json` once the secrets are 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://analytics.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://analytics.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://analytics.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 |
| `get_snippet` | The project's snippet (one for every site), its settings, and the hostnames that have sent events |
| `update_web_settings` | Change `replaySampleRate` or the optional `allowedOrigins` |
| `list_streams` | Streams with entry counts and heads (web analytics writes to `$web.events` and `$web.replay`) |
| `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://analytics.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://analytics.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-key="cs_…"></script>
```

Put it before `</head>` on every page. Get one from [capless.sh](https://analytics.capless.sh/#install) or with `curl -s https://analytics.capless.sh/new` ([Quickstart](https://analytics.capless.sh/docs/quickstart.md)); a project's snippet is also in the dashboard and in `GET /v1/web`.

The key (`cs_…`) is public and can only write events. Each project has one key, and one snippet works on any number of domains. The project's sites are the hostnames that have sent events; they appear in `hosts` without any setup.

## Settings

Read the snippet, the settings and the hosts with the project API key, a dashboard session, or the claim secret of an unclaimed project:

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

curl -s https://api.capless.sh/v1/web -H "$H"
# → {"key":"cs_…","snippet":"<script async …>","replaySampleRate":1,"allowedOrigins":[],
#    "hosts":[{"host":"shop.example","firstSeen":"…","lastSeen":"…","events":1520}]}

# Changing settings needs an API key or an owner or admin session
curl -s -X PATCH https://api.capless.sh/v1/web -H "$H" -d '{"replaySampleRate":0.25}'
```

| Field | | |
|---|---|---|
| `replaySampleRate` | 0–1, default `1` | Fraction of sessions recorded. |
| `allowedOrigins` | optional, default `[]` (any origin) | Origins whose pages may send events, e.g. `["https://shop.example", "*.shop.example"]`. |

`allowedOrigins` makes browsers on other sites that copied your snippet get `403 origin_not_allowed`. It is a deterrent, not security: anyone can send events with their own HTTP client and any `Origin` header. To bound what such traffic can cost you, set a [spend cap](https://analytics.capless.sh/docs/limits.md#spend-cap).

## 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` (when already known: the load, else DOMContentLoaded, time; often absent because the tag runs before either) |
| `pageleave` | navigating away / tab closing | `visibleMs`, `scrollDepthPct`, `loadMs` (the page's full load time, on the first `pageleave` after a page load), `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` (the key `cs_…`)
* `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)

## Delivery

Browser events are acknowledged once the collector has buffered them, and committed to the stream in batches. A quiet site's requests are saved durably before the acknowledgement and committed within about 30 seconds. A busy site (several requests per second) is buffered in memory and committed about once per second; a collector crash can lose up to about a second of those events. Session replay chunks are sent every 15 seconds and when the tab is hidden or closed. The authenticated [ingestion API](https://analytics.capless.sh/docs/streams.md) is unaffected: it returns only after a batch is durably committed.

The collector answers `402` with the reason in `error.code` (for example `event_limit_reached` or `spend_cap_reached`) while collection is paused; those events are not stored. The first event of a new key creates its project; new projects are rate limited per IP address (`429 rate_limited`).

## Streams

The snippet writes to two built-in [streams](https://analytics.capless.sh/docs/streams.md), created with the project. Built-in stream names start with `$`; they cannot be renamed or deleted (`403 built_in_stream`).

* `$web.events`: one record per event (above). Query it with [`/read` + CEL](https://analytics.capless.sh/docs/reading.md), or [materialize it into ClickHouse](https://analytics.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://analytics.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://analytics.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://analytics.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.
* Names starting with `$` belong to built-in streams, which Capless creates: `$web.events` and `$web.replay` ([Web SDK](https://analytics.capless.sh/docs/web-sdk.md#streams)). They work like any other stream for reads, erasures and materializations, but cannot be renamed or deleted (`403 built_in_stream`). In shell commands, single-quote URLs that contain them (`'https://api.capless.sh/v1/streams/$web.events'`) so the shell does not expand `$web`.
* A **validator** is a [CEL](https://analytics.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://analytics.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://analytics.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://analytics.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://analytics.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://analytics.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://analytics.capless.sh/docs/erasures.md -->

# Erasures & GDPR

Streams are immutable except for **erasures**: delete every entry matching a [CEL](https://analytics.capless.sh/docs/cel.md) predicate, in the stream and in every [materialization](https://analytics.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://analytics.capless.sh/docs/materializations.md#supported-and-unsupported-patterns).
* Session replay records only what the [privacy rules](https://analytics.capless.sh/docs/web-sdk.md#session-replay-privacy) allow, so most personal data is never captured in the first place.

---

<!-- https://analytics.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.

Materializations read streams only through the public API (the [change feed](https://analytics.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://analytics.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://analytics.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 claim secret of an unclaimed project (`Bearer csk_…`) is accepted for the read-only endpoints listed under [Claiming](#claiming). The complete, machine-readable contract is the OpenAPI 3.1 spec: [/openapi.yaml](https://analytics.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) and API key; with `claimSecret`, take over that unclaimed project. No auth. [Details](https://analytics.capless.sh/docs/agents.md#signup-api) |
| `GET` | `/v1/project` | The project: plan, billing (including `spendCap`), `claimed`, `role`, allowance, usage, `web` |
| `PATCH` | `/v1/billing` | Set or clear the monthly spend cap: `{"spendCap": 50}` or `{"spendCap": null}` (owners and admins) |

## Claiming

A snippet from analytics.capless.sh creates an **unclaimed** project with its first event. Its claim secret (`csk_…`) is a bearer token with read-only access to that project until it is claimed:

| Method | Path |
|---|---|
| `GET` | `/v1/project`, `/v1/usage`, `/v1/web`, `/v1/streams`, `/v1/streams/{stream}`, `/v1/replays`, `/v1/replays/{session}/{tab}` |
| `POST` | `/v1/streams/{stream}/read`, `/v1/streams/{stream}/locate` |

Anything else returns `403 claim_required`. Once the project is claimed, the secret returns `401 project_claimed`.

| Method | Path | |
|---|---|---|
| `POST` | `/v1/claim` | `{"secret": "csk_…"}` with a dashboard session: claim the project for the signed-in account |
| `POST` | `/v1/signup` | `{"email": "…", "claimSecret": "csk_…"}`: create an account and claim the project in one call |

Both return `409 already_claimed` if another account owns the project. [Quickstart](https://analytics.capless.sh/docs/quickstart.md)

## 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://analytics.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://analytics.capless.sh/docs/reading.md) · [Time seeking](https://analytics.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://analytics.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://analytics.capless.sh/docs/cel.md)

## Web analytics

| Method | Path | |
|---|---|---|
| `GET` | `/v1/web` | The project's ingest `key`, `snippet`, `replaySampleRate`, `allowedOrigins`, and `hosts` (hostnames that sent events) |
| `PATCH` | `/v1/web` | Change `replaySampleRate` and/or `allowedOrigins` (owners and admins) |
| `GET` | `/v1/replays` | Session recordings from the last 7 days |
| `GET` | `/v1/replays/{session}/{tab}` | Frames of one recording |

[Web SDK](https://analytics.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://analytics.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_claim_secret`, `invalid_spend_cap`, `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`, `project_claimed`, `forbidden`, `claim_required`, `built_in_stream`, `origin_not_allowed`, `query_forbidden` |
| 402 | `trial_ended`, `no_active_plan`, `event_limit_reached`, `storage_limit_reached`, `spend_cap_reached`, `plan_required`, `plan_limit` |
| 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`, `already_claimed` |
| 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://analytics.capless.sh/docs/limits.md -->

# Limits & quotas

## Plan allowances

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

| | Unclaimed (14 days) | Free trial (14 days) | Starter | Team | Enterprise |
|---|---|---|---|---|---|
| Members | none (read-only via the claim secret) | unlimited | 1 | unlimited | custom |
| Events / month | 250,000 | 250,000 | 250,000 included | 250,000 included | custom |
| Session replays / month | 2,500 | 2,500 | 2,500 included | 2,500 included | custom |
| Storage | 10 GB | 10 GB | 10 GB-months included | 10 GB-months included | custom |
| Sites | unlimited | unlimited | unlimited | unlimited | custom |
| Web analytics, session replay, reading data | ✓ | ✓ | ✓ | ✓ | ✓ |
| API keys, MCP, writes, erasures, members, settings | | ✓ | ✓ | ✓ | ✓ |
| ClickHouse SQL | | ✓ | ✓ | ✓ | ✓ |
| Beyond the included usage | collection pauses | collection pauses | pay as you go | 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.
* A **site** is a hostname that sent events. One snippet works on any number of them.
* **Storage** is the compressed size of your streams plus your ClickHouse tables, measured hourly.
* On Starter and Team, usage beyond the included amount is billed: 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; storage $0.10 per GB-month.
* The trial has no card on file, so its limits are hard: collection pauses at a limit until you pick a plan. Data you already collected is untouched.
* An **unclaimed** project is one created by a snippet from analytics.capless.sh that nobody has claimed yet. Its limits are hard, and it is deleted with all its data 14 days after it was created unless it is claimed. Claiming starts the 14-day trial (or needs a plan if the account already had a trial) and keeps the data.
* Data is kept until you delete it ([erasures](https://analytics.capless.sh/docs/erasures.md), or deleting a stream); deleted data stops counting toward storage once it is purged.

## Spend cap

On Starter and Team, owners and admins can set a monthly limit on the whole bill (plan price plus usage beyond the included amount), in USD, at least 5:

```sh
curl -s -X PATCH https://api.capless.sh/v1/billing -H "authorization: Bearer $CAPLESS_API_KEY" -d '{"spendCap":50}'
# → {"spendCap":50}; {"spendCap":null} removes it
```

When the period's estimated bill reaches the cap, collection pauses (`402 spend_cap_reached`) until the next period or until you raise or remove the cap. Data you already collected is untouched. It is off by default, and it is the protection against traffic you did not expect, for example from a copied snippet.

## 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}$` (names starting with `$` are built-in) |
| 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 |
| New projects (first event of an unknown key) | 20 per minute per IP address (`429 rate_limited`) |

---

<!-- https://analytics.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.
* **Ingest keys** (`cs_…`, in the snippet) are public and write-only: they can only send web analytics events to their project. They cannot read data or claim the project.
* **Claim secrets** (`csk_…`) are 160-bit random secrets generated in your browser on capless.sh (or by `GET https://analytics.capless.sh/new`). The ingest key is derived from the secret (SHA-256), and the project ID from the key, so Capless never needs to store the secret. capless.sh keeps it in your browser's `localStorage`, so the page shows the same snippet on your next visit. While the project is unclaimed, the secret gives read-only access to it; claiming the project for an account requires it. Once claimed, it no longer grants access (`401 project_claimed`).
* **Allowed origins** (optional, off by default) make browsers on sites that copied your snippet get `403 origin_not_allowed`. This is a deterrent, not a security boundary: anyone can send events with their own HTTP client. The protection for your bill is a [spend cap](https://analytics.capless.sh/docs/limits.md#spend-cap), which pauses collection when the month's estimated bill reaches it.
* New projects (the first event of an unknown key) are rate limited per IP address, and unclaimed projects have hard caps and are deleted after 14 days.

## 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://analytics.capless.sh/docs/web-sdk.md#session-replay-privacy)).
* `capless("optout")` stops collection in a browser.
* [Erasures](https://analytics.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://analytics.capless.sh/pricing.md -->

# Pricing

Prices are per project, in USD, billed monthly through Stripe. Both plans include the same usage. The only difference is how many people can join the project.

A tag you get from analytics.capless.sh starts collecting into an unclaimed project right away, with the included usage as a hard limit. When you claim it with your email, a 14-day free trial starts. You don't need a credit card for the trial. If nobody claims a project, we delete it after 14 days.

## Plans

| | Starter | Team | Enterprise |
|---|---|---|---|
| Price | $5 / month | $29 per member / month | [Contact us](mailto:hello@capless.sh) |
| Members | 1 | unlimited | custom |
| Included events / month | 250,000 | 250,000 | custom |
| Included session replays / month | 2,500 | 2,500 | custom |
| Included storage | 10 GB | 10 GB | custom |
| Sites | unlimited | unlimited | custom |
| API, MCP, CEL, streams, erasures, ClickHouse SQL | ✓ | ✓ | ✓ |
| Beyond the included usage | 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; storage $0.10 per GB-month | same | custom contract |
| Also | | | SSO, custom contracts, EU data residency |

## Compared at scale

What a month costs at each volume, compared with the big product analytics and session replay tools.

| Monthly volume | Capless Starter (1 member) | PostHog¹ | Mixpanel Growth² | Amplitude Plus³ | LogRocket⁴ |
|---|---|---|---|---|---|
| 10M events | **$24.50** | $324.40 | $840 (annual billing), $1,176 (monthly billing) | $720 | priced per session |
| 100M events | **$204.50** | $2,618.40 | contact sales | contact sales | priced per session |
| 100k session replays | **$53.75** | $272.50 | not published | not published | $717 (billed annually) |
| 10M events + 100k replays | **$73.25** | $596.90 | not published | not published | $717 (billed annually) |

How the Capless numbers add up: $5 includes 250,000 events and 2,500 replays. 10M events = $5 + 9.75 × $2 = $24.50. 100M events = $5 + 99.75 × $2 = $204.50. 100k replays = $5 + 97.5 × $0.50 = $53.75. On Team, add $29 per member instead of the $5.

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.
3. Amplitude Plus, from the pricing calculator on [amplitude.com/pricing](https://amplitude.com/pricing), checked 2026-11-02: 10M events cost $720/month ($6,912/year billed annually). Plus stops at 70M events; Growth and Enterprise are custom. Replay packages beyond the included 10K a month are priced as a share of the plan and not published.
4. LogRocket, from [logrocket.com/pricing](https://logrocket.com/pricing), checked 2026-11-02: billed per recorded session, with analytics events unlimited; the page shows prices only as monthly equivalents of annual plans ($717 for 100K sessions on Pro).

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 counts as storage?

The compressed size of everything you keep: your streams (events, replays, API entries) plus your ClickHouse tables. We measure it every hour. A GB-month is 1 GB kept for a month (or 2 GB for half a month). Typical sizes: about 0.3 KB per event and 50–500 KB per session replay, depending on the page.

### What happens when I go past the included usage?

On Starter and Team, usage beyond the included amount is billed at the rates above, at the end of the month, and collection does not pause unless you set a spend cap. Usage is shown live in the dashboard and through the API.

During the free trial there is no card on file, so the included usage is a hard limit: collection pauses when you reach it, until you pick a plan. Data you already collected is untouched.

### Can I limit what I spend?

Yes. Set a monthly spend cap in the dashboard or with `PATCH /v1/billing` (`{"spendCap": 50}`, in USD, at least $5). When the month's estimated bill (plan price plus usage beyond the included amount) reaches it, collection pauses until the next month or until you raise or remove the cap. It is off by default. [Details](https://analytics.capless.sh/docs/limits.md#spend-cap)

### How is usage beyond the included amount calculated?

Each project includes 250,000 events, 2,500 replays and 10 GB-months of storage per month, on either plan. Beyond that: $2 per 1M events for the first 100M, then $1 per 1M; $0.50 per 1,000 replays for the first 100,000, then $0.25 per 1,000; $0.10 per GB-month of storage.

**Starter, 2M events, 5,000 replays.** Overage: 1.75M events × $2 per 1M = $3.50; 2,500 replays × $0.50 per 1,000 = $1.25. Plan: $5. **Total: $9.75.**

**Team with 3 members, 9M events, 45,000 replays.** Overage: 8.75M events × $2 = $17.50; 42,500 replays × $0.50 per 1,000 = $21.25. Members: 3 × $29 = $87. **Total: $125.75.**

**Starter, 150M events, 10,000 replays.** Overage: 149.75M events = 100M × $2 + 49.75M × $1 = $249.75; 7,500 replays × $0.50 per 1,000 = $3.75. Plan: $5. **Total: $258.50.**

**Any plan, 300 GB stored all month.** Included: 10 GB-months. Overage: 290 GB-months × $0.10 = $29.

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

Pick Starter (just you) or Team (if you invited people) in the dashboard to keep collecting. The trial needs no credit card, so nothing is charged unless you choose a plan. You can switch between Starter and Team at any time; the change is prorated.

### 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://analytics.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. Because data accumulates, storage counts toward your plan (see "What counts as storage?"); delete what you no longer need with [erasures](https://analytics.capless.sh/docs/erasures.md) or by deleting streams.

### What does Team add?

Members. Starter is the one-person version of the same plan; switch to Team to invite people. Everything else, including ClickHouse SQL [materializations](https://analytics.capless.sh/docs/materializations.md), is on both.

### What about Enterprise?

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