# Export format

> The galerne-export/1 format, newline-delimited JSON with schema, doc, media and end lines, available on every plan, and the import lines it pairs with.

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":{}}}
```

| 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

```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"}
```

| 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

```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}
```

| 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:

```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.
