Overview
Astrato workbooks can be exported via the REST API as an .astx file. That file is a plain uncompressed zip, so every asset inside it is diff-able and commit-able. The workflow has three steps: export, unzip, and push.
1. Export over API
ℹ️ Export is also available in the lobby, by clicking on the workbook menu.
Endpoint:
GET https://app.astrato.io/tenant/{tenantId}/workbook/{workbookId}/export-to-astxRequires a valid bearer token. The response is the .astx binary.
Example (curl):
bash
curl -X GET \ "https://app.astrato.io/tenant/$TENANT_ID/workbook/$WORKBOOK_ID/export-to-astx" \ -H "Authorization: Bearer $TOKEN" \ -o workbook.astx
2. Unzip
.astx is uncompressed, so a standard unzip works with no flags:
bash
unzip workbook.astx -d ./workbook
Contents after unzip:
File | Type | Notes |
sheets | JSON | Largest file (~896 KB); contains sheet layout and component config |
dataview | JSON | Data model definitions |
actions | JSON | Button/event actions |
variables | JSON | Dashboard variables |
references | JSON | External data references |
navigation | JSON | Page/tab navigation config |
workbookTheme | JSON | Brand and theme tokens |
workbookMedia | JSON | Embedded media references |
metadata | JSON | Workbook metadata |
workbook | JSON | Top-level workbook config |
globalState | JSON | Global state config |
workbookVersionContainer | JSON | Version metadata |
tenantMedia | JSON | Tenant-level media links |
media/ | PNG / JPG / XLSX | Binary assets (images, Excel files) |
3. Upload files as a version
With the folder unzipped, commit everything. Binary files in media/ will be stored as blobs; the JSON files are fully human-readable and will produce meaningful diffs.
bash
cd ./workbook git init # only needed once per repo git add . git commit -m "chore: export workbook v$(date +%Y%m%d-%H%M)" git push origin main
For a CI/CD pipeline, wrap steps 1–3 in a script triggered on a schedule or on a deployment event:
bash
#!/bin/bash set -e # 1. Export curl -sX GET \ "https://app.astrato.io/tenant/$TENANT_ID/workbook/$WORKBOOK_ID/export-to-astx" \ -H "Authorization: Bearer $TOKEN" \ -o workbook.astx # 2. Unzip into versioned folder rm -rf ./workbook && mkdir workbook unzip -q workbook.astx -d ./workbook # 3. Commit and push cd workbook git add -A git diff --cached --quiet || git commit -m "workbook: snapshot $(date -u +%Y-%m-%dT%H:%M:%SZ)" git push origin main
The git diff --cached --quiet || ... guard skips an empty commit if nothing changed since the last export.
Bulk creating/modifying measures
If you have an existing astx file, with a populated semantic layer (AKA dataview file), you may have some success using AI coding agents such as Claude Code/OpenAI Codex, to update or add measures in bulk.
Example prompt
astx files are astrato workbook files, zipped without compression. They're made up of smaller json files without a file extension, for example the dataview is the astrato semantic layer.
I have an astx workbook extracted in my working folder <WorkbookName>.
Tasks:
I need measures duplicated, where the duplicates rely on fields from new tables that are prefixed with agg, ideally one "agg" table at a time, since these are smaller tables. In the measure name, append the name of the agg table e.g. `known_ppp [agg xyz]`