API Reference
Comprehensive guide to the NexusAI REST API. Build integrations, automate workflows, and deploy AI-powered solutions at scale.
https://api.nexusai.com/v3
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 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.
Authorization: Bearer nx_live_sk_7f8a9b2c3d4e5f6g7h8i9j0k
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.
| Plan | Requests / min | Requests / day | Concurrent |
|---|---|---|---|
| Starter | 60 | 10,000 | 4 |
| Professional | 600 | 500,000 | 20 |
| Enterprise | Custom | Unlimited | Custom |
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": { "code": "invalid_request_error", "message": "Missing required field: model", "type": "ValidationError", "param": "model", "request_id": "req_8f7a6b5c4d3e2f1a0b9c" } }
HTTP Status Codes
Retry-After header
Pagination #
All list endpoints support cursor-based pagination. Use the limit and cursor query parameters to paginate through results.
{ "data": [ { ... }, { ... }, { ... } ], "pagination": { "has_more": true, "next_cursor": "eyJpZCI6IjEyMyIsImNyZWF0ZWQiOiIyMDI0", "total_count": 142 } }
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 #
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);
| 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 |
{ "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 #
Returns detailed information about a specific model, including capabilities, pricing, and configuration options.
| Parameter | Type | Required | Description |
|---|---|---|---|
| model_id | string | Required | The unique identifier of the model (e.g., nexus-v3-ultra) |
{ "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 #
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.
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);
| 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 |
{ "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 } }
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 #
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
| 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 #
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 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" }'
| 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 #
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.
{ "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 #
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 #
Retrieve the status and result of an agent run. For async runs, poll this endpoint until the status is completed, failed, or timed_out.
{ "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.
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
{ "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
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" )
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.
pip install nexusai
npm install @nexusai/sdk
cargo add nexusai
maven nexusai
gem install nexusai
go get nexusai.dev/sdk