2. First Node

This is part 2 of the Your First Plugin tutorial. Make sure you’ve completed 1. Plugin Definition first.

Nodes are where your plugin’s logic lives. Let’s build a node that takes a city name and returns a formatted weather description.

V2 vs V1 nodes

There are two kinds of node, and you should almost always write V2:

V2 (recommended, connector-free). A V2 node mirrors the platform’s native nodes: it has no edge connectors. Instead it is two schemas — a config schema whose fields are the node’s settings (a field marked bindable=True becomes an input that accepts a literal or a :var[...] reference to an upstream output), and an output schema that declares every output. Everything arrives on self.config; call(ctx) returns a dict keyed by the output field names.
V1 (legacy — edge connectors). Inputs and outputs are Connector objects wired by edges, and inputs arrive as keyword arguments to call. Only use V1 when you specifically need a node for a V1 flow.

Both kinds can live in the same plugin — nodes() returns them together and the SDK splits them into the correct editor automatically.

Define the node

V2 (recommended)
V1 (legacy)

Add a new node to weather_plugin/:

from noxus_sdk.nodes.base import BaseNodeV2, NodeConfiguration, NodeOutputs
from noxus_sdk.nodes.types import NodeCategory
from noxus_sdk.ncl import Parameter, ConfigText, ConfigSelect
from noxus_sdk.plugins.context import RemoteExecutionContext


class GetWeatherConfig(NodeConfiguration):
    # `bindable=True` makes this a node input: it accepts a literal typed in the
    # editor, or a `:var[...]` reference to an upstream node's output.
    city: str = Parameter(
        default="",
        bindable=True,
        display=ConfigText(label="City", placeholder="e.g. London"),
    )
    # A plain (non-bindable) config field — a setting the user picks in the editor.
    units: str = Parameter(
        default="celsius",
        display=ConfigSelect(label="Units", values=["celsius", "fahrenheit"]),
    )


class GetWeatherOutputs(NodeOutputs):
    temperature: str
    description: str


class GetWeatherNode(BaseNodeV2[GetWeatherConfig, GetWeatherOutputs]):
    node_name = "GetWeatherNode"
    title = "Get Weather"
    description = "Returns weather data for a given city"
    category = NodeCategory.DATA
    color = "#4A90E2"

    async def call(self, ctx: RemoteExecutionContext) -> dict:
        # Every value — bindable inputs included — is read from self.config.
        temperature = "22°C" if self.config.units == "celsius" else "72°F"
        return {
            "temperature": temperature,
            "description": f"Sunny skies in {self.config.city}",
        }

A list[X]-typed output field (e.g. tags: list[str]) becomes a list output. Required-but-unbound inputs fail with a clear error before call runs, so you don’t need to defensively check them.

Only reach for V1 when you need a node for a V1 flow. Inputs and outputs are Connector objects, and call receives inputs as keyword arguments:

from noxus_sdk.nodes.base import BaseNode, NodeConfiguration
from noxus_sdk.nodes.connector import Connector
from noxus_sdk.nodes.types import DataType, NodeCategory, TypeDefinition
from noxus_sdk.plugins.context import RemoteExecutionContext


class GetWeatherConfig(NodeConfiguration):
    """This node has no configuration fields."""
    pass


class GetWeatherNode(BaseNode[GetWeatherConfig]):
    node_name = "GetWeatherNode"
    title = "Get Weather"
    description = "Returns weather data for a given city"
    category = NodeCategory.DATA
    color = "#4A90E2"

    inputs = [
        Connector(
            name="city",
            label="City",
            definition=TypeDefinition(data_type=DataType.str),
        ),
    ]
    outputs = [
        Connector(
            name="temperature",
            label="Temperature",
            definition=TypeDefinition(data_type=DataType.str),
        ),
        Connector(
            name="description",
            label="Description",
            definition=TypeDefinition(data_type=DataType.str),
        ),
    ]

    async def call(self, ctx: RemoteExecutionContext, city: str) -> dict:
        return {
            "temperature": "22°C",
            "description": f"Sunny skies in {city}",
        }

