surface

Load and save projects.

Load and save the headless graph, or save a versioned copy of an attached Studio graph while keeping the original project and unsaved work open.

Written for
People managing persistent projects through Kaitoi MCP tools.

Loading a project, changing the working graph, saving its bundle, and reloading a copy are different actions. Keep project IDs and versions from actual receipts rather than treating a project name as identity.

Read both parts of a save receipt

Saving a copy leaves the open tab on its original project.

Updating project A keeps its identity. Saving a separate copy writes project B, while the open tab and unsaved work stay on A. The returned reloadCopyState is client_unconfirmed. Open B yourself to continue there. Check bundleSaved and the returned project ID before retrying a save.

Work in the headless graph

Use list_projects, then load_project(project_id) to replace the server's headless working graph with the intended project. Inspect and edit that graph, then save_project(name, project_id, expected_version) to update it using the observed saved-project version. For a new named project, use the new-save contract instead of passing an unrelated existing ID.

Scratch single-node execution is not this working graph and cannot be saved through this workflow. Add and connect persistent nodes when you need work that can be extended and reopened.

Save an attached Studio graph

Attach explicitly and read the current session's saveContext, including project ID and bundleVersion, plus the live graphRevision. An update uses the same project ID, its bundle version as expected_version, and current expected_revision. Changing the name on that update renames the same project.

For a separate copy, omit project_id and use expected_version:0 with the current editor revision. This can save live unsaved work into a new bundle. Inspect bundleSaved, versionConfirmed, returned bundle version, and any reloadCopyState separately. A copy returns client_unconfirmed; your open tab stays on the original project. Open the saved copy yourself to edit it.

Open an attached project yourself

Loading a project into an attached Studio tab is not available yet. Open the project in Studio yourself, then attach. Headless load_project works. Do not silently retry an attached refusal against the headless graph.

Check identity and receipt before retrying

Headless: load the intended saved project into the headless working graph and update it with its saved version. Attached update: use the same project ID, bundle version and current live revision. Copy: omit project ID, use new-save version zero, and open the saved copy yourself when needed. Attached loading is unavailable and must not silently fall back.

Recover without overwriting another context

Retain a pending actionId and inspect the original action after uncertainty. If a bundle save succeeded while the tab stayed on its original project, do not assume the entire operation failed and create another copy. Read the receipt and current tab before deciding the next action.

For stale saved versions, reread and reconcile the project. For stale editor revisions or lost attachment, refresh the live context. These failures need different repairs. See Live Studio sessions and Permissions and troubleshooting.

Last reviewed against Kaitoi on 26 October 2026. View this page as Markdown

Type at least two characters.