Skip to content

Project export

A project export is an open, documented copy of one space that people can read, keep and process with ordinary tools. (What v0.1 called a project is a space in v0.2; the API paths and the export format keep the name project.) It is not a backup: it has one space and none of the private or internal data that a backup keeps.

Re-import is not part of this slice. Format version 1 has no import; every export says so in provenance.reimportSupported: false and in its README. An export of a v0.1 instance cannot be imported into v0.2 either, and v0.2 does not upgrade a v0.1 instance (upgrade).

Way Result Who
GET /api/v1/projects/:projectId/export project.json (application/json) A signed-in person with project.manage.
GET /api/v1/projects/:projectId/export?format=bundle The bundle (application/gzip, Content-Disposition: attachment) Same.
./flux export <space id or exact name> [--as EMAIL] [--output FILE] The bundle in exports/ The operator, acting as the account --as names, by default the company’s first owner.

project.manage belongs to a space’s admins and to the company’s owners and admins (access policy). An invisible project answers 404, a visible one the caller may not manage 403, a missing session 401. The command line runs the same core use case as the API inside the API container, as that account, so the policy decides there too (--as a member without project.manage is refused). Responses carry Cache-Control: no-store.

Export metadata is read in one read-only REPEATABLE READ transaction, so all relationships show the same moment even while people keep working. Published attachments are immutable. Bundle generation checks their size and SHA-256 before responding, then reads one file at a time outside SQL and streams tar and asynchronous gzip with backpressure. A disconnected HTTP client cancels further reads. A later missing/corrupt object fails the archive stream; it never silently omits files or writes a successful partial manifest.

flux-project-<first 8 of project id>-<UTC time>/
project.json the whole project (below)
files/<file id> exact published attachment bytes
docs/<doc id>.md current Markdown text of each doc
schema/project-export.v1.schema.json JSON Schema (draft-07) of project.json
README.md what is in it and what is not
manifest.json path, bytes and SHA-256 of every other file

Any tar extracts it (tar -xzf flux-project-….tar.gz). The launcher prints the bundle’s own SHA-256. Only published attachments join the bundle under files/; private staged uploads are excluded. Original display names and relationships are in project.json. JSON-only export carries metadata, while the bundle carries the bytes as well.

A task’s discussion is a conversation of the project, so it is in the conversations array with the others, agents’ messages included (a task has one discussion, #868).

Format flux.project-export, formatVersion 1 (the one current format). The TypeScript types (ProjectExport) and the JSON Schema (PROJECT_EXPORT_JSON_SCHEMA) are in app/packages/contracts/src/export.ts (Apache-2.0); the application tests validate real exports against the schema. Timestamps are ISO 8601 UTC. People and agents are referenced as { "kind": "human" | "agent", "id" }; actors gives their names.

Key Contents
$schema, format, formatVersion, exportedAt Identification.
provenance exportedBy (with name), instanceOrigin (FLUX_PUBLIC_ORIGIN), database schemaVersion, reimportSupported: false.
excluded The list below, repeated in every export.
project Id, name, visibility, creation time, workspace id and name.
people Everyone who can read the project now, with access (manager or contributor) and workspaceRole, decided by the access policy.
grants Explicit project grants (manager or contributor).
actors Names of every person and agent referenced anywhere in the export.
conversations Each conversation with all messages in sequence: author, text, cited material or doc version, time. A message made by a saved blocker, the “what came of it” line or a public handoff also has contribution ({ "kind": "blocker" | "handoff" | "came_of_it" }); ordinary messages omit it. A message its author posted through a local client or with Show everyone also has via, the client’s or assistant’s name (“Claude Code”); the author stays the person.
files (optional) Published attachments: id, display name, size, SHA-256, message and conversation ids, order, and bundle path. Absent for projects without published files. Message files lists id, name and size in attachment order.
materials Published materials with every immutable version: title, text, URL, author, time.
docs Docs with every version: title, Markdown text, reason, author, time, and file (the Markdown file of the current text).
sketches The space’s Maps (called sketches here) with their thoughts (text, position, size, shape, author, version) and links between thoughts (label).
work, decisions All fields: status, blocker, whether it was dropped and what came of it, owner, who proposed and who accepted, supersession.
githubSources (optional) Only for projects with GitHub task rules: dormant: true, the project’s default rule mode and rules (task id, mode, the state it had, enabled: false). Repository bindings are never exported here: a repository’s name, URL and id are private GitHub facts that need the exporter’s own current GitHub proof, which this export does not check. No installation or App ids, tokens, connecting person, deliveries or pull request data either. Nothing imports it yet (reimportSupported: false); a future import must create rules disabled and require a person to connect and authorize repositories on the destination.
links Typed links (source, affects, related, mentions, part_of) whose two ends are both in the export.
  • other spaces;
  • direct messages;
  • private maps (a person’s My map);
  • images placed on map thoughts: the thought and its caption are exported, the image is not in the export; a full backup keeps it;
  • accounts, e-mail addresses, sessions, push subscriptions and notifications;
  • agent connections, OAuth clients, access and refresh tokens and signing keys (secrets of this instance), and pending agent proposals, which are not part of the export;
  • events, idempotency records and other internal rows.

Links whose target the export leaves out are dropped, so an export never names an object it does not contain. (Private drafts and the placement of a note on a map are not in the list above because they no longer exist: they went with “Your notes”, #947, #999.) app/tests/app/export.test.ts checks this with distinctive text in another space, a DM, a private map, and another member’s extra notification address, quiet hours and mute, and also checks that no e-mail address, client mutation id, agent connection id or other project id appears. scripts/check_backup.sh checks the same for ./flux export on the demo data.

The export is a public extension contract (O-010 EXT-2), and nothing is kept compatible before the first public release (rule): a change edits the one current format in place, with no version bump and no reading of an older format. formatVersion names that current format. Readers should ignore unknown fields and treat an unknown enum value as unknown. The JSON Schema rejects unknown top-level keys so that a change to the format cannot go unnoticed in the tests, and app/tests/app/extension-contracts.test.ts pins the schema and bundle layout to app/tests/app/contracts/project-export.json. See integrations.

Task creation Undo keeps every task in the export. Each task carries lifecycle (active, or creation reverted with the notice, time and actor) and creationHistory (trusted origin, immutable baseline, first persisted use, proposal identity, and the original and reversion notices with their actual actors). Active application lists leave creation-reverted tasks out; direct reads and the export name them explicitly. Command receipts stay in full backups, as before.