Publishing

Every change to what an artifact holds is one call, save_artifact. It makes a new version — live (the default) or staged — or writes the artifact's draft. A version never changes once saved and nothing deletes one; the address serves exactly one version, or none.

Choose the route for the files

What you hold What to send
A folder or file on disk, with 23a installed and signed in 23a publish <path> --to <key> --json reads it locally; see large-sites for separate-stream capture.
Text or binary bytes in the conversation files: [{path, content, encoding}], with binary content base64-encoded.
Bytes too large to inline Stage them with upload_file, then send {path, upload}; see large-sites.
A file already saved in another artifact {path, from: "<artifact>@<version>/<path>"} copies it on the server. from is an artifact reference, never a local filesystem path.
Settings kept beside a site's files Root artifact.json; the server validates and applies it. Existing access changes use update_access.

A new artifact

  1. Gather every file into files. Each entry is { path, content, encoding }:
    • path — the file's path within the site, e.g. index.html, styles.css, img/logo.svg. No leading slash, at most 1,024 characters.
    • Text files (HTML, CSS, JS, SVG, JSON, markdown): encoding: "utf8" (the default).
    • Binary files (PNG, JPEG, fonts, …): base64 of the bytes, encoding: "base64".
    • The server is remote and cannot read your sandbox or the person's disk: every file arrives inline, staged ({ path, upload }, see large-sites), copied from material ({ path, from }, see library), or as a zip ({ archive: "<base64>" }, expanded on arrival). With a shell on the person's own machine and the command line installed (23a whoami answers), 23a publish <folder> --to <key> --json reads the folder from disk and saves it for you — see large-sites.
    • A page needs an entry page: index.html, or entrypoint naming another of its paths.
  2. Call save_artifact { name, files }, or leave name in the root artifact.json alone when that file supplies it. An inferred HTML title or folder name must not duplicate a different configured name; an explicit name supplied both ways must agree. Also, only when a save makes an artifact:
    • key — a name for tools to find it by (docs-site): one to sixty-three lowercase letters, digits and hyphens, unique in its workspace, and part of no address, link preview, title or share link. Left out, the artifact has none — nothing is derived from name. Give one whenever you will save it again (see Saving by key); set, rename or clear it later with update_artifact_settings { artifact, key } (null clears).
    • workspace — a handle, to make it in a workspace the person belongs to; their own when left out.
    • kind — page, deck, markdown, file, or a material kind (image, video, sound, font, theme). Left out, it is recognised from the content: a document is a deck, files with an entry page a page, one markdown file markdown, any other single file a file. A markdown artifact is shown to people as a page of ours, with the crate and comments, and read by a program at the same address as the file it is. Material is made only by naming its kind (see library). The kind is fixed at birth: a later save whose content does not fit it is refused naming the kind.
    • description (one line, at most 280 characters), tags, access and preview (see below).
  3. Give the person the address from the answer: <id>.23a.so, fixed from the moment the artifact exists — its only address. The answer also carries id (the identifier), key when it has one, kind, state, version (number, its own pinned address, live, staged), files (per path its bytes and sha256 — compare them with your own files instead of fetching them back), whoCanOpen (every way in, as one sentence) and dashboardUrl. next says what comes next: the preview image being made, a staged version one set_artifact_state away, the workspace's default theme when the save did not use it.

Saving by key

save_artifact { key, files } names the artifact by its key in the workspace the save acts in (workspace, else a credential's own, else the person's own). When no artifact there holds that key, the save makes one carrying it; when one does, the save is that artifact's next version. So an agent, a CI job or a command line that always passes the same key makes its artifact once and versions it on every run after — no need to look it up first, and no save by key is ever refused as already taken. On a save that versions, name, description and tags are optional; any sent are left as stored and the answer's next says so (change them with update_artifact_settings), and a kind the artifact is not is refused. A key held by a deleted artifact is refused until it is restored (set_artifact_state), and is freed when the artifact is purged. A key names nothing outside its workspace.

A new version of an artifact

Pass artifact — its address, its identifier or its key, whichever you hold — and the content, in one of three forms:

