nodetool-api-reference

name	nodetool-api-reference
description	Use NodeTool REST API, WebSocket protocol, Chat API (OpenAI-compatible), workflow execution endpoints, and streaming responses. Use when user asks about API endpoints, WebSocket protocol, how to call the API, build a client, integrate with NodeTool, or stream workflow results.

You help users integrate with NodeTool's APIs. There are three API surfaces.

API Surfaces

Surface	Start Command	Use Case
Editor API	nodetool serve	Full control, dev, WebSocket
Server API	nodetool serve --mode private	Hardened REST, production
Chat Server	nodetool chat-server	Chat-only, OpenAI-compatible

Authentication

All authenticated endpoints use Bearer token:

Authorization: Bearer <TOKEN>

Token source depends on auth provider:

• static: SERVER_AUTH_TOKEN env var
• supabase: Supabase JWT
• local/none: No auth required

REST Endpoints

Workflows

# List workflows
curl http://localhost:7777/api/workflows/ \
  -H "Authorization: Bearer TOKEN"

# Get workflow
curl http://localhost:7777/api/workflows/<id> \
  -H "Authorization: Bearer TOKEN"

# Run workflow (blocking)
curl -X POST http://localhost:7777/api/workflows/<id>/run \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params": {"prompt": "hello world"}}'

# Run workflow (streaming SSE)
curl -X POST http://localhost:7777/workflows/<id>/run/stream \
  -H "Authorization: Bearer TOKEN" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"params": {"prompt": "hello world"}}'

Models

# List available models (OpenAI-compatible)
curl http://localhost:7777/v1/models \
  -H "Authorization: Bearer TOKEN"

Health

# Health check (no auth required)
curl http://localhost:7777/health

Storage

# Check asset exists
curl -I http://localhost:7777/storage/<path>

# Download asset
curl http://localhost:7777/storage/<path>

Chat API (OpenAI-Compatible)

HTTP

# Chat completion
curl -X POST http://localhost:7777/v1/chat/completions \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "stream": false
  }'

# Streaming chat
curl -X POST http://localhost:7777/v1/chat/completions \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

Python Client (OpenAI SDK)

import openai

client = openai.OpenAI(
    api_key="TOKEN",
    base_url="http://localhost:7777/v1"
)

# Non-streaming
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

JavaScript Client

const response = await fetch("http://localhost:7777/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello!" }],
    stream: false
  })
});
const data = await response.json();
console.log(data.choices[0].message.content);

WebSocket API

Endpoint: ws(s)://<host>/ws

Run a Job

const socket = new WebSocket("ws://localhost:7777/ws");

// Send run_job command
socket.send(JSON.stringify({
  command: "run_job",
  data: {
    type: "run_job_request",
    api_url: "http://localhost:7777/api",
    workflow_id: "<uuid>",
    job_type: "workflow",
    auth_token: "<token>",
    params: { input_name: "value" },
    job_id: "<uuid>",
    user_id: "<user>",
    graph: { nodes: [], edges: [] },
    execution_strategy: "threaded"
  }
}));

// Handle messages
socket.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case "job_update":
      console.log(`Job ${msg.status}`); // running|completed|failed|cancelled|suspended
      if (msg.result) console.log("Result:", msg.result);
      break;
    case "node_update":
      console.log(`Node ${msg.node_name}: ${msg.status}`);
      break;
    case "node_progress":
      console.log(`Progress: ${msg.progress}/${msg.total}`);
      break;
    case "output_update":
      console.log(`Output ${msg.output_name}:`, msg.value);
      break;
    case "chunk":
      process.stdout.write(msg.content);
      break;
    case "log_update":
      console.log(`[${msg.severity}] ${msg.content}`);
      break;
  }
};

Job Control Commands

// Cancel
socket.send(JSON.stringify({ command: "cancel_job", data: { job_id: "...", workflow_id: "..." } }));

// Pause
socket.send(JSON.stringify({ command: "pause_job", data: { job_id: "...", workflow_id: "..." } }));

// Resume
socket.send(JSON.stringify({ command: "resume_job", data: { job_id: "...", workflow_id: "..." } }));

// Reconnect to running job
socket.send(JSON.stringify({ command: "reconnect_job", data: { job_id: "...", workflow_id: "..." } }));

// Stream input to a running node
socket.send(JSON.stringify({
  command: "stream_input",
  data: { input: "name", value: "data", handle: "..." }
}));

// End input stream
socket.send(JSON.stringify({
  command: "end_input_stream",
  data: { input: "name", handle: "..." }
}));

WebSocket Chat

const socket = new WebSocket("ws://localhost:7777/chat?api_key=TOKEN");

socket.onopen = () => {
  socket.send(JSON.stringify({
    role: "user",
    content: "Hello",
    model: "gpt-4o"
  }));
};

socket.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === "chunk") {
    process.stdout.write(data.content);
  }
};

Streaming SSE Response Format

When using stream=true or the /run/stream endpoint, responses come as Server-Sent Events:

data: {"type": "job_update", "status": "running", "job_id": "..."}

data: {"type": "node_progress", "node_name": "Agent", "progress": 1, "total": 5}

data: {"type": "chunk", "content": "Hello", "done": false}

data: {"type": "output_update", "output_name": "text", "value": "...", "output_type": "str"}

data: {"type": "job_update", "status": "completed", "result": {...}}

Server Message Types

Type	Key Fields	Purpose
job_update	status, result, error, duration	Job lifecycle
node_update	node_id, node_name, status, error, result	Node lifecycle
node_progress	progress, total, chunk	Progress tracking
output_update	output_name, value, output_type	Node output values
preview_update	value	Preview node data
log_update	content, severity	Log messages
chunk	content, done	Streaming text

Server Management

nodetool serve                        # Start server (default port 7777)
nodetool serve --port 8080            # Custom port
nodetool serve --host 0.0.0.0         # Bind all interfaces
nodetool workflows list               # List saved workflows
nodetool workflows get <id>           # Get workflow details
nodetool jobs list                    # List execution jobs
nodetool secrets store OPENAI_API_KEY # Store API key