Work with projects and graph documents.

Use 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. The illustrated controls change only the example.

The A/B/C graph keeps its connections and other inputs. A narrow patch highlights only A’s strength change from 0.5 to 0.7; whole-document replacement highlights the enclosing document and its wider preservation responsibility.

#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

1. Fetch the current project or graph document and its version.
2. Make the intended change using the supported document or patch contract.
3. Send the observed version as expectedVersion where required.
4. 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.

#Choose inspection, document replacement, or a narrow patch

Inspect: use the graph inspection response to understand state, and fetch the editable document before writing. Patch: use a current expectedVersion and narrow semantic operations for the intended pins or connections. Replace: PUT the complete current document only after reconciling changes. Changing a version number alone does not reconcile stale content. No project is read, saved, deleted, or executed by these examples.

#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 schema for the exact operation fields.

Project metadata changes use PATCH /projects/{id}/metadata with the expected version. Deletion also requires the current version. 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.