https://api.nexusai.com/v3
ℹ️
Base URL

All API requests should be made to https://api.nexusai.com/v3. All responses are returned in JSON format. The API uses standard HTTP status codes and supports CORS.

Quick Start Example

cURL
curl https://api.nexusai.com/v3/chat/completions \n  -H "Authorization: Bearer nx_live_YOUR_API_KEY" \n  -H "Content-Type: application/json" \n  -d '{
    "model": "nexus-v3-ultra",
    "messages": [
      {"role": "user", "content": "Explain quantum computing"}
    ],
    "temperature": 0.7
  }'

Authentication #

NexusAI uses API keys for authentication. Include your API key in the Authorization header of every request. API keys can be generated from your dashboard.

Header
Authorization: Bearer nx_live_sk_7f8a9b2c3d4e5f6g7h8i9j0k
⚠️
Keep your API keys secure

Never expose your API keys in client-side code, public repositories, or browser-accessible locations. Use environment variables and server-side proxying for production applications.

API Key Types

Type Prefix Description
Live nx_live_ Production keys for live traffic and real data
Test nx_test_ Sandbox keys for development and testing — no charges apply
Restricted nx_restrict_ Scoped keys with limited permissions and rate limits

Rate Limiting #

API rate limits vary by plan tier. When you exceed your rate limit, the API returns a 429 Too Many Requests status code with a Retry-After header.

Rate Limits by Plan
Plan Requests / min Requests / day Concurrent
Starter 60 10,000 4
Professional 600 500,000 20
Enterprise Custom Unlimited Custom
Rate Limit Headers
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1702857600

Error Handling #

NexusAI uses conventional HTTP status codes to indicate the success or failure of a request. All errors follow a consistent response format.

Error Response Format
{
  "error": {
    "code": "invalid_request_error",
    "message": "Missing required field: model",
    "type": "ValidationError",
    "param": "model",
    "request_id": "req_8f7a6b5c4d3e2f1a0b9c"
  }
}

HTTP Status Codes

200 Success — The request was completed successfully
201 Created — A new resource was successfully created
400 Bad Request — The request was malformed or missing parameters
401 Unauthorized — Invalid or missing API key
403 Forbidden — API key lacks permission for this action
429 Too Many Requests — Rate limit exceeded. Check Retry-After header
500 Internal Server Error — Something went wrong on our end

Pagination #

All list endpoints support cursor-based pagination. Use the limit and cursor query parameters to paginate through results.

Pagination Response
{
  "data": [
    { ... },
    { ... },
    { ... }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6IjEyMyIsImNyZWF0ZWQiOiIyMDI0",
    "total_count": 142
  }
}
ℹ️
Pagination Tips

Default page size is 20. Maximum is 100. Always check has_more before making additional requests. Use next_cursor to fetch the next page.

List Models #

GET /models Retrieve all available models

Returns a list of all available AI models accessible with your API key. Models are sorted by creation date in descending order.

curl https://api.nexusai.com/v3/models \n  -H "Authorization: Bearer nx_live_YOUR_API_KEY"
from nexusai import NexusAI

client = NexusAI(api_key="nx_live_YOUR_API_KEY")
models = client.models.list()
print(models[0].name)
import { NexusAI } from "@nexusai/sdk";

const client = new NexusAI({
  apiKey: "nx_live_YOUR_API_KEY"
});

const models = await client.models.list();
console.log(models[0].name);
Query Parameters
Parameter Type Required Description
limit integer Optional Number of results to return (max 100). Default: 20
cursor string Optional Cursor for next page of results
type string Optional Filter by model type: text, vision, embedding
Response — 200 OK
{
  "data": [
    {
      "id": "nexus-v3-ultra",
      "name": "Nexus Ultra V3",
      "type": "text",
      "context_length": 128000,
      "max_tokens": 4096,
      "created": "2024-11-15T08:00:00Z",
      "status": "available"
    },
    {
      "id": "nexus-vision-2",
      "name": "Nexus Vision 2",
      "type": "vision",
      "context_length": 16000,
      "max_tokens": 2048,
      "created": "2024-10-20T12:30:00Z",
      "status": "available"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6IjEyMyJ9"
  }
}

Get Model #

GET /models/{model_id} Retrieve model details

Returns detailed information about a specific model, including capabilities, pricing, and configuration options.

Path Parameters
Parameter Type Required Description
model_id string Required The unique identifier of the model (e.g., nexus-v3-ultra)
Response — 200 OK
{
  "id": "nexus-v3-ultra",
  "name": "Nexus Ultra V3",
  "type": "text",
  "description": "Most capable model for complex reasoning and generation tasks",
  "context_length": 128000,
  "max_output_tokens": 4096,
  "pricing": {
    "input_per_1m_tokens": 0.01,
    "output_per_1m_tokens": 0.03,
    "currency": "USD"
  },
  "capabilities": [
    "text-generation",
    "chat",
    "function-calling",
    "json-mode"
  ],
  "status": "available",
  "created": "2024-11-15T08:00:00Z"
}

Chat Completions #

POST /chat/completions Generate chat completions

Creates a model response for the given chat conversation. This is the most commonly used endpoint for conversational AI applications. Supports streaming, function calling, and JSON mode.

Streaming Support

Set stream: true to receive responses as Server-Sent Events (SSE). Ideal for building real-time chat interfaces with token-by-token output.

curl https://api.nexusai.com/v3/chat/completions \n  -H "Authorization: Bearer nx_live_YOUR_API_KEY" \n  -H "Content-Type: application/json" \n  -d '{
    "model": "nexus-v3-ultra",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "temperature": 0.7,
    "max_tokens": 500,
    "stream": false
  }'
