Edit an artifact's content

Change an artifact's content.

PUT/workspaces/{workspace}/artifacts/{artifact_id}/content

For a doc: markdown with a target: append (add to the end), document (replace it all), section (with heading: that heading and everything under it) or blocks (from_block through to_block, block ids from its content). With the edit role the change is made, as a new version; with the comment role, or suggest_only, it is filed as a suggestion its editors accept or reject. note says why; marks_current says it brings the doc up to date with the code it cites. Returns mode (applied or suggested), version_id or the suggestion, and the artifact.

With only the comment role, or with suggest_only, the change is filed as a suggestion instead: mode is suggested, with the suggestion its editors accept or reject. A target that is not there any more answers 404: read the content again.

Authentication: Required. Send an access token as Authorization: Bearer.
MCP tool: artifact with action edit, and the same inputs
Scope: An access token needs artifacts:write.

Path parameters

Name	Type	Required	Description
`workspace`	string	Yes	The workspace’s slug, e.g. “acme”.
`artifact_id`	string	Yes	The artifact’s id (fol_…), or its address: /acme/-/artifacts/q4-roadmap-fol_…

Body parameters

Send a JSON object. Names are snake_case, as in responses; the camelCase spelling is accepted too.

Name	Type	Required	Description
`markdown`	string	No	For a doc: the Markdown to add, or to replace the target with.
`target`	object or string	No	For a doc: append or document (as a string or { “kind”: … }), { “kind”: “section”, “heading”: … }, or { “kind”: “blocks”, “from_block”: …, “to_block”: … }. Left out: append.
`ops`	array of objects	No	For slides, designs and dashboards, once they ship: the kind’s own ops.
`kind`	string	No	The artifact’s kind; left out, doc. One of `doc`, `slides`, `design`, `dashboard`.
`note`	string	No	Why, in a line: shown with the version or suggestion.
`suggest_only`	boolean	No	File a suggestion even when you could edit.
`marks_current`	boolean	No	The edit brings it up to date with the code it cites.

Example request

curl -X PUT https://api.g1t.sh/workspaces/acme/artifacts/fol_01kq7c4e6g8j0m2p4r6t8v0x2z/content \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target": {
      "kind": "section",
      "heading": "This quarter"
    },
    "markdown": "## This quarter\n\nWe ship the merge queue, Artifacts and the API for both.\n",
    "note": "Adds the API"
  }'

Example response

A successful request answers 200 with:

{
  "mode": "applied",
  "artifact": {
    "id": "fol_01kq7c4e6g8j0m2p4r6t8v0x2z",
    "kind": "doc",
    "title": "Q4 roadmap",
    "icon": "🗺️",
    "slug": "q4-roadmap-fol_01kq7c4e6g8j0m2p4r6t8v0x2z",
    "html_url": "https://g1t.sh/acme/-/artifacts/q4-roadmap-fol_01kq7c4e6g8j0m2p4r6t8v0x2z"
  },
  "version_id": "ver_01kqa7h9k1n3q5s7u9w1y3a5c",
  "summary": "Replaced the section This quarter."
}

Errors

A failed request answers with one of these statuses and a body like {"error": {"code": "not_found", "message": "Repository not found."}}. See errors.

Status	Code	When
401	`unauthenticated`	A token is required, or the one sent is not valid.
403	`forbidden`	The token is valid but not allowed to do this, such as a member-only change or an agent token outside its repository.
404	`not_found`	It does not exist, or you cannot see it.
409	`conflict`	The request conflicts with the current state.
422	`invalid`	The input is not valid. `message` says which field and why.