# 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.