Register the node in your plugin

Add the node class to your plugin’s nodes() method:

class WeatherPlugin(BasePlugin[WeatherPluginConfig]):
    # ... same metadata as before ...

    def nodes(self):
        return [GetWeatherNode]

Test it locally

Restart the plugin server:

noxus plugin serve --path ./weather-plugin

Then execute the node. The /nodes/{node_name}/execute endpoint takes a body with ctx, inputs, and config:

V2 (recommended)
V1 (legacy)

For a V2 node, bindable and plain config values both go in config; inputs stays empty:

curl -X POST http://localhost:8505/nodes/GetWeatherNode/execute \
  -H "Content-Type: application/json" \
  -d '{
    "ctx": {},
    "inputs": {},
    "config": {"city": "London", "units": "celsius"}
  }'

For a V1 node, connector inputs go in inputs as plain values keyed by name:

curl -X POST http://localhost:8505/nodes/GetWeatherNode/execute \
  -H "Content-Type: application/json" \
  -d '{
    "ctx": {},
    "inputs": {"city": "London"},
    "config": {}
  }'

Either way you get back an ExecutionResponse:

{
  "success": true,
  "outputs": {
    "temperature": "22°C",
    "description": "Sunny skies in London"
  }
}

Key concepts

Concept	Description
`node_name`	Unique identifier — must be unique across all plugins
Config schema (V2)	A `NodeConfiguration`; `bindable=True` fields are inputs, the rest are settings
Output schema (V2)	A `NodeOutputs` subclass; each field is an output, `list[X]` is a list output
`inputs` / `outputs` (V1)	`Connector` objects that define what flows in and out over edges
`call()`	The async method that runs when the node executes. V2 reads `self.config` and returns a dict keyed by output names; V1 receives inputs as kwargs
`ctx`	The `RemoteExecutionContext` — group id, integration credentials, and file helpers

Available data types

V2 output fields and V1 connectors both use these types (V2 infers them from the Python annotation; V1 declares them via TypeDefinition):

Python annotation (V2)	`DataType` (V1)	Meaning
`str`	`DataType.str`	Text
`int` / `float`	`DataType.number`	Number
`bool`	`DataType.bool`	Boolean
`dict`	`DataType.dict`	JSON / dict
`datetime`	`DataType.datetime`	Timestamp
`File`	`DataType.File`	Any file
`list[str]`	`TypeDefinition(data_type=DataType.str, is_list=True)`	List of strings
`list[File]`	`TypeDefinition(data_type=DataType.File, is_list=True)`	List of files

Image, Audio, and Chat are also available as file-like types.

Node metadata

Field	Required	Description
`node_name`	Yes	Unique identifier for the node
`title`	Yes	Display name in the UI
`description`	Yes	Shown in the node palette and tooltips
`category`	No	Groups the node in the palette (`DATA`, `AI_TEXT`, `INTEGRATIONS`, `LOGIC`, `OTHER`, …); default `OTHER`
`color`	No	Hex color for the node in the editor
`image`	No	Icon URL (PNG/SVG)
`small_description`	No	Short one-line summary
`sub_category`	No	Finer grouping within a category
`integrations`	No	Dict mapping integration types to required credential fields
`max_timeout`	No	Maximum execution time in seconds (default `240`)

Next: First Integration →

Define credentials and an integration for an external API.

Overview

Tutorial

Reference

GitOps

V2 vs V1 nodes

Define the node

Register the node in your plugin

Test it locally

Key concepts

Available data types

Node metadata

Next: First Integration →

​V2 vs V1 nodes

​Define the node

​Register the node in your plugin

​Test it locally

​Key concepts

​Available data types

​Node metadata

Next: First Integration →

V2 vs V1 nodes

Define the node

Register the node in your plugin

Test it locally

Key concepts

Available data types

Node metadata