Use artifact or key, never both: { artifact, files } names an existing artifact, while { key, files } creates it once and versions it thereafter. Leave out key even when it equals the stored key; renaming or clearing that setting is update_artifact_settings { artifact, key }.

  • The whole of it: files (or document, for a deck or a theme). The version holds exactly what you send. The answer's leftOut lists every path the version it replaces had and this one does not (the first 50, then more), so nothing is ever dropped without saying so; leaving out the entry page is refused unless you name a new entrypoint.
  • Changes on a base: base — a version number, "live" or "draft" — with changes, applied on the server; every file you do not name is carried over by digest, moving no bytes. A change is { path, content, encoding } (written whole), { path, upload }, { path, from }, { path, remove: true }, or { path, replace: { old, new, all? } } — a text edit inside the file, where old must occur exactly once unless all: true. At most 2,000 changes. This is the way to change a few files of a big site: it cannot drop the rest.
  • A base alone: base and nothing else saves that version's content again as the newest — the way to bring an earlier version back as a new one, or to make the draft a version.

A base older than the newest version is accepted, and the answer's base.newer names the versions the save does not include. A save identical to the live version makes no version and says so (noop: true); identical to the draft, it writes nothing.

Live, staged or the draft

as decides how a save lands:

  • "live" (the default) — the new version is what the address serves, at once.
  • "staged" — the version is saved at its own pinned address and the address keeps serving what it served; set_artifact_state { artifact, state: "live", version } makes it live later. A first save staged leaves the artifact offline: nothing is live, and its address says so.
  • "draft" — the artifact's draft: one per artifact, served at no address and read only by people who can edit it. Fill it whole, or with changes on base: "draft" (or on a version, which puts the draft back to that version first). Every save into the draft names the draft's revision it read — the answer gives the new one — and a stale revision is refused as a conflict carrying the current one, so two writers never overwrite each other unseen. save_artifact { artifact, base: "draft" } then makes the draft a version, live or staged. get_artifact_files { artifact, version: "draft" } reads it.

Save live unless the person asked for a step before it goes live. Versions are immutable and going back is one set_artifact_state call, so saving live is already safe; a staged version sits unseen until someone makes it live. Someone who can edit but may not make changes live has a live save staged, and the answer says so and who may make it live.

Copies and remixes

