Examples

Complete, copy-paste-ready examples for common Nodexa integration scenarios.

---

Environment Setup

All examples assume these environment variables are set:

export NODEXA_API_KEY="nxk_your_key_here"
export NODEXA_BASE_URL="https://your-admin.example.com"
export NODEXA_ASSISTANT_ID="asst_01234567-89ab-cdef-0123-456789abcdef"

---

Example 1 — Simple Question and Answer

The simplest possible integration: send a question, get a text response.

Node.jsPythoncurl

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: process.env.NODEXA_BASE_URL + '/v1',
  apiKey: process.env.NODEXA_API_KEY,
});

const response = await client.responses.create({
  model: process.env.NODEXA_ASSISTANT_ID,
  input: 'What are the main differences between REST and GraphQL?',
});

console.log(response.output_text);

from openai import OpenAI
import os

client = OpenAI(
    base_url=os.environ["NODEXA_BASE_URL"] + "/v1",
    api_key=os.environ["NODEXA_API_KEY"],
)

response = client.responses.create(
    model=os.environ["NODEXA_ASSISTANT_ID"],
    input="What are the main differences between REST and GraphQL?",
)

print(response.output_text)

curl "$NODEXA_BASE_URL/v1/responses" \
  -H "x-api-key: $NODEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$NODEXA_ASSISTANT_ID\",
    \"input\": \"What are the main differences between REST and GraphQL?\"
  }"

---

Example 2 — Streaming Response with Progress Display

Stream tokens as they arrive and display them in real time.

Node.jsPython

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: process.env.NODEXA_BASE_URL + '/v1',
  apiKey: process.env.NODEXA_API_KEY,
});

console.log('Assistant: ');

const stream = await client.responses.create({
  model: process.env.NODEXA_ASSISTANT_ID,
  input: 'Explain the CAP theorem in simple terms.',
  stream: true,
});

let responseId;

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
  if (event.type === 'response.completed') {
    responseId = event.response.id;
  }
}

console.log('\n');
console.log('Response ID:', responseId);

from openai import OpenAI
import os

client = OpenAI(
    base_url=os.environ["NODEXA_BASE_URL"] + "/v1",
    api_key=os.environ["NODEXA_API_KEY"],
)

print("Assistant: ", end="")

response_id = None
with client.responses.stream(
    model=os.environ["NODEXA_ASSISTANT_ID"],
    input="Explain the CAP theorem in simple terms.",
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
        elif event.type == "response.completed":
            response_id = event.response.id

print(f"\n\nResponse ID: {response_id}")

---

Example 3 — Multi-Turn Chat with Memory

A chat loop that maintains conversation history and uses per-user memory.

Node.jsPython

import OpenAI from 'openai';
import * as readline from 'readline';

const client = new OpenAI({
  baseURL: process.env.NODEXA_BASE_URL + '/v1',
  apiKey: process.env.NODEXA_API_KEY,
});

const USER_ID = 'user_demo_001'; // Your user's identifier

async function main() {
  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
  const prompt = (q) => new Promise((res) => rl.question(q, res));

  let lastResponseId = null;
  console.log('Start chatting! Type "quit" to exit.\n');

  while (true) {
    const input = await prompt('You: ');
    if (input.toLowerCase() === 'quit') {
      rl.close();
      break;
    }

    const response = await client.responses.create(
      {
        model: process.env.NODEXA_ASSISTANT_ID,
        input,
        ...(lastResponseId && { previous_response_id: lastResponseId }),
      },
      {
        headers: { 'x-user-id': USER_ID },
      }
    );

    lastResponseId = response.id;
    console.log(`\nAssistant: ${response.output_text}\n`);
  }
}

main();

from openai import OpenAI
import os

client = OpenAI(
    base_url=os.environ["NODEXA_BASE_URL"] + "/v1",
    api_key=os.environ["NODEXA_API_KEY"],
)

USER_ID = "user_demo_001"
last_response_id = None

print("Start chatting! Type 'quit' to exit.\n")

while True:
    user_input = input("You: ")
    if user_input.lower() == "quit":
        break

    kwargs = {
        "model": os.environ["NODEXA_ASSISTANT_ID"],
        "input": user_input,
    }
    if last_response_id:
        kwargs["previous_response_id"] = last_response_id

    response = client.responses.create(
        **kwargs,
        extra_headers={"x-user-id": USER_ID},
    )

    last_response_id = response.id
    print(f"\nAssistant: {response.output_text}\n")

---

Example 4 — Function Calling with Database Lookup

Define a function tool that queries your database and returns results to the assistant.

Node.jsPython

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: process.env.NODEXA_BASE_URL + '/v1',
  apiKey: process.env.NODEXA_API_KEY,
});

// Simulated database
const orders = {
  'ORD-001': { status: 'delivered', items: 3, total: 149.97 },
  'ORD-002': { status: 'in_transit', items: 1, total: 29.99 },
  'ORD-003': { status: 'processing', items: 5, total: 234.50 },
};

async function getOrderStatus(orderId) {
  const order = orders[orderId];
  if (!order) return { error: `Order ${orderId} not found` };
  return { orderId, ...order };
}

