Create Your First Node

When the node library doesn’t have what you need, you write it. A node is a folder of YAML: you describe the service you want to call, and the platform performs it. There is nothing to compile and no package to install. You write the files, run the node against the real API, then publish it.


What you’ll build	Quote, a node that fetches a famous quote
Where it lives	`nodes/quote/` in your studio workspace
What it outputs	Two connectors: `quote` and `author`
Why this API	It needs no key, so you can build and run it in under a minute

Before you begin

You have a studio workspace, from unoverse studio. Building and running the node needs nothing else. For the last step, where you use it in a workflow, your universe is running and you have the workflow from Create Your First Agent. Here is the node you are about to build, as canvas will draw it:

My custom node

Quote

Ready

The bold line is this node’s name on your canvas, and you can rename it to whatever the step is doing. The line beneath it is the node type, Quote, which never changes. The colour and the type come from the files below. So do the handles: one on the left for the input, one on the right per output. Hover a handle and its connector name appears.

Build it

Four small files, and none of them is code.

What a node cannot do

It adds no code. The platform makes every call itself, the same way for every node.
It reaches only declared hosts. Anything else is refused, and https only.
It carries no keys. Yours stay in canvas, supplied as it runs.
It is sealed. A deployed copy that was changed by hand is refused.

Anatomy of a node covers each of those in full. Read a working one first. Your project ships with sample nodes in nodes/samples, and studio lists them beside your own. Open one to see the same files you are about to write, already filled in.

Create the package

A package holds one or more nodes and declares which hosts they may call. In your studio workspace, create nodes/quote/ with one file in it:

package.yaml

name: quote
displayName: Quote
description: A famous quote, fetched fresh each run
version: 1.0.0
category: search

allowedHosts:
  - zenquotes.io

allowedHosts is the list of hosts this package may reach, and everything else is refused. A node cannot call anywhere you have not named here.

Describe the node

Create quote/nodes/Quote/node.yaml. This one file says what the node is, what it connects to, and how to test it.

nodes/Quote/node.yaml

type: Quote
kind: PromiseNode

name: Quote
category: Search
color: "#7c5cff"
description: Fetches a random famous quote and its author

whenToUse: Pick when a step needs a famous quote. No settings to fill in.

# Who may run it. Compulsory on every node, and `required: false` is the usual answer:
# the node adds no requirement of its own and runs for whoever the trigger admitted.
auth:
  required: false

capabilities:
  cacheable: false

interface:
  inputs:
    - name: signal
      type: object
      description: Data from previous nodes
  outputs:
    - name: quote
      type: string
      description: The quote text
    - name: author
      type: string
      description: Who said it

# This node has no settings of its own, so it declares none. Every node's form still ends
# with the two access controls ("Require sign-in", "Require role"): the platform injects
# them, because they are the WORKFLOW BUILDER's per-box decision, which is a different
# question from the `auth` block above (yours, and true of every copy). You never write
# them, and their names are reserved.

test:
  testData:
    config: {}
    inputs:
      signal: {}
    expect:
      quote: "return output.quote.length > 0"
      author: "return output.author.length > 0"

Each entry in outputs becomes a connector on the node. Downstream nodes read them as signal.quote1.quote and signal.quote1.author, where quote1 is the id canvas gives the node when you drag it in.A bigger node splits interface and test into their own files. This one is small, so they stay here.

whenToUse decides whether the AI workflow builder can find your node at all. The catalogue ranks it against the task being built, so lead with the outcome in plain words and keep it to one or two sentences. Describe what disqualifies your node as a property (“no settings to fill in”), and never name another node. The full guide is Node discoverability; read it before writing this field for a real node.

Describe the call

Create quote/nodes/Quote/api/run.yaml. It lists the calls the node makes, and this node makes one.

nodes/Quote/api/run.yaml

- name: fetch
  method: GET
  url: https://zenquotes.io/api/random
  transport: json

It is a list even with one call, because a node often needs two: fetch a record, then fetch something the first reply pointed at. Naming each one is how a later call reads an earlier reply.transport: json says the reply arrives as one body. A streaming service uses transport: sse instead, and the node emits as tokens arrive.

Describe what comes out

Create quote/nodes/Quote/api/events.yaml. One row per output connector, in the order the node declares them.

nodes/Quote/api/events.yaml

- emit: quote
  from: response
  value: "return response[0].q"

- emit: author
  from: response
  value: "return response[0].a"

This API returns an array with one object in it, so response[0].q is the quote text. Read this file and you know everything the node emits, without opening another one.

Run it against the real API

Open studio and go to the Nodes tab. Your node is listed there. Load its sample, press Run, and the output appears beside the settings.This calls the real API. No platform is running, the keys come from your own .env, and nothing is published. Testing nodes covers it in full.

Check it and deploy it

From anywhere in your workspace:

unoverse lint

Every rule a node must meet is checked, and each message names the one it broke. Then ship it to your universe:

unoverse deploy studio

Deploy runs the same check first, and Quote is in the node library in canvas the moment it finishes.

Use it in a workflow

Open your workflow from Create Your First Agent, drag Quote in, and connect Input Trigger to it.Step through the workflow. Quote’s Debug tab shows a fresh quote from the API.Now feed it to the model: reference signal.quote1.quote in the OpenAI Stream prompt, and your Agent opens its answer with a famous quote.

When a node needs a key

Quote needs no key. Most services do, and the key never goes in these files. A node declares what it needs, by name:

nodes/YourNode/node.yaml

interface:
  credentials:
    - name: yourServiceCredential
      required: true
      displayName: Your Service

Then the request uses it:

nodes/YourNode/api/run.yaml

- name: fetch
  credential:
    scheme: bearer
    token: "{{ credentials.yourServiceCredential.apiKey }}"

You enter the key once in canvas, under Credentials. The platform encrypts it, and supplies it to the node at the moment it runs. The value is never in your files, never in git, and never in the node you hand to someone else. A node carries no keys, so sharing one never shares a secret. Credentials covers the full pattern. Your node runs from the files in your repo, which is all you need while you build. To give it to anyone else, ship it from your terminal with unoverse deploy studio. That writes the node into a universe as a record: no build, no package, nothing to download, and it is live in that universe’s node library as soon as the deploy finishes. The node carries a URL and asks for a key, so the two things anyone installing it will read are its allowedHosts and its credential declaration. Keep both honest.

Have Claude Code build it

Installed by unoverse update

unoverse-create

Claude Code already knows everything on this page. Open your project and describe the node you want:

Create a node that fetches the top story from a news API.

The skill writes the files, adds the host to allowedHosts, and follows the same rules this page just walked through.

How the skills work.

Using a different AI assistant? Point it at docs.unoverse.ai/nodes. Every page there is fetchable as raw markdown by adding .md to the URL.

Start Here

Challenges

Ship It

Create Your First Node

Before you begin

Build it

When a node needs a key

Have Claude Code build it

Next steps

Ingest content to Spatial

Create a component

​Before you begin

​Build it

​When a node needs a key

​Sharing it

​Have Claude Code build it

​Next steps

Ingest content to Spatial

Create a component

Before you begin

Build it

When a node needs a key

Sharing it

Have Claude Code build it

Next steps