Graphs and nodes.

A graph describes work as nodes joined by connections. Each node performs an operation. Its input pins accept values, its output pins provide values, and a connection supplies one node's output to another node's input.

For example, a graph can take an image, resize it, and pass the resized image to another step. You can follow the wires to see where a value comes from and change one operation without rebuilding the whole workflow.

Term	What it describes
Graph	The operations, their settings, and their connections.
Project	The saved or working document around the graph and other project content.
Run	An attempt to execute the intended work and produce results.

Saving a project and running its graph are separate actions. A graph can exist before it has produced any output. See Projects for saving and Runs for execution.

#One type, separate instances

A node type defines an operation: its implementation, pins, defaults, and controls. An instance is one node placed in your graph. You can place the same type more than once and give each instance its own settings and label.

The simplified contract for Resize Image is image + floating-point scale factor + other options → resized image. In the Initial settings state, Web image has example ID resize_web and factor 0.5; Small preview has ID resize_preview and factor 0.25. In Change Web image, only resize_web becomes 0.75; the other stays at 0.25. Both still use the same node type. The controls switch between these states without editing or running a real graph. The authored kite previews illustrate relative scale; they are not generated outputs.

Connections and run targets use instance IDs, not display labels. Studio assigns IDs to new nodes; inline API graphs use the IDs you supply. Name instances for their purpose. Renaming a label does not change the operation or instance ID.

#What a node can do

Nodes cover more than AI model calls. An operation can generate media, transform an image, pass text through, work with files, call an external service, or provide a specialized tool with its own interface. A workflow can combine deterministic operations with generative steps.

You can also ask Penny to help build or change a graph and create a custom node for an operation you need. Custom code and integrations depend on account capabilities. Inspect the generated inputs and outputs and try a small example before relying on it.

#Where an input gets its value

An unconnected input can use its manual control or a declared default. When you connect an upstream output, that connection supplies the input instead.

The diagram opens in Shared output: Text Prompt supplies “A blue kite” through a green string wire to Create image; red image wires carry the same output to Resize Image and Use as reference. Both branches show that image as an input preview; Resize Image has a scale factor of 0.5. Connected input keeps the upstream prompt, which replaces the image step's manual control, and removes the branches. Manual input uses “A coral kite” in the image step's own control instead. The landscape preview changes to a coral kite. These are authored illustrations and simplified operation labels, not Studio screenshots or provider results. Switching states only changes the explanation; it executes no graph.

#Return to a manual input

In Studio, the manual input widget is hidden while the pin is connected. Disconnecting shows the control again but clears the stored value. The input then falls back to its declared default, or has no value if none is defined. Check or set it before running again. Undo can restore the previous graph state. Not every input has a useful default: check the node's help for required inputs, valid ranges, and operation-specific rules.

#Read the pin contract

Pins have named data types, and their colors help you follow those types on the canvas. Common examples include string, int, float, bool, image, audio, and video. Read the type as well as the label: a pin labelled “Prompt” is not itself a data type.

When dragging wires in Studio, the pin types must match exactly. An image output does not connect to a string input, and int and float are distinct types. Use a suitable conversion operation when a workflow needs a different representation.

A compatible type does not guarantee a successful run. An image may be unavailable, a required input may be missing, a provider may be unconfigured, or an operation may reject the value it receives. Read the failing node's message before retrying.

Some pins have specialized meanings. An object pin carries structured JSON data; file-backed values use a JSON file. A text pin is different from a plain string. A plugin supplies a capability, and a node reference carries node identity for particular control operations. Node and data reference explains these contracts.

#Connections and branches

In Studio, the connection rules for ordinary value-carrying pins are:

• One output can feed several inputs. An image can be resized on one branch and used as a reference on another.
• A normal input takes one connection. Connecting a different source replaces its previous wire.
• An array input can collect several connections. These inputs use a tall rounded pin rather than a circle, and the node can declare a limit.

Studio does not let a node wire to itself. Ordinary data dependencies must also be free of cycles: a chain that eventually needs its own unfinished result cannot be scheduled. Specialized reference and execution-control nodes have their own rules; they are not a workaround for an ordinary data cycle.

#Wires determine the work order

The canvas layout helps you read a graph. Moving a node above or to the left of another does not change the dependency between them. For ordinary data connections, the downstream step needs the upstream value first. Independent ready steps can be scheduled together.

In Studio, Run Graph uses the selected nodes as targets; a node's own run button targets that instance. Required upstream dependencies are considered too. Selecting the end of a chain does not mean every node elsewhere in the project will run. Session and specialized control nodes have separate behavior.

Reusing an output and executing a node again are different outcomes. A changed upstream step runs again to refresh the value your target needs. A clean upstream node can supply its cached output; explicitly targeting an unlocked node asks it to run again even if it was clean. A locked node keeps its cached output instead, and fails if it has no cached output to reuse. Referenced files must still be available. Use Building a graph for the controls and Nodes for node anatomy.

#Find the current operation

Search Studio's node library, then inspect the candidate's help and input and output pins. Check provider or local-service requirements before executing it. The catalog changes, so use the operation's current schema rather than copying an old example's model name or pin names.

API clients can discover account-available types through GET /api/v1/node-types and inspect one through GET /api/v1/node-types/{node_type} with the node_types:read scope. The list supports search and cursor pagination. The API reference ↗ (opens in a new tab) defines the current fields and limits. A node being discoverable does not establish that all credentials or local services needed to run it are ready.

#Graphs through the API

A public run can use a saved project's graph or an inline graph supplied with the request. An inline graph is transient work, not a newly saved Studio project. It must name at least one target instance.

The public inline format contains nodes and connections. Each node needs an id and a type; its title, position, and input values are optional. Connection endpoints name an instance and a pin, using from and to pairs such as ["resize_web", "outputImage"]. Use actual names from the schema.

Public API input objects use transport tags such as string, number, boolean, json, file, and null. Those tags describe the submitted value; they are separate from canvas pin types such as float, bool, and image. A file object uses a Kaitoi file ID. Follow Work with projects and graph documents and Runs and files for request shapes and file handling.

#Validation before a run

Public inline-graph validation checks available node types, named pins, input value objects, and targets. It does not compare connected pin types, apply Studio's one-wire or array-size rules, or detect data cycles. A graph that passes validation can still fail at execution; check the schemas and graph structure before running it.