const tools = [
  {
    type: 'function',
    name: 'get_order_status',
    description: 'Get the current status of a customer order',
    parameters: {
      type: 'object',
      properties: {
        orderId: {
          type: 'string',
          description: 'The order ID, e.g. ORD-001',
        },
      },
      required: ['orderId'],
    },
  },
];

async function handleUserQuery(userMessage) {
  let response = await client.responses.create({
    model: process.env.NODEXA_ASSISTANT_ID,
    input: userMessage,
    tools,
  });

  while (response.status === 'requires_action') {
    const results = [];

    for (const item of response.output) {
      if (item.type !== 'function_call') continue;

      const args = JSON.parse(item.arguments);
      console.log(`  [tool] ${item.name}(${JSON.stringify(args)})`);

      let result;
      if (item.name === 'get_order_status') {
        result = await getOrderStatus(args.orderId);
      } else {
        result = { error: `Unknown function: ${item.name}` };
      }

      results.push({
        type: 'function_call_output',
        call_id: item.call_id,
        output: JSON.stringify(result),
      });
    }

    response = await client.responses.create({
      model: process.env.NODEXA_ASSISTANT_ID,
      previous_response_id: response.id,
      input: results,
    });
  }

  return response.output_text;
}

console.log(await handleUserQuery('What is the status of order ORD-002?'));
console.log(await handleUserQuery('Has order ORD-004 been shipped?'));

import json
from openai import OpenAI
import os

client = OpenAI(
    base_url=os.environ["NODEXA_BASE_URL"] + "/v1",
    api_key=os.environ["NODEXA_API_KEY"],
)

ORDERS = {
    "ORD-001": {"status": "delivered", "items": 3, "total": 149.97},
    "ORD-002": {"status": "in_transit", "items": 1, "total": 29.99},
}

def get_order_status(order_id: str) -> dict:
    order = ORDERS.get(order_id)
    if not order:
        return {"error": f"Order {order_id} not found"}
    return {"orderId": order_id, **order}

tools = [
    {
        "type": "function",
        "name": "get_order_status",
        "description": "Get the current status of a customer order",
        "parameters": {
            "type": "object",
            "properties": {
                "orderId": {"type": "string", "description": "The order ID"},
            },
            "required": ["orderId"],
        },
    }
]

def handle_query(user_message: str) -> str:
    response = client.responses.create(
        model=os.environ["NODEXA_ASSISTANT_ID"],
        input=user_message,
        tools=tools,
    )

    while response.status == "requires_action":
        results = []
        for item in response.output:
            if item.type != "function_call":
                continue
            args = json.loads(item.arguments)
            if item.name == "get_order_status":
                result = get_order_status(args["orderId"])
            else:
                result = {"error": f"Unknown: {item.name}"}
            results.append({
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(result),
            })
        response = client.responses.create(
            model=os.environ["NODEXA_ASSISTANT_ID"],
            previous_response_id=response.id,
            input=results,
        )

    return response.output_text

print(handle_query("What is the status of order ORD-002?"))

---

Example 5 — Web Search with Real-time Information

Use the built-in web search tool to answer questions requiring current data.

Node.jsPython

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: process.env.NODEXA_BASE_URL + '/v1',
  apiKey: process.env.NODEXA_API_KEY,
});

const stream = await client.responses.create({
  model: process.env.NODEXA_ASSISTANT_ID,
  input: 'What are the latest developments in quantum computing this week?',
  tools: [{ type: 'web_search_preview', search_context_size: 'high' }],
  stream: true,
});

for await (const event of stream) {
  switch (event.type) {
    case 'response.web_search_call.searching':
      console.log(`[Searching: "${event.query}"]`);
      break;
    case 'response.web_search_call.completed':
      console.log(`[Found ${event.results_count} results]\n`);
      break;
    case 'response.output_text.delta':
      process.stdout.write(event.delta);
      break;
    case 'response.completed':
      console.log('\n');
      break;
  }
}

from openai import OpenAI
import os

client = OpenAI(
    base_url=os.environ["NODEXA_BASE_URL"] + "/v1",
    api_key=os.environ["NODEXA_API_KEY"],
)

with client.responses.stream(
    model=os.environ["NODEXA_ASSISTANT_ID"],
    input="What are the latest developments in quantum computing this week?",
    tools=[{"type": "web_search_preview", "search_context_size": "high"}],
) as stream:
    for event in stream:
        if event.type == "response.web_search_call.searching":
            print(f'[Searching: "{event.query}"]')
        elif event.type == "response.web_search_call.completed":
            print(f"[Found {event.results_count} results]\n")
        elif event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
print()

---

Example 6 — User Claims Management

Store and retrieve structured user data.

Node.jsPython

const BASE_URL = process.env.NODEXA_BASE_URL;
const API_KEY = process.env.NODEXA_API_KEY;

async function nodexaFetch(path, options = {}) {
  const res = await fetch(`${BASE_URL}${path}`, {
    ...options,
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });
  if (res.status === 204) return null;
  return res.json();
}

const userId = 'user_demo_001';

