docs menu

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#

bash
galerne export --out ./backup
bash
curl "https://api.galerne.cloud/p/acme/v1/export?branch=main" \
  -H "Authorization: Bearer gal_…" -o acme.ndjson

The 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#

json
{"kind":"schema","format":"galerne-export/1","project":"acme","branch":"main","exportedAt":"2026-10-16T09:30:00.000Z","config":{"languages":["en","fr"],"types":{}}}
FieldWhat it holds
formatgalerne-export/1
project, branchWhere the export comes from
exportedAtISO 8601 time
configThe deployed galerne.config.ts, as JSON

doc#

json
{"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"}
FieldWhat it holds
id, typeDocument id and type
valuesThe latest values. Document-level translations carry _lang and _translationOf here
publishedThe published values, or null if never published
updatedAtISO 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#

json
{"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#

json
{"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:

json
{"kind":"doc","id":"harbours","type":"post","values":{"title":"Harbours of Brittany","body":"Brittany has **many** harbours."},"publish":true}
FieldWhat it does
id, type, valuesRequired. Rich text may be Markdown.
publishPublish 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:

json
{ "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.