---
title: 'Analytics'
description: 'How Cirra Analytics is put together, and what the Analytics API acts as: pages, panels, data sources, drafts, sharing and permissions.'
---

The Analytics API does everything Cirra's Analytics assistant does, as plain requests. Every endpoint name below links to its reference page. [Analytics Building Guide](/docs/api/rest/introduction/analytics-building-guide) is the short path to a working page.

## The parts

- **Data sources** hold rows. A _sync_ source fetches from an app's read action on a schedule and stores the rows. A _live_ source fetches only when a drill-down opens. A _merge_ combines sources with SQL and code. A _fixed_ source holds rows you send. Sources belong to a person, not to a page, and many panels can read one source.
- **Pages** are what people open: a grid of panels, with optional tabs and variables. A _report_ is a page with one written panel that fills it. A _subpage_ opens when someone clicks a panel on another page.
- **Panels** show rows. Each reads one or more sources through DuckDB SQL, optionally reshapes them with transform code, and draws them as a table, chart, stat tile or another display type. A _drill-down_ panel (placement `drill`) is off the grid and opens when another panel is clicked.
- **Variables** are a page's filters: date windows, dropdowns, search boxes and switches. Panel SQL reads each one as `$name`.
- **Publications** send a page by email, Slack or Teams on a schedule.

## Who the API acts as

Analytics belongs to people. A request acts as the person who created the API key, in an organization where they are a member: the pages and sources it creates are theirs, and it can open exactly what they can open in the app. Their Analytics seat, their role and the pages shared with them apply to every request. A request naming another organization in `X-Company-Id` works only where that person is a member.

Three API key permissions govern Analytics:

| Permission              | Allows                                                                                                                                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `analytics:page:view`   | Every read. Every member holds it.                                                                                                                                                                     |
| `analytics:page:create` | Making something new (pages, subpages, duplicates, data sources, publications, themes, template installs) and everything the app keeps to builders, such as changing sources and sending publications. |
| `analytics:page:edit`   | Changing pages, panels, variables, tabs and shares, and publishing.                                                                                                                                    |

A key acts with a permission only while its creator holds it too.

## Drafts and publishing

Every change to a page goes to its draft, and takes the draft's revision in `If-Match` (see [Analytics Building Guide](/docs/api/rest/introduction/analytics-building-guide)). Viewers keep seeing the published version until you [publish](/docs/api/rest/actions/publish-analytics-page). [Get Analytics Page](/docs/api/rest/actions/get-analytics-page), and every panel read, answers the published version when the page has one unless you pass `version=draft`; read the same version for the page and its panels.

Each change is one undo step, as in the app: [Undo Analytics Page](/docs/api/rest/actions/undo-analytics-page) and [Redo Analytics Page](/docs/api/rest/actions/redo-analytics-page) walk them, and [List Analytics Page Edits](/docs/api/rest/actions/list-analytics-page-edits) lists them. [List Analytics Page Versions](/docs/api/rest/actions/list-analytics-page-versions) lists what has been published, and any version can be restored into the draft.

## Cirra chats

Nothing the API creates opens a Cirra chat. A page, panel or source gets its chat the first time someone opens it in the app.