Nodex AI
Theme

Developer Docs

Integration overview, authentication, API reference, SDKs, CLI, Web Chat, SSE resume, billing, errors, and status support.

Introduction

Introduction

Nodex AI provides shared identity, quota, billing, routing, and session records across API, CLI, and Web Chat product forms. V1 public access centers on the Singapore node, Alipay subscriptions, and OpenAI/Claude-compatible protocols.

Scope
Product forms: API / CLI / Web Chat
Region: Singapore
Protocols: OpenAI-compatible / Claude-compatible / SSE
Billing: subscription + token metering
Session storage: metadata + encrypted request/response body references

Quickstart

Create an API key in Console, then point your SDK base URL to Nodex. Every paid request must include an idempotency key, and streaming requests should include a session id.

cURL
curl https://api.nodex-ai.net/v1/chat/completions \
  -H "Authorization: Bearer $NODEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: req_$(uuidgen)" \
  -H "X-Nodex-Session-Id: sess_docs_quickstart" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{"role": "user", "content": "Hello Nodex"}],
    "stream": true
  }'

Bearer Token Authentication

Authenticate requests by including your API key in the Authorization HTTP header as a Bearer token. Do not store runtime API keys in browsers; Web Chat uses server-side short-lived relay credentials.

cURL Request
curl https://api.nodex-ai.net/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Keep your keys secure

Your API keys carry many privileges, so keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub or client-side code.

API Reference

V1 exposes four model API families: OpenAI Chat Completions, OpenAI Responses, Claude Messages, and Models. All endpoints pass through shared authentication, routing, idempotency, quota, and billing layers.

Endpoints
GET  /v1/models
POST /v1/chat/completions
POST /v1/responses
POST /v1/messages

Chat Completions

Chat Completions accepts the OpenAI SDK messages format and supports stream=true SSE responses. Response headers include Nodex request, session, and node metadata.

Request
POST https://api.nodex-ai.net/v1/chat/completions
Authorization: Bearer $NODEX_API_KEY
X-Idempotency-Key: req_01
X-Nodex-Session-Id: sess_01

{
  "model": "gpt-5.4",
  "messages": [{"role": "user", "content": "Summarize this."}],
  "stream": true
}

Responses & Messages

Responses supports newer OpenAI-style workflows; Messages supports Claude-compatible calls. Nodex adapts protocols at the gateway boundary while preserving unified session and billing records.

Examples
POST /v1/responses
{
  "model": "gpt-5.4",
  "input": "Generate a release note."
}

POST /v1/messages
{
  "model": "claude-sonnet-4.6",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Review this design."}]
}

SSE Streaming & Resume

Streaming requests support Last-Event-ID resume. After a disconnect, reconnect with the same X-Idempotency-Key, same X-Nodex-Session-Id, and the last received event id.

Resume Headers
Last-Event-ID: evt_00042
X-Idempotency-Key: req_01
X-Nodex-Session-Id: sess_01

Idempotency & Billing

Idempotency keys prevent duplicate charges caused by network retries. Nodex estimates tokens, reserves balance, then settles by final token usage and pricing version.

Billing Headers
Required:
Authorization: Bearer $NODEX_API_KEY
X-Idempotency-Key: req_unique_per_business_action

Recommended:
X-Nodex-Session-Id: sess_user_visible_thread
Avoid duplicate billing

Use one idempotency key for one business request only. Do not reuse it across prompts, models, or users.

SDKs & CLI

OpenAI SDKs only need a baseURL change; Claude SDKs use the compatible /v1/messages entrypoint. CLI Provider shares the same account balance and permission boundary.

SDK / CLI
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NODEX_API_KEY,
  baseURL: "https://api.nodex-ai.net/v1",
});

// CLI
nodex login
nodex env export openai

Web Chat

Web Chat uses the Nodex Console session and does not expose runtime API keys in the browser. Conversations, requests, responses, SSE summaries, and billing metadata are stored through the shared backend.

Flow
Web Chat flow:
1. User signs in to Console
2. Server creates a short-lived runtime key
3. Gateway streams SSE with session metadata
4. Server revokes the short-lived key after completion

Error Codes

Error responses use a shared envelope. Clients should branch on error.code and record X-Nodex-Request-Id for troubleshooting.

JSON
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key provided.",
    "request_id": "req_01..."
  }
}

Common codes:
unauthenticated, invalid_api_key, idempotency_key_required,
insufficient_balance, rate_limited, upstream_unavailable,
model_forbidden, body_too_large

Status & Support

Status and support channels help troubleshoot node, upstream, payment, reconciliation, and account issues. For production issues, provide request id, session id, time window, and model name.

Troubleshooting Bundle
Troubleshooting bundle:
request_id=req_...
session_id=sess_...
model=gpt-5.4
time_window=2026-05-11T10:00:00Z/2026-05-11T10:05:00Z
symptom=stream_disconnected