capless
Docs Quickstart

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. Its key was generated in your browser and belongs to you. In a terminal, or from a coding agent, use:

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:

{
  "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>:

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

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:

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):

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 to watch sessions and replays.

5. Ask questions

  • From your coding agent: connect the MCP server and ask "which pages had the most rage clicks this week?".
  • With CEL: filter and reshape events server-side on /read (CEL functions).
  • With SQL: materialize $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.

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 and open the claim link instead. Details: For agents.

Track your own events

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.

This page as Markdown

← Overview · For agents →