Skip to content

Quickstart

Get your first Nodexa API call working in under 5 minutes.

Prerequisites

  • A Nodexa API key (format: nxk_...) — contact your platform administrator
  • The UUID of an assistant configured on your Nodexa instance
  • curl, Node.js 18+, or Python 3.9+ installed

Step 1 — Get Your API Key and Assistant ID

Your API key and assistant ID are provided by your Nodexa platform administrator. You will need:

Value Example Description
API Key nxk_abc123... Your secret key — never expose it client-side
Assistant ID asst_01234567-89ab-cdef-0123-456789abcdef UUID of the assistant you want to call
Base URL https://your-admin.example.com Hostname of your Nodexa deployment

Store these as environment variables so you don't accidentally paste them into code:

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

Step 2 — Make Your First Request

curl "$NODEXA_BASE_URL/v1/responses" \
  -H "x-api-key: $NODEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$NODEXA_ASSISTANT_ID\",
    \"input\": \"Hello! What can you help me with?\"
  }"

Install the OpenAI SDK if you haven't already:

npm install openai

Then run:

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: 'Hello! What can you help me with?',
});

console.log(response.output_text);

Install the OpenAI SDK if you haven't already:

pip install openai

Then run:

import os
from openai import OpenAI

client = OpenAI(
    base_url=f"{os.environ['NODEXA_BASE_URL']}/v1",
    api_key=os.environ['NODEXA_API_KEY'],
)

response = client.responses.create(
    model=os.environ['NODEXA_ASSISTANT_ID'],
    input="Hello! What can you help me with?",
)

print(response.output_text)

Step 3 — Handle the Response

A successful non-streaming response looks like this:

{
  "id": "resp_01234567-89ab-cdef-0123-456789abcdef",
  "object": "response",
  "status": "completed",
  "model": "asst_01234567-89ab-cdef-0123-456789abcdef",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! I'm your AI assistant. I can help you with..."
        }
      ]
    }
  ],
  "output_text": "Hello! I'm your AI assistant. I can help you with...",
  "created_at": 1700000000
}

The most important fields:

Field Type Description
id string Unique response ID — save this to continue the conversation
status string "completed" or "requires_action" (tool execution needed)
output_text string Convenience field with the assistant's text reply
output array Full structured output including messages and tool calls

For a better user experience, stream the response token by token:

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: 'Tell me a short story about a robot.',
  stream: true,
});

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}
console.log(); // newline at end

import os
from openai import OpenAI

client = OpenAI(
    base_url=f"{os.environ['NODEXA_BASE_URL']}/v1",
    api_key=os.environ['NODEXA_API_KEY'],
)

with client.responses.stream(
    model=os.environ['NODEXA_ASSISTANT_ID'],
    input="Tell me a short story about a robot.",
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
print()  # newline at end

curl "$NODEXA_BASE_URL/v1/responses" \
  -H "x-api-key: $NODEXA_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d "{
    \"model\": \"$NODEXA_ASSISTANT_ID\",
    \"input\": \"Tell me a short story about a robot.\",
    \"stream\": true
  }"

Step 5 — Continue the Conversation

Use the id from the previous response as previous_response_id to maintain conversation history:

// First turn
const first = await client.responses.create({
  model: process.env.NODEXA_ASSISTANT_ID,
  input: 'My name is Alice.',
});

// Second turn — references the first response
const second = await client.responses.create({
  model: process.env.NODEXA_ASSISTANT_ID,
  input: 'What is my name?',
  previous_response_id: first.id,
});

console.log(second.output_text); // "Your name is Alice."

# First turn
FIRST_RESPONSE=$(curl -s "$NODEXA_BASE_URL/v1/responses" \
  -H "x-api-key: $NODEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"$NODEXA_ASSISTANT_ID\", \"input\": \"My name is Alice.\"}")

RESPONSE_ID=$(echo $FIRST_RESPONSE | jq -r '.id')

# Second turn
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 is my name?\",
    \"previous_response_id\": \"$RESPONSE_ID\"
  }"

Next Steps