from nexusai import NexusAI

client = NexusAI(api_key="nx_live_YOUR_API_KEY")

response = client.chat.completions.create(
    model="nexus-v3-ultra",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"}
    ],
    temperature=0.7,
    max_tokens=500
)

print(response.choices[0].message.content)
import { NexusAI } from "@nexusai/sdk";

const client = new NexusAI({
  apiKey: "nx_live_YOUR_API_KEY"
});

const response = await client.chat.completions.create({
  model: "nexus-v3-ultra",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "What is the capital of France?" }
  ],
  temperature: 0.7,
  max_tokens: 500
});

console.log(response.choices[0].message.content);
Request Body
Parameter Type Required Description
model string Required The model to use (e.g., nexus-v3-ultra, nexus-vision-2)
messages array Required Array of message objects with role (system/user/assistant) and content
temperature float Optional Controls randomness (0.0-2.0). Lower = more deterministic. Default: 1.0
max_tokens integer Optional Maximum number of tokens to generate. Default: model's max
top_p float Optional Nucleus sampling parameter (0.0-1.0). Default: 1.0
stream boolean Optional Enable streaming response via SSE. Default: false
response_format object Optional Set { type: "json_object" } to force JSON output
tools array Optional Array of function/tool definitions for function calling
Response — 200 OK
{
  "id": "chatcmpl-8f7a6b5c4d3e2f1a0b",
  "object": "chat.completion",
  "model": "nexus-v3-ultra",
  "created": 1702857600,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris. It is the most populous city in France and is known for its iconic landmarks such as the Eiffel Tower, the Louvre Museum, and Notre-Dame Cathedral."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 47,
    "total_tokens": 75,
    "cost": 0.00135
  }
}
Streaming Response — 200 OK (SSE)
event: message
data: {"choices":[{"delta":{"role":"assistant"},"index":0}]}

event: message
data: {"choices":[{"delta":{"content":"The capital"},"index":0}]}

event: message
data: {"choices":[{"delta":{"content":" of France"},"index":0}]}

event: message
data: {"choices":[{"delta":{"content":" is Paris."},"index":0}]}

event: done
data: {"usage":{"prompt_tokens":28,"completion_tokens":6,"total_tokens":34}}

data: [DONE]

Embeddings #

POST /embeddings Generate vector embeddings

Creates a vector embedding for the given input text. Use these embeddings for semantic search, clustering, recommendation systems, and RAG pipelines.

curl https://api.nexusai.com/v3/embeddings \n  -H "Authorization: Bearer nx_live_YOUR_API_KEY" \n  -H "Content-Type: application/json" \n  -d '{
    "model": "nexus-embed-3",
    "input": "The quick brown fox jumps over the lazy dog",
    "encoding_format": "float"
  }'
from nexusai import NexusAI

client = NexusAI(api_key="nx_live_YOUR_API_KEY")

response = client.embeddings.create(
    model="nexus-embed-3",
    input="The quick brown fox jumps over the lazy dog"
)

embedding = response.data[0].embedding  # List[float]
print(len(embedding))  # 3072
Request Body
Parameter Type Required Description
model string Required Embedding model ID: nexus-embed-3 (3072-dim), nexus-embed-3-small (1536-dim)
input string | array Required Text to embed. Pass a string or array of strings (max 2048 items)
encoding_format string Optional Output format: float (default) or base64

Image Analysis #

POST /vision/analyze Analyze images with vision models

Analyze images using NexusAI's vision models. Supports object detection, image description, OCR, and visual question answering. Accepts base64-encoded images or public URLs.

