Skip to content
Docs menu

Edit by id

Change one slide or block without resending the artifact, in batches that apply all or none, with a version for every write and a check that stops two writers overwriting each other.

View .md

Every slide and block has an id, so an edit names what it changes. studio_outline_get lists the ids and titles of an artifact (and the ids of the blocks inside each slide) in a few lines, far cheaper than reading it whole.

Operations

studio_content_edit takes ops, a list of up to 100 operations applied in order. All apply or none do, and the batch is one version.

Op Fields
slide.add slide, after or before (a slide id, start or end; the end by default)
slide.replace id, slide
slide.patch id, layout, notes (null clears), content (slots to set; null removes one)
slide.move id, after or before
slide.delete id
slide.duplicate id, new_id, after (every id inside the copy is new)
block.add block, in (<slide id>.<slot> or <columns id>.left; omit on a page), after or before
block.replace id, block
block.patch id, set (fields to change; null removes an optional one)
block.edit id, field, edits (anchored string edits on a text field)
block.move id, in, after or before
block.delete id
{
  "id": "0190...",
  "ops": [
    { "op": "block.patch", "id": "rev", "set": { "title": "Revenue, $M" } },
    { "op": "block.edit", "id": "lt", "field": "md", "edits": [{ "op": "replace", "old_string": "beta", "new_string": "GA" }] },
    { "op": "slide.add", "slide": { "layout": "closing", "content": { "title": "Thanks" } }, "after": "plan" }
  ]
}

A block's new or changed spec is checked the same way as on create, and an error names the op (ops[1].id: "nope" is not a block). dry_run: true checks a batch and changes nothing. The answer lists the ids the batch touched and removed.

String edits (replace, insert_before, insert_after, prepend, append, replace_range) are the same ones notes and issues use: each anchor must match exactly once. HTML pages are edited the same way with studio_html_edit.

Versions

Every write makes a version with who made it and an optional note. The newest 100 are kept. studio_version_list shows them and studio_version_restore makes an earlier one current again. A restore is written as a new version, so it can be undone too.

Two writers

Anchored ops apply to the latest content, so two people changing different slides do not collide. To be safe when a change depends on what you read, pass expect_version, the version you last read. If someone else wrote since, the write fails with the current version and changes nothing:

The artifact changed since you read it (now version 7, you sent expect_version 5). Read it again (studio_outline_get), re-apply
your change and pass expect_version 7.

Over REST, send the version as If-Match: "5" and a stale write is a 412.

On the canvas

The console's editor uses these same ops (The Studio pages). Its preview is drawn in an edit mode where each text carries the id of its slide or block and the path of the field it comes from (text, items.2, rows.1.0, left.points.0); the view, a public link, present, print and the thumbnails are drawn without those attributes. A text edited in place is saved as the smallest op that changes it, with the version the editor last saw as expect_version:

You edit The op
a slide's text (title, subtitle, a bullet, a panel's heading or point, a big number) slide.patch with content set to that slot
a block's text (a heading, a paragraph's markdown, a list item, a table cell, a stat, a title or caption) block.patch with set for that field
the page title studio_artifact_update with title

A number stays a number when you type digits where one was. Emptying an optional text removes it (null), emptying a bullet or a point removes it from its list, and a required text cannot be emptied: the editor says which rule it broke and saves nothing. If someone else wrote first, the conflict message above is shown and nothing changes.

Ask the agent

A comment on an element is a message to an agent quick chat, sent through the same chat API the Agents app uses. It names the artifact (id, kind, title and version), the element (a slide or block id and the field, or for an HTML page the element's CSS path and the start of its HTML) with a short excerpt, and your words, and asks the agent to change only that element with studio_content_edit (or studio_html_edit) and expect_version. The chat the artifact was made in (its "created from" link), or the one an earlier comment started, is reused when it is your own quick chat with the Studio server; otherwise a new quick chat starts with the Studio server, linked to the artifact. Tools that delete or send still wait for your confirmation in the chat, as they do in any quick chat: the box says so and links to it.

An HTML page is picked inside its sandbox: in the editor its frame is served with ?pick=1, which adds a small script to the page. The frame keeps its own Content-Security-Policy, no network and no same-origin access; the script reports the clicked element to the editor with postMessage, and the editor accepts only messages from that frame. A public link never carries the script.