# SnapCount Public Read API

Read counters, current totals, and recent count events with an organization API key. The API is read-only and available to Pro and Enterprise organizations.

## Authentication

Base host: `https://api.snapcount.app`. Send an organization API key on every request:

```http
Authorization: Bearer sc_live_...
```

Owners and admins create and revoke keys in Settings, Developers. The full key is shown once. An organization can hold up to 10 keys.

## List counters

`GET /api/v1/counters` returns the organization's counters and their current totals, sorted by name.

```bash
curl https://api.snapcount.app/api/v1/counters \
  -H "Authorization: Bearer sc_live_..."
```

```json
{
  "counters": [
    {
      "id": "cm1gatea0001",
      "name": "Gate A",
      "count": 187,
      "incrementStep": 1,
      "decrementStep": 1,
      "mode": "both",
      "organizationId": "cm1org0001",
      "groupId": null,
      "goalTarget": null,
      "locked": false,
      "version": 212,
      "lastEventId": 5812,
      "createdAt": "2026-09-20T08:00:00.000Z",
      "updatedAt": "2026-09-26T18:42:10.000Z"
    }
  ]
}
```

## Get a counter

`GET /api/v1/counters/:counterId` returns one counter in the same shape. An unknown id returns 404.

## Counter history

`GET /api/v1/counters/:counterId/history` returns recent count events, newest first. Metadata-only `update` rows are omitted.

- `limit`: events to return. Default 100, maximum 500.
- `beforeEventId`: return events with a `lastEventId` lower than this value. Pass the last event's `lastEventId` to read the next page.

```bash
curl "https://api.snapcount.app/api/v1/counters/cm1gatea0001/history?limit=50" \
  -H "Authorization: Bearer sc_live_..."
```

```json
{
  "counterId": "cm1gatea0001",
  "counterName": "Gate A",
  "events": [
    {
      "id": "cm1evt5812",
      "counterId": "cm1gatea0001",
      "eventType": "increment",
      "count": 187,
      "previousCount": 186,
      "delta": 1,
      "lastEventId": 5812,
      "metadata": null,
      "createdAt": "2026-09-26T18:42:10.000Z"
    }
  ]
}
```

## Rate limits

Limits are per API key. Pro: 60 requests per minute and 1,000 per hour. Enterprise: 300 per minute and 10,000 per hour. Over the limit the API returns 429 with `code: RATE_LIMITED`. Responses carry standard `RateLimit` headers.

## Errors

- 401: the key is missing, revoked, or wrong. Body: `{ "error": "Unauthorized" }`.
- 403: the organization is not on Pro or Enterprise.
- 404: the counter does not exist in this organization.
- 429: the key is over its rate limit.

```json
{
  "error": "The public API requires a Pro plan",
  "code": "PLAN_REQUIRED",
  "requiredPlan": "organization"
}
```
