# Node and data reference

> Find an operation’s current schema, read pin names and data types, check its controls and requirements, and use the right value representation.

Source: https://kaitoi.io/docs/reference/nodes-and-types/
Section: Kaitoi Core / Custom nodes and plugins
Written for: Workflow builders and developers inspecting a node's contract.
Last reviewed: 2026-10-24

---

The node library and API discovery describe the operations available to your
account. Use their current schemas for the node type and settings you intend to
run.

## Distinguish a value from its file reference


Follow three boundaries separately: the node schema declares an image pin, a REST run can supply a file transport value with a completed fileId, and a custom-node runtime receives its supported media wrapper. The object pin represents a JSON file; json is a REST transport tag. Array input support does not imply array output support. A string scalar differs from the canonical text file wrapper. Paths, file IDs and temporary URLs are not interchangeable.

The same authored image accompanies its schema, completed file ID f1 and runtime wrapper. A managed details.json file illustrates an object-pin value separately from the outer output-name return map.

*Figure: Follow the receiving input's schema instead of relying on the preview.*

## Find an operation

Search the Studio node library and open the operation's help and details. For
programmatic discovery, use the node-type list and detail endpoints in the
[API reference](https://api.studio.kaitoi.io/api/v1/docs), or your MCP client's
node discovery tools.

Availability depends on provider configuration, keys, local services, and
capabilities. An old example naming a model does not establish access today.

## Read the schema

| Field        | Meaning                                                     |
| ------------ | ----------------------------------------------------------- |
| Node type    | Operation identifier used when placing a node               |
| Title        | Display name, separate from an instance's editable title    |
| Pins         | Exact input/output names, types, requiredness, and defaults |
| Widgets      | Parameter controls, ranges, and supported options           |
| Requirements | Providers, plugins, services, and packages                  |
| Help         | Purpose and operation-specific constraints                  |

An instance ID identifies a placed node; connections and run targets use that
ID. They do not identify a particular instance by its display title alone.

## Read the value type

Common scalar pin types include `string`, `int`, `float`, and `bool`. An
`object` pin carries a JSON file; use `string` when a node should receive JSON
as ordinary text. `json` is not a canonical node pin type. A `text` pin delivers
a TextData wrapper rather than a plain Python string; use its supported text
accessor in custom code. Media pins include `image`, `video`, and `audio`;
other file and model types have their own contracts. A `plugin` supplies a
capability, while a `node` reference supports particular execution-control
operations.

Arrays, optionality, and mandatory inputs are declared by the schema. Use
compatible pins or an explicit conversion. A local path, a temporary download
URL, and a Kaitoi file ID are different representations; follow the contract
for the widget, API, or custom-node runtime you are using.

## Keep input arrays and transport values distinct

**Pin:** the node schema declares exact interface names, types and optionality.
**Transport:** REST runs use their six value tags and fileId for a file.
**Runtime:** custom code receives supported values/wrappers and must return
the expected managed output representation. Array inputs do not establish
array-output support. Type, instance, path, URL and file ID are separate.

## Checks and next steps

Ordinary node schemas support array inputs such as `image[]`, with the
required/optional marker following the brackets where used. Do not assume
array output declarations such as `image[]` or `object[]` are supported;
use the current supported manifest or separate-output pattern for the job.

REST run inputs and overrides use transport tags `string`, `number`,
`boolean`, `json`, `file`, or `null`. A file transport value uses `fileId`.
Those tags are not interchangeable with node pin types such as `image`,
`int`, or `object`. Editable project document inputs have their own schema;
do not copy an inspection response or inline-run body into them blindly.

In custom code, media and file values can be supported wrappers, not plain
OS paths or raw Python values. Use their documented accessors and helpers.
For an output, inspect the actual managed file and required format instead
of returning a placeholder name. See [Files and outputs](/docs/core/files-and-outputs/)
for the API's stable identifiers and temporary URLs.