# Start with the API

1. **Create an API key.** Run `npx countwatch init` in your project: you approve a write key in the browser and it is saved as `COUNTWATCH_API_KEY`. Or sign in at `https://countwatch.com/login` and open **Settings → API keys** in the dashboard. A **write** key only sends data (`POST /v1/ingest`, `POST /v1/import`) and cannot read alerts: put it in your app's secrets as `COUNTWATCH_API_KEY`. An **admin** key manages the account and reads alerts: use it for scripts and CI. A key is shown once; you can name and revoke each one. Send it as `Authorization: Bearer <key>`. An agent connected over MCP needs no key: it signs in with your e-mail and works through its tools.
2. **Send a count.** A watch is one metric plus its tags (such as `shop:EU`); the first point creates it.

   ```
   curl -X POST https://countwatch.com/v1/ingest \
     -H "Authorization: Bearer $COUNTWATCH_API_KEY" -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{"points":[{"metric":"orders","tags":{"shop":"EU"},"add":3}]}'
   ```
3. **Choose where alerts go.** Add Slack, a webhook, e-mail or PagerDuty (`POST /v1/destinations`, then `POST /v1/destinations/{id}/verify`) with an admin key, then choose it: `PATCH /v1/groups/{id}` or `PATCH /v1/watches/{id}` with `destination_ids`. With none chosen, alerts stay in the app. A write key cannot read alerts. Without a public address, read them with `GET /v1/alerts?since=…` and that admin key.
4. **Skip the wait.** A new watch first gets to know your pattern (`status: "learning"`); simple starter rules alert meanwhile. Import past counts (`POST /v1/import`) and alerts start now.

Errors follow RFC 9457 (problem details): each has a stable `code`, a fix page linked from its `type`, and a `Request-Id` to quote when you write to us. A rejected point carries `{index, code, field, detail}`.