base: "<other artifact>@<version>" (or @live), with no artifact, makes a new artifact from that version: pass changes (or a deck's patch) to remix it — which needs only that you can open it — or nothing, to duplicate it, which is its owner's. The new artifact records its source, and the source's source, and every read of it names them. name and key name the copy as they name any new artifact; a key the workspace already holds is refused for a copy.

What else a save takes

  • note — why this version exists, in your words, at most 2,000 characters; kept with the version and shown with it. A save into the draft takes none.
  • work — the work item this save answers (see comments). Any save you make while you hold work on the artifact is that work's save, named or not: where the artifact's agent policy needs approval, it is staged whatever as says, and waits for a person to make it live.
  • theme — a theme to copy in as theme.css (link it from your HTML; a markdown artifact's page links it for you and is drawn in the theme): its address, identifier or key (the workspace's own first, then ours), pinned with @<version> if you like; "none" says you chose none. A theme.css you send yourself wins. See themes.
  • keepPhotoMetadata: true — keeps every photograph in this save (JPEG, PNG, WebP, GIF, AVIF, HEIC; staged ones too) exactly as sent. Without it, each is kept without where it was taken — GPS and place names — and without the camera's and lens's serials and the owner's name; orientation, date and camera model stay, and the pictures are never re-encoded. Pass it only when the person wants the location published; each file in the answer says photoMetadata: "removed" or "kept". A file copied with from is not read again.
  • validate: true — runs every check and answers as the save would, in the same words, saving nothing.

Settings as a file: `artifact.json`

artifact.json at the root of a save's files — sent inline, staged, inside a zip, or written by a change — is read as the artifact's settings and kept nowhere: no version or draft holds it and no address serves it. Any other path is an ordinary file. It is one JSON object, at most 64 KB, every key optional:

  • name, description (one line; null clears it), tags (the whole list) — on a new artifact the save's own fields; on an existing one, the change update_artifact_settings makes.
  • library (true/false), room (on/off), crate (shown/hidden), search (listed/unlisted; listing needs {"kind": "anyone"} in access), agentPolicy (workspace, approval, live) — set as update_artifact_settings sets them; on a new artifact, once it is made.
  • access and preview, in the shapes the save takes — a new artifact's own; on an existing one they must equal what is stored, and a different value is refused naming update_access, so a file never changes who can open it.

A key left out leaves its setting as it is. A key equal to what is stored changes nothing and needs nothing, so a file read back and saved again changes nothing. A key that changes something needs what update_artifact_settings needs — Edit for the words, the tags and the library, the owner for the room, the crate and the agent policy — and, from a credential, its manage scope on an existing artifact. On a new artifact a field passed both in the save and in the file must agree. The file is applied after the version is written or found unchanged, so a file sent with unchanged content changes the settings and makes no version (noop: true). The answer's settings lists each change in a sentence, empty when there was none; with validate: true it names the keys the file would change, and nothing changes.

Refused whole, writing nothing: the file in a save as: "draft" (settings are the artifact's, never the draft's); a file that is not one JSON object; a key outside the list above, named, with the keys it takes — theme, domain and provenance are not among them yet; a value its setting refuses, in that setting's words; a change the saver may not make. A backup's artifact folder holds the file in this shape, so that folder saved back as it stands changes nothing.

Redirects and headers: `_redirects` and `_headers`

Two files at the root of what a save makes are read as the artifact's own rules, in the part of Netlify's and Cloudflare Pages' syntax both read. Unlike artifact.json they stay in the version, so each version keeps its own, and neither is served at its own path.

  • _redirects, one rule a line, # for a comment: from to [status][!]. from is a path; :name matches one segment and a final * the rest. to is a path, which may use :name and :splat, or an https:// address for a redirect. Status 301, 302 (when none is given), 303, 307 or 308 redirects; 200 answers with to's file at the address asked for, and 404 does the same as not found. A real file wins: a rule answers only a path the artifact has no file for, unless its status ends ! — so /* /index.html 200 serves an app's routes and leaves its scripts and images alone. The first rule that matches is the only one. A redirect carries the visitor's query when to names none, never a share link's token. At most 2,000 rules without a placeholder or * and 100 with one; 1,000 characters a line.
  • _headers: a path line (same patterns), then indented Name: value lines it adds to every file of the artifact it matches. A file may set Content-Security-Policy (sent beside ours, so it only narrows), Permissions-Policy, the three Cross-Origin-*-Policy headers, X-Frame-Options, X-Robots-Tag (beside ours: it never lifts noindex), Content-Disposition, Content-Language, Link, and custom X- headers. Cookies, caching, cross-origin reading and content type stay ours; so does removing a header (! Name). At most 100 blocks; 2,000 characters a line.

They act after the gate, so someone not let in never sees where a path leads. A line either file cannot read refuses the save, naming the file, the line and why, and writes nothing — validate: true checks them too. A draft's are read when it is published. A version saved before these files were read keeps them as ordinary files.

Things refused by name

  • An existing artifact's name, description, tags, kind, key and workspace are not a save's fields to change — a save naming it by artifact with any of them is refused (one reaching it by key keeps them as stored, above): settings change with update_artifact_settings or an artifact.json (above), access and the link preview with update_access. A save may pass the access and preview already stored; a different one is refused.
  • An unknown field in a document is refused, naming the nearest field that exists.

Description and tags

Pass description so the artifact can be found later: list_artifacts matches it, and it shows under the name. Pass tags (lowercase, e.g. ["client-acme", "2026"]) when some clearly apply, reusing the workspace's own vocabulary — list_artifacts's facets.tag lists every tag in use — rather than inventing one-offs. A new artifact without tags gets up to three of the workspace's existing tags whose exact token appears in its name. Change either later with update_artifact_settings.

The sandbox

Artifacts serve on an isolated origin under a sandbox policy: external https: scripts, styles, fonts, images and fetch work; cookies, localStorage/IndexedDB, credentialed requests and wss: do not. For state that survives a reload or is shared between viewers, use the room. See runtime and rooms.

Multi-page static exports work: /route serves route/index.html (or route.html).