Analytics

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 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). Viewers keep seeing the published version until you publish. 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 and Redo Analytics Page walk them, and List Analytics Page Edits lists them. 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.