Append a new version

PATCH/api/v2/workspaces/{slug}/artifacts/{artifact_id}/update/

Add a new HTML version to an existing artifact. The new version becomes current and current_version increments by one.

This is not a partial update in the usual v2 sense. It does not edit fields on the artifact: you cannot rename it, change its description, or move it between projects through this route. It accepts only new content.

Requires the Applets feature and the workspace admin or owner role. See Artifacts overview.

Note the /update/ segment

The path is PATCH …/artifacts/{artifact_id}/update/, not PATCH …/artifacts/{artifact_id}/. A PATCH to the bare detail route is not a defined operation.

Path parameters

slug:requiredstring

The workspace slug. It appears in your Plane URLs. In https://app.plane.so/my-team/projects/, the slug is my-team.

artifact_id:requiredstring (uuid)

The artifact to append a version to. UUID only.

Body parameters

html:requiredstring

The rendered HTML for the new version. An empty or missing value returns 400.

prompt:optionalstring

The prompt that produced this HTML, stored against the version for provenance. Not returned by any read endpoint.

Every call creates a version

Posting identical HTML still appends a version and increments current_version. Content is not de-duplicated, so a retry after a network timeout can leave the artifact one version ahead of what you expect. Read current_version from the response instead of tracking it locally.

Scopes

workspaces.artifacts:write

Errors

Status	Code	Cause
400	None	html is missing or empty. Returns a bare {"detail": "…"} body. See below.
401	unauthorized	Missing or invalid credentials.
402	payment_required	The Applets feature isn't enabled on your plan.
403	forbidden	You are not a workspace admin or owner, or your token lacks the scope.
404	not_found	No such artifact in this workspace, or the workspace is outside your tenant.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
409	conflict	Declared by the schema; no current condition produces it on this route.
413	payload_too_large	The request body is over the size limit. Large HTML can hit this.
415	unsupported_media_type	The Content-Type isn't one this endpoint accepts.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

The 400 here is not problem+json

The missing-html failure returns a bare detail-only body with no type or code member, unlike the rest of v2:

{ "detail": "`html` is required." }

The 404 is a standard problem document. Code that branches on problem.code needs a fallback for the 400 shape.

Append a new version

curl -X PATCH \
  "https://api.plane.so/api/v2/workspaces/my-team/artifacts/b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53/update/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "html": "<section><h1>Q1 velocity by squad</h1><p>Refreshed.</p></section>"
}'

import requests

response = requests.patch(
    "https://api.plane.so/api/v2/workspaces/my-team/artifacts/b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53/update/",
    headers={"X-Api-Key": "your-api-key"},
    json={"html": "<section><h1>Q1 velocity by squad</h1><p>Refreshed.</p></section>"},
)
print(response.json()["current_version"])

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/artifacts/b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53/update/",
  {
    method: "PATCH",
    headers: {
      "X-Api-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      html: "<section><h1>Q1 velocity by squad</h1><p>Refreshed.</p></section>",
    }),
  },
);
const data = await response.json();

Response200

{
  "id": "b7e42a19-3c5d-4f80-9a26-8d1c0f4e7b53",
  "current_version": 4,
  "data_mode": "snapshot"
}

Response404

{
  "type": "not_found",
  "code": "not_found",
  "detail": "Artifact not found."
}

Publishing and versions are independent

If the artifact is already published, its anchor serves the current version, so you publish once and append as often as you like. You do not need to publish again after an update, and you cannot point an anchor at an older version.

See Publish an artifact.