surface

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.

Written for
Developers building or editing workflows through the public API.
You need
Any plan for REST project and graph access
Interactive API reference Explore endpoints, request schemas and responses. Opens in a new tab

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

Review the part of the saved project that a write will replace.

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

  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.

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

Type at least two characters.