Publishing creates an artifact and its first immutable version. Updating it later appends more versions without changing the earlier snapshots.
Pick a surface
Use whichever surface matches who (or what) is publishing:
| You are… | Use |
|---|
| A human in the browser | Web dashboard |
| A local coding agent | CLI |
| A backend service or CI job | REST API with an API key |
| An MCP-capable agent | MCP tools |
Create an artifact
The fastest path from a local file to a durable URL is the CLI’s push. The REST and MCP equivalents take the same fields explicitly.
artifacts push --owner alice --project-slug default --file ./report.md
What push infers
push is built for speed — it fills in everything it can from the file:
- Type from the file extension:
.md, .markdown, .html, .htm, .jsx, .tsx.
- Title from the Markdown heading, or the file name.
- Slug from the title.
- Access as public view, private edit.
Override any of it when you need to:
artifacts push \
--owner alice \
--project-slug default \
--file ./prototype.tsx \
--type jsx \
--title "Prototype v1" \
--slug prototype-v1 \
--private
Use --ensure when an agent should reuse an existing artifact instead of failing on a slug conflict:artifacts push --owner alice --project-slug default --file ./report.md --ensure
REST fields
For POST /api/artifacts, these fields are required: ownerUsername, projectSlug, slug, type, title, content, and access. The description and changelog fields are optional.
Publish into a workspace
When you already have a workspace ID, post to the workspace route instead. The body is the same, minus ownerUsername (the workspace is already selected):
POST /api/workspaces/:workspaceId/artifacts
Update an artifact
Appending a version needs only the artifact ID and new content.
artifacts artifact update \
--artifact-id ARTIFACT_ID \
--json '{"content":"# Launch review\n\nUpdated after QA.","changelog":"QA edits"}'
For concurrent writers, include expectedLatestVersion in REST or MCP requests. If the head has moved on, the API returns a conflict instead of silently overwriting another actor’s work.
Check a slug before you publish
Avoid surprises by checking availability and previewing the final URL first:
artifacts artifact slug-availability \
--owner alice \
--project-slug default \
--slug launch-review
artifacts artifact url-preview \
--owner alice \
--project-slug default \
--slug launch-review