cURL
curl https://api.nexusai.com/v3/vision/analyze \n  -H "Authorization: Bearer nx_live_YOUR_API_KEY" \n  -H "Content-Type: application/json" \n  -d '{
    "model": "nexus-vision-2",
    "image": "https://example.com/photo.jpg",
    "prompt": "Describe this image in detail",
    "detail": "high"
  }'
Request Body
Parameter Type Required Description
model string Required Vision model ID: nexus-vision-2
image string Required Public URL or base64-encoded image (PNG, JPEG, WebP)
prompt string Optional The question or instruction for the model. Default: "Describe this image"
detail string Optional Analysis detail level: low, high, auto. Default: auto
max_tokens integer Optional Maximum tokens in the response. Default: 1024

Create Agent #

POST /agents Create a new AI agent

Create an autonomous AI agent with custom instructions, tools, and knowledge bases. Agents can perform multi-step reasoning and use external tools to complete tasks.

Request Body
{
  "name": "Customer Support Agent",
  "model": "nexus-v3-ultra",
  "instructions": "You are a customer support agent. Help users with their account issues, order tracking, and refunds. Always be polite and empathetic.",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_order",
        "description": "Look up order by order ID",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string" }
          },
          "required": ["order_id"]
        }
      }
    }
  ],
  "knowledge_bases": ["kb_support_docs_v2"],
  "temperature": 0.3
}

Run Agent #

POST /agents/{agent_id}/runs Execute an agent run

Submit a task to an agent for execution. The agent will use its tools and knowledge to complete the task. Supports both synchronous and asynchronous execution modes.

curl https://api.nexusai.com/v3/agents/agt_8f7a/runs \n  -H "Authorization: Bearer nx_live_YOUR_API_KEY" \n  -H "Content-Type: application/json" \n  -d '{
    "input": "Where is my order #ORD-12345?",
    "stream": true
  }'
from nexusai import NexusAI

client = NexusAI(api_key="nx_live_YOUR_API_KEY")

run = client.agents["agt_8f7a"].runs.create(
    input="Where is my order #ORD-12345?",
    stream=True
)

for event in run:
    print(event.type, event.data)

Agent Status #

GET /agents/{agent_id}/runs/{run_id} Check run status

Retrieve the status and result of an agent run. For async runs, poll this endpoint until the status is completed, failed, or timed_out.

Response — 200 OK
{
  "id": "run_9c8b7a6f5e4d3c2b1a",
  "agent_id": "agt_8f7a",
  "status": "completed",
  "input": "Where is my order #ORD-12345?",
  "output": {
    "content": "Your order #ORD-12345 is currently out for delivery. It should arrive today by 5:00 PM.",
    "tool_calls": [
      {
        "name": "lookup_order",
        "arguments": { "order_id": "ORD-12345" },
        "result": "Order found: status=delivered, tracking=TRK9876"
      }
    ]
  },
  "usage": {
    "total_tokens": 342,
    "tool_calls": 1,
    "duration_ms": 2840
  },
  "created_at": "2024-12-18T14:22:00Z",
  "completed_at": "2024-12-18T14:22:03Z"
}

Webhooks #

Configure webhooks to receive real-time notifications about events in your NexusAI workspace. Webhooks are delivered as POST requests to your configured endpoint URL.

ℹ️
Webhook Security

Each webhook request includes a X-NexusAI-Signature header. Verify this signature using your webhook secret to ensure the request is authentic.

Available Events

agent.run.completed

Triggered when an agent run completes successfully or fails.

model.training.completed

Triggered when a custom model training job finishes.

rate_limit.warning

Triggered when usage reaches 80% of your plan's daily limit.

billing.invoice.finalized

Triggered when a new invoice is generated and finalized.

Webhook Payload Example

Webhook POST Body
{
  "id": "evt_8f7a6b5c4d3e2f1a0b9c",
  "type": "agent.run.completed",
  "created_at": "2024-12-18T14:22:03Z",
  "data": {
    "run_id": "run_9c8b7a6f5e4d3c2b1a",
    "agent_id": "agt_8f7a",
    "status": "completed",
    "duration_ms": 2840
  }
}

Verifying Signatures

Python
import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# Usage
is_valid = verify_webhook(
    payload=request.body,
    signature=request.headers["X-NexusAI-Signature"],
    secret="whsec_YOUR_WEBHOOK_SECRET"
)
🚫
Always verify signatures

Never process webhook events without verifying the signature. This prevents unauthorized parties from injecting malicious events into your system.

SDKs & Libraries #

Official SDKs are available for the following languages. All SDKs are open source and maintained on our GitHub organization.

🐍
Python
pip install nexusai
JavaScript / TS
npm install @nexusai/sdk
🦀
Rust
cargo add nexusai
Java
maven nexusai
💎
Ruby
gem install nexusai
🔨
Go
go get nexusai.dev/sdk