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.
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.