// Sync user profile on signup/update
await nodexaFetch('/user-claims/bulk', {
  method: 'POST',
  body: JSON.stringify({
    claims: [
      { claimKey: 'name', claimValue: 'Alice Johnson' },
      { claimKey: 'role', claimValue: 'software_engineer' },
      { claimKey: 'plan', claimValue: 'pro' },
      { claimKey: 'preferred_language', claimValue: 'en' },
      {
        claimKey: 'preferences',
        claimValue: {
          responseStyle: 'concise',
          codeLanguage: 'typescript',
          timezone: 'America/New_York',
        },
      },
    ],
  }),
});

// Read back a specific claim
const planClaim = await nodexaFetch(`/user-claims/${userId}/plan`);
console.log('Plan:', planClaim.claimValue); // "pro"

// List all claims
const { claims: allClaims } = await nodexaFetch(`/user-claims/${userId}`);
console.log(`User has ${allClaims.length} claims`);

// Delete a claim (e.g. user removes a preference)
await nodexaFetch(`/user-claims/${userId}/preferences`, { method: 'DELETE' });

import requests, json, os

BASE_URL = os.environ["NODEXA_BASE_URL"]
API_KEY = os.environ["NODEXA_API_KEY"]
USER_ID = "user_demo_001"

def nodexa(method: str, path: str, **kwargs) -> dict | None:
    res = requests.request(
        method,
        BASE_URL + path,
        headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
        **kwargs,
    )
    if res.status_code == 204:
        return None
    return res.json()

# Bulk upsert on signup
nodexa("POST", "/user-claims/bulk", json={
    "claims": [
        {"userId": USER_ID, "claimKey": "name", "claimValue": "Alice Johnson"},
        {"userId": USER_ID, "claimKey": "role", "claimValue": "software_engineer"},
        {"userId": USER_ID, "claimKey": "plan", "claimValue": "pro"},
    ]
})

# Read back
plan = nodexa("GET", f"/user-claims/{USER_ID}/plan")
print("Plan:", plan["claimValue"])

# List all
all_claims = nodexa("GET", f"/user-claims/{USER_ID}")
print(f"User has {len(all_claims)} claims")

---

Example 7 — Handling Specialist Agent Handovers

Log handover events for analytics while transparently streaming the final response.

Node.js

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: process.env.NODEXA_BASE_URL + '/v1',
  apiKey: process.env.NODEXA_API_KEY,
});

const handovers = [];
let fullText = '';

const stream = await client.responses.create({
  model: process.env.NODEXA_ASSISTANT_ID,
  input: 'I need help with my subscription invoice from last month.',
  stream: true,
});

for await (const event of stream) {
  switch (event.type) {
    case 'response.output_item.added':
      if (event.item.type === 'handover') {
        handovers.push(event.item);
        console.error(
          `[Routing] ${event.item.from_specialist} → ${event.item.to_specialist}: ${event.item.reason}`
        );
      }
      break;

    case 'response.output_text.delta':
      process.stdout.write(event.delta);
      fullText += event.delta;
      break;

    case 'response.completed':
      console.log('\n');
      if (handovers.length > 0) {
        console.log(`Routing path: ${handovers.map((h) => h.to_specialist).join(' → ')}`);
      }
      break;
  }
}

---

Example 8 — Full GDPR Erasure Flow

Respond to a user's data deletion request by erasing all Nodexa data.

Node.jsPython

async function handleGdprErasureRequest(userId) {
  const apiKey = process.env.NODEXA_API_KEY;
  const base = process.env.NODEXA_BASE_URL;

  // 1. Delete all user claims (via public API)
  const { claims } = await fetch(
    `${base}/v1/user-claims/${userId}`,
    { headers: { 'x-api-key': apiKey } }
  ).then((r) => r.json());

  await Promise.all(
    claims.map((claim) =>
      fetch(
        `${base}/v1/user-claims/${userId}/${claim.claimKey}`,
        { method: 'DELETE', headers: { 'x-api-key': apiKey } }
      )
    )
  );

  console.log(`GDPR erasure complete for user ${userId}`);
  console.log(`  - Claims: ${claims.length} records deleted`);
  // Note: assistant memory erasure (conversation history and learned context)
  // must be requested via the Nodexa admin panel or support — there is no
  // public API endpoint for memory deletion.
}

await handleGdprErasureRequest('user_abc123');

import requests, os

def handle_gdpr_erasure(user_id: str):
    base = os.environ["NODEXA_BASE_URL"]
    api_key = os.environ["NODEXA_API_KEY"]

    # 1. Delete all user claims (via public API)
    response = requests.get(
        f"{base}/v1/user-claims/{user_id}",
        headers={"x-api-key": api_key},
    ).json()
    claims = response["claims"]

    for claim in claims:
        requests.delete(
            f"{base}/v1/user-claims/{user_id}/{claim['claimKey']}",
            headers={"x-api-key": api_key},
        )

    print(f"GDPR erasure complete for user {user_id}")
    print(f"  Claims: {len(claims)} records deleted")
    # Note: assistant memory erasure must be requested via the Nodexa admin
    # panel or support — there is no public API endpoint for memory deletion.

handle_gdpr_erasure("user_abc123")