Work with projects and graph documents.
Discover node schemas, edit a versioned graph document through the public API, and reconcile changes without overwriting another client’s work.
Interactive API reference Explore endpoints, request schemas and responses. Opens in a new tabUse the public /api/v1 project and graph-document endpoints for stable
integration contracts. Studio's internal persistence requests and public API
documents have different purposes; construct the shape described by the public
schema.
Compare a focused edit with a whole graph
A focused patch changes the selected fields; replacing a graph supplies the complete intended graph. Capture the current project version, inspect the relevant nodes and preserve unrelated content. Version conflicts require rereading and comparing. An unresolved mutation or unavailable state must not become permission to resubmit automatically.
Discover before building
Search node types and read the detail for each type you will place. Use the actual input/output names, types, defaults, and requirements. A display label such as “Reference image” is not automatically the pin identifier your graph must use.
Assign stable instance IDs to placed nodes and use those IDs in connections and run targets. A node type identifies an operation; a node instance identifies that particular operation in your graph.
Read, change, write
- Fetch the current project or graph document and its version.
- Make the intended change using the supported document or patch contract.
- Send the observed version as
expectedVersionwhere required. - Keep the version returned by a successful write for your next change.
If another client has already updated the document, read the new version and reconcile your change. Blindly substituting the latest version number into an old full document can still overwrite work you did not examine.
The version returned by a read is a conservative optimistic save base captured
before the content read. It is not a certificate of exact bytes during a
concurrent write. Guarded responses such as PROJECT_MUTATION_UNRESOLVED or
PROJECT_SAVE_UNAVAILABLE are not ordinary version conflicts. Preserve local
work and follow the code-specific recovery path
instead of automatically retrying.
Keep graph state and executions separate
Saving graph changes does not execute them. A run snapshots a saved project or accepts an inline graph. Non-persistent run input overrides change that execution without rewriting the saved graph.
Use a saved project when users should reopen and edit the workflow. Use a supported inline graph when the application needs a transient execution and will manage its own source definition.
Use current schemas
The interactive API reference (opens in a new tab) is the field-level contract. Its generated schema also covers timeline and storyboard documents. Use the corresponding document endpoints and validation rules for those artifacts instead of treating rendered media as their editable source.
Checks and next steps
GET /projects/{id}/graph is an inspection view, not the editable document.
Use GET /projects/{id}/document for the public editable shape; it requires
both projects:read and graphs:read. Nodes there use input maps and
connections such as {"from":["a","image"],"to":["b","inputImage"]}.
Replace through PUT /projects/{id}/document with expectedVersion and
document, or use PATCH /projects/{id}/document with expectedVersion and
1–100 semantic operations. Both writes require projects:write and
graphs:write. For a one-pin change, use setNodeInput/unsetNodeInput;
updateNode.inputs replaces the whole public input map. Read the current
fields below. Positions are {x,y}, connections use from/to pairs, and
input values are typed public values such as {"type":"number","value":3}.
| Operation | Fields besides op |
Example |
|---|---|---|
addNode |
node |
{"op":"addNode","node":{"id":"a","type":"builtin/utils/text","inputs":{}}} |
replaceNode |
Complete node with existing ID |
{"op":"replaceNode","node":{"id":"a","type":"builtin/utils/text","inputs":{}}} |
updateNode |
nodeId; title, position and/or whole inputs map |
{"op":"updateNode","nodeId":"a","title":"Caption"} |
deleteNode |
nodeId; incident connections are removed |
{"op":"deleteNode","nodeId":"a"} |
setNodeInput |
nodeId, input, value |
{"op":"setNodeInput","nodeId":"a","input":"inputText","value":{"type":"string","value":"Hello"}} |
unsetNodeInput |
nodeId, input |
{"op":"unsetNodeInput","nodeId":"a","input":"inputText"} |
moveNode |
nodeId, position |
{"op":"moveNode","nodeId":"a","position":{"x":100,"y":80}} |
connect (alias addConnection) |
from, to |
{"op":"connect","from":["a","outputText"],"to":["b","prompt"]} |
disconnect (alias deleteConnection) |
from, to |
{"op":"disconnect","from":["a","text"],"to":["b","prompt"]} |
replaceConnections |
Complete connections list |
{"op":"replaceConnections","connections":[]} |
renameProject |
name |
{"op":"renameProject","name":"Caption workflow"} |
setProjectMetadata |
metadata |
{"op":"setProjectMetadata","metadata":{"externalId":"job-42"}} |
Project metadata changes use PATCH /projects/{id}/metadata with the expected
version. Delete with DELETE /projects/{id}?expectedVersion=7, replacing 7
with the observed version. This deletes the same project from Studio too.
A failed or stale write
is a reason to inspect and reconcile state, not to copy a newer number into
an old replacement document. Run submission is separate and does not supply
the same expected-version guard for a saved-project run.
Create, list and read a project
All paths are relative to /api/v1. Metadata and graph documents are separate.
| Request | Scope and behavior |
|---|---|
POST /projects with {"name":"Caption workflow"} |
projects:write; send an Idempotency-Key; returns 201 with project identity/version |
GET /projects |
projects:read; filters include search, externalId, externalUserId and externalWorkspaceId; follow opaque cursors |
GET /projects/{id} |
projects:read; inspect metadata and current version |
PATCH /projects/{id}/metadata |
projects:write; provide expectedVersion and intended metadata changes |
DELETE /projects/{id}?expectedVersion=7 |
projects:write; version-guarded deletion also removes the project from Studio |
Editable graph documents are limited to 1 MiB, 500 nodes and 2,500 connections. An inline run graph is limited to 256 KiB, 100 nodes and 500 connections. Inspect validation issues before sending a larger replacement.
Last reviewed against Kaitoi on 26 October 2026. View this page as Markdown