Chat API

NodeTool provides both OpenAI-compatible HTTP endpoints and a WebSocket endpoint for chat interactions:

The single server (nodetool serve, defaults to port 7777) exposes OpenAI-compatible HTTP endpoints (/v1/chat/completions, /v1/models) for remote clients.
The same server exposes a WebSocket endpoint at /ws that carries both chat and workflow messages.

See the canonical matrix in API Reference for methods, auth requirements, and streaming behavior.

Port Reference: Both development and production deployments use port 7777 by default. Replace localhost with your server hostname for remote connections.

OpenAI-Compatible HTTP API

NodeTool exposes OpenAI-compatible endpoints that allow you to use standard OpenAI client libraries and tools. When AUTH_PROVIDER is static or supabase, send Authorization: Bearer <token>; in local/none modes the token is optional for development.

Chat Completions: `POST /v1/chat/completions`

URL: http://localhost:7777/v1/chat/completions

Headers:

Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

Request Body:

{
  "model": "gpt-4",
  "messages": [
    {"role": "user", "content": "Hello, how are you?"}
  ],
  "stream": true
}

Example using OpenAI Python client:

import openai

# For local development: base_url="http://localhost:7777/v1"
# For production/server: base_url="http://localhost:7777/v1" or your server URL
client = openai.OpenAI(
    api_key="YOUR_TOKEN",
    base_url="http://localhost:7777/v1"
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "Hello, how are you?"}
    ],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

Models: `GET /v1/models`

URL: http://localhost:7777/v1/models

List all available models for the configured provider.

# For local development and production: http://localhost:7777/v1/models
curl http://localhost:7777/v1/models \
  -H "Authorization: Bearer YOUR_TOKEN"

WebSocket API

NodeTool also exposes a /ws WebSocket endpoint for real time conversations. The server side is implemented by UnifiedWebSocketRunner which handles message parsing, tool execution and streaming responses.

The connection supports both binary (MessagePack) and text (JSON) messages. Authentication can be provided via Authorization: Bearer <token> headers or an api_key query parameter.

Note: The WebSocket endpoint is served on port 7777 (development) or your configured server port.

WebSocket Example usage

// For local development: ws://localhost:7777/ws
// For production deployments, use your server URL
const socket = new WebSocket("ws://localhost:7777/ws?api_key=YOUR_KEY");

// Send a chat message
const message = {
  role: "user",
  content: "Hello world",
  model: "gpt-3.5-turbo" // or any supported model
};

socket.onmessage = async (event) => {
  const data = msgpack.decode(new Uint8Array(await event.data.arrayBuffer()));
  if (data.type === "chunk") {
    console.log(data.content);
  }
};

socket.onopen = () => {
  socket.send(msgpack.encode(message));
};

Server responses

Responses from the server may include:

chunk – streamed text from the model
tool_call – a request to execute a tool
tool_result – the result of a tool execution
job_update – status updates when running a workflow
error – error messages

The runner also supports workflow execution by sending a message with a workflow_id. In that case the WebSocket will stream job updates in addition to regular chat responses.

Edit this page on GitHub