> ## Documentation Index
> Fetch the complete documentation index at: https://tinyanalytics.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# tinyanalytics API Reference

> Send events, read analytics, manage sites, and run scoped SQL with the tinyanalytics HTTP API at https://dash.tinyanalytics.io.

The tinyanalytics API lets you **send server-side events**, **read analytics**, and **manage sites programmatically** alongside the browser [tracking script](/docs/install-tinyanalytics-tracking-script). Every endpoint uses one base URL:

```
https://dash.tinyanalytics.io
```

Ingestion endpoints (`/api/track`, `/api/identify`) accept events; read endpoints (`/api/sites/{siteId}/…`) return your data as JSON. Most calls are a single request with a JSON body.

## What can the API do?

The API covers **133 endpoints across 29 groups** — far more than reading metrics. Alongside the analytics reads you can manage sites, define goals and funnels, drive feature flags and experiments, run surveys, build dashboards, configure alerts and scheduled reports, and operate uptime monitors. Every endpoint has its own page in the **Endpoints** section of this reference.

## How do I authenticate?

There are two credentials, and which you need depends on what you're doing:

| What you're doing                       | Credential                                                                                              |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Sending events from a browser**       | None — the `data-site-id` in the [snippet](/docs/install-tinyanalytics-tracking-script) identifies the site. |
| **Sending events from a server**        | An **API key** as `Authorization: Bearer <key>` (lets you send the visitor's real IP and user agent).   |
| **Reading analytics or managing sites** | An **API key** as `Authorization: Bearer <key>`.                                                        |

You create an API key in your **account settings** — see [API keys](/docs/api-reference/api-authentication). Reads and management are authorized by the key owner's access, exactly as if they had signed in.

If an **AI agent** is doing the work rather than code you write, you can skip the HTTP calls entirely: the [MCP server](/docs/api-reference/mcp-server) exposes this same surface as tools that Claude Code, Cursor, VS Code, and Codex CLI can call with the same key.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://dash.tinyanalytics.io/api/sites/1/overview \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```js JavaScript theme={null}
  await fetch("https://dash.tinyanalytics.io/api/sites/1/overview", {
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  })
  ```

  ```python Python theme={null}
  import requests

  requests.get(
      "https://dash.tinyanalytics.io/api/sites/1/overview",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
  )
  ```
</CodeGroup>

<Note>
  Browser ingestion is intentionally open (any origin, no credentials) so the tracker works from your visitors' pages. Every other endpoint requires a credential, and cross-origin reads are restricted to trusted origins — a third-party site can't read your logged-in analytics.
</Note>

## What do responses look like?

* **Ingestion** (`/api/track`, `/api/identify`) returns **`204 No Content`** — the event is queued and written asynchronously, so there's no response body to parse.
* **Reads** return **`200`** with a JSON body. List endpoints are shaped `{ "data": [ … ] }`.

Common status codes:

| Code  | Meaning                                                     |
| ----- | ----------------------------------------------------------- |
| `200` | Success (reads).                                            |
| `204` | Accepted (ingestion) — no body.                             |
| `400` | Invalid input (a bad field or an unknown site ID).          |
| `401` | Missing or invalid credential on a private site.            |
| `403` | Authenticated, but not a member of the site's organization. |
| `404` | Unknown site.                                               |
| `429` | Ingestion rate limit exceeded for the API key.              |

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Do I need an API key to send events from the browser?">
    No. Browser ingestion needs no credential — the `data-site-id` in the [tracking script](/docs/install-tinyanalytics-tracking-script) identifies the site. You need an API key to send events from a server, to read analytics, or to manage sites.
  </Accordion>

  <Accordion title="Why do ingestion endpoints return no response body?">
    `/api/track` and `/api/identify` return `204 No Content` because the event is queued and written asynchronously. There is nothing to parse. Read endpoints return `200` with a JSON body instead, and list endpoints are shaped `{ "data": [ … ] }`.
  </Accordion>

  <Accordion title="What is the difference between a 401 and a 403?">
    A `401` means the credential is missing or invalid on a private site. A `403` means the request authenticated fine, but the key's owner is not a member of the site's organization.
  </Accordion>
</AccordionGroup>

## Start here

<Columns cols={2}>
  <Card title="Tracking API" icon="paper-plane" href="/docs/api-reference/track-events-api">
    Send pageviews and custom events to /api/track.
  </Card>

  <Card title="Identify API" icon="user" href="/docs/api-reference/identify-users-api">
    Attach a stable user ID and traits.
  </Card>

  <Card title="Analytics read API" icon="chart-line" href="/docs/api-reference/analytics-read-api">
    Read overview, timeseries, and breakdowns.
  </Card>

  <Card title="All endpoints" icon="list" href="/docs/api-reference/overview/get-overview">
    Browse all 133 endpoints by group.
  </Card>

  <Card title="API keys" icon="key" href="/docs/api-reference/api-authentication">
    Create and manage your keys.
  </Card>

  <Card title="API playground" icon="terminal" href="/docs/api-reference/api-playground">
    Run any call against your own data.
  </Card>
</Columns>


## Related topics

- [tinyanalytics API Playground](/docs/api-reference/api-playground.md)
- [Analytics Read API](/docs/api-reference/analytics-read-api.md)
- [tinyanalytics Account Settings](/docs/tinyanalytics-account-settings.md)