---
title: "Edit artifact files"
method: POST
path: "/v1/artifacts/{id}/edits"
tags: ["Artifacts"]
---

# Edit artifact files

`POST /v1/artifacts/{id}/edits`

## Request

- Base URL: `https://shareout.site`
- URL: `https://shareout.site/v1/artifacts/{id}/edits`
- Auth: HTTP bearer

Change an artifact with small operations instead of re-publishing every file. The ops run in order on the newest version, which `base_version` must name; if any op fails nothing is written. The result is published as the next version through the normal publish pipeline (moderation, tests gate, readiness), and files the ops leave unchanged are carried over without re-uploading. Counts once against the daily publish limit (`dry_run` does not). Requires the editor role. Works on html, markdown, csv, txt and json artifacts. Workspace Agent tokens need `artifacts:publish` and reach only artifacts in their own workspace. Renaming or deleting the mobile entrypoint turns the artifact's mobile view off. Send `Idempotency-Key` to make retries safe.

## Request body

- EditRequest
  - `base_version` integer, required: The `version_no` of the files you read; must be the newest version.
  - `ops` EditOp[], required
    - `op` 'replace' | 'write' | 'delete' | 'rename', required
    - `path` string
    - `old` string
    - `new` string
    - `all` boolean
    - `content` string
    - `encoding` 'utf8' | 'base64'
    - `from` string
    - `to` string
  - `message` string: Note for the version history.
  - `dry_run` boolean: Report `changes` without saving anything.

## Response `200`

`dry_run: true` (`{dry_run, base_version, would_create_version, entrypoint, changes}`), or ops that leave every file as it was (`{unchanged: true}`): no version is created.

- object
  - `dry_run` boolean
  - `unchanged` boolean
  - `base_version` integer
  - `would_create_version` integer
  - `changes` FileChange[]
    - `path` string
    - `change` 'added' | 'modified' | 'deleted' | 'renamed'
    - `from` string: Old path of a renamed file.
    - `size_before` integer
    - `size_after` integer
    - `replacements` integer

## Other responses

- `201`: Saved as a new version. Same body as `POST /v1/publish`, plus `base_version` and `changes`.
- `400`: Malformed request (`VALIDATION_ERROR`, `INVALID_OPS`, `INVALID_PATH`, `INVALID_JSON`).
- `403`: Access denied
- `404`: Resource not found
- `409`: `VERSION_CONFLICT`: the artifact has a newer version than `base_version`; `current_version` says which. Nothing was written.
- `413`: `STORAGE_LIMIT_EXCEEDED` or `FILE_TOO_LARGE`.
- `422`: An op could not be applied; nothing was written. `EDIT_NO_MATCH` (`old` not found; `nearest` is the closest line), `EDIT_AMBIGUOUS` (`old` matches several places; `lines` lists them — add context or set `all`), `FILE_NOT_FOUND`, `FILE_EXISTS`, `NOT_TEXT`, `RENAME_CHANGES_TYPE`, `ENTRYPOINT_MISSING`, `UNSUPPORTED_ARTIFACT_TYPE`.
- `429`: Rate limit reached (`RATE_LIMIT_EXCEEDED` on publish / account creation / AI routes, `RATE_LIMITED` on the data plane). Wait for `Retry-After` / `reset`.

## Changes

- **2026-10-26** `7712c85b3fea`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/shareout/apis/shareout-rest-api/changes/v1/artifacts/:id/edits/post.md)

---

[API](https://skmtc.dev/shareout/apis/shareout-rest-api.md) - [All operations](https://skmtc.dev/shareout/apis/shareout-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shareout/apis/shareout-rest-api/revisions/1e3f7fd34f6d?raw)