Export format
Every plan can export everything, Free included. An export is newline-delimited JSON (NDJSON): one JSON object per line, each with a kind. The format is versioned; this page describes galerne-export/1.
Get an export#
galerne export --out ./backupcurl "https://api.galerne.cloud/p/acme/v1/export?branch=main" \
-H "Authorization: Bearer gal_…" -o acme.ndjsonThe API streams application/x-ndjson and needs a token with the read scope; every role may export. branch defaults to main, and a branch export holds what that branch shows: its own changes, and main for everything else. The CLI writes export.ndjson, downloads every media file into media/, and saves the schema next to them.
With the client, galerne.export({ branch }) returns the lines one by one as an async iterator.
Lines#
The file always has this order: one schema line, the doc lines sorted by id, the media lines in upload order, and one end line. A file without its end line is incomplete.
schema#
{"kind":"schema","format":"galerne-export/1","project":"acme","branch":"main","exportedAt":"2026-10-16T09:30:00.000Z","config":{"languages":["en","fr"],"types":{}}}| Field | What it holds |
|---|---|
format | galerne-export/1 |
project, branch | Where the export comes from |
exportedAt | ISO 8601 time |
config | The deployed galerne.config.ts, as JSON |
doc#
{"kind":"doc","id":"harbours","type":"post","values":{"title":"Harbours of Brittany","_lang":"en","body":{"type":"doc","content":[]}},"published":{"title":"Harbours of Brittany","_lang":"en","body":{"type":"doc","content":[]}},"updatedAt":"2026-10-15T16:40:12.000Z"}| Field | What it holds |
|---|---|
id, type | Document id and type |
values | The latest values. Document-level translations carry _lang and _translationOf here |
published | The published values, or null if never published |
updatedAt | ISO 8601 time |
Values are stored values: rich text as ProseMirror JSON, references as { "_ref": "<id>" }, images as { "asset": "<media id>", … }, localized fields as { "<lang>": value }.
media#
{"kind":"media","id":"m_7Qk2…","url":"https://api.galerne.cloud/p/acme/media/m_7Qk2…","filename":"harbour.jpg","mimeType":"image/jpeg","size":482113,"width":2400,"height":1600,"alt":"Harbour at dawn","credits":"Ada","tags":["brittany"],"hash":"9f2c…"}hash is the SHA-256 of the file's bytes. url downloads the original. In an export folder written by galerne export, url is replaced by file, the path of the downloaded file (media/<id>.<ext>).
end#
{"kind":"end","docs":412,"media":96}The counts let you check that nothing is missing.
Import lines#
POST /p/<project>/v1/import?branch=<branch> takes NDJSON lines in a simpler shape, one document per line:
{"kind":"doc","id":"harbours","type":"post","values":{"title":"Harbours of Brittany","body":"Brittany has **many** harbours."},"publish":true}| Field | What it does |
|---|---|
id, type, values | Required. Rich text may be Markdown. |
publish | Publish the document after writing it |
A published document with a newer draft is two lines: the published values with "publish": true, then the draft with "publish": false. Lines of another kind are skipped. Documents are compared with what is stored first, so the same file can run twice: unchanged documents stay unchanged and are not published again. Add dryRun=1 to the URL to get the report without writing. The branch defaults to import/<date> and is created when missing; importing on main needs the import right (editors and admins) and, for tokens and agents, the right to write on main. Up to 100,000 documents and 100 MB per request.
The answer is a report with one result per document:
{ "branch": "import/2026-10-16", "dryRun": false, "created": 410, "updated": 2, "unchanged": 0, "failed": 1, "published": 398, "results": [{ "id": "old-page", "type": "page", "status": "failed", "published": false, "errors": [{ "path": "title", "rule": "required", "message": "required" }] }] }Upload media first with POST /v1/media; the x-galerne-media-id header keeps the media id of the source, so asset values keep working. galerne import <folder> does both from an export folder.
Versioning#
A change that removes or renames a field of a line, or changes its meaning, gets a new format name, such as galerne-export/2. New fields can appear in galerne-export/1; ignore the ones you do not know.