Nodexa API Docs¶

Welcome to the Nodexa developer documentation. Nodexa is an AI orchestration platform that exposes an OpenAI-compatible Responses API, allowing you to integrate conversational AI assistants into your applications using familiar tooling and patterns.

What is Nodexa?¶

Nodexa lets you build AI-powered conversational experiences backed by a multi-specialist-agent routing engine. Instead of calling a generic LLM directly, you call a Nodexa Assistant — a configured entity that:

Routes requests to the most appropriate Specialist Agent (an LLM-backed agent with a specific role and knowledge)
Invokes tools on your behalf (web search, REST APIs, MCP integrations)
Maintains memory across sessions for each user
Passes user context to specialist agents via structured claims
Streams responses in real time using Server-Sent Events (SSE)

The API is wire-compatible with the OpenAI Responses API, so you can use the official OpenAI SDK (Node.js or Python) without any custom client code.

Key Capabilities¶

Capability	Description
OpenAI-compatible API	Use the OpenAI SDK or any HTTP client out of the box
Streaming	Real-time SSE streaming with granular event types
Multi-specialist agent routing	Requests are automatically routed to the best specialist agent
Client-side function calling	Execute custom functions in your app and feed results back
Web search	Built-in web search for OpenAI, Anthropic Claude, and Google Gemini models
Conversation threading	Continue conversations across requests with `previous_response_id`
User memory	Per-user, per-assistant memory that persists across sessions
User claims	Store and retrieve structured user profile data
OAuth passthrough	Forward per-provider OAuth tokens for tools that require user auth

Quickstart

Get your first API call working in under 5 minutes.

Authentication

Learn how API keys work and which scopes to use.

Responses API

Full reference for the core chat endpoint.

Streaming

Connect to the SSE stream and handle all event types.

Function Calling

Execute client-side tools and return results.

User Claims

Store and retrieve structured user profile data.

Memory

Per-user memory management, opt-out, and GDPR erasure.

OpenAI SDK Guide

Use the official OpenAI SDK with Nodexa — Node.js and Python.

Base URL¶

All API requests are sent to your Nodexa admin instance:

https://your-admin.example.com/v1

Replace your-admin.example.com with the hostname of your Nodexa deployment.

Authentication at a Glance¶

Nodexa uses API keys with the nxk_ prefix. Include your key in every request:

curl https://your-admin.example.com/v1/responses \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_ASSISTANT_ID",
    "input": "Hello, how can you help me?"
  }'

See Authentication for details on header options and API Keys for scope information.

Minimal Working Example¶

Node.js (OpenAI SDK)Python (OpenAI SDK)curl

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://your-admin.example.com/v1',
  apiKey: 'YOUR_API_KEY',
});

const response = await client.responses.create({
  model: 'YOUR_ASSISTANT_ID',
  input: 'What can you help me with today?',
});

console.log(response.output_text);

from openai import OpenAI

client = OpenAI(
    base_url="https://your-admin.example.com/v1",
    api_key="YOUR_API_KEY",
)

response = client.responses.create(
    model="YOUR_ASSISTANT_ID",
    input="What can you help me with today?",
)

print(response.output_text)

curl https://your-admin.example.com/v1/responses \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_ASSISTANT_ID",
    "input": "What can you help me with today?"
  }'

Getting Help¶

Browse the full Reference section for SSE events, error codes, and limits.
Check out Examples for complete, copy-paste-ready code for common scenarios.