Skip to main content

​
Overview

The Client class is the main entry point for all interactions with the Noxus AI platform. It handles authentication, request management, and provides access to all SDK resources including workflows, conversations, knowledge bases, and agents.

​
Basic Initialization

The simplest way to create a client: 
from noxus_sdk.client import Client

client = Client(api_key="your_api_key_here")

​
Configuration Options

The client supports several configuration options for different use cases: 
client = Client(
    api_key="your_api_key_here",
    base_url="https://backend.noxus.ai",  # Custom backend URL
    load_nodes=True,                      # Load available node types
    load_me=True,                         # Load user information
    extra_headers={"Custom-Header": "value"}  # Additional headers
)
​
api_key
string
required
Your Noxus API key for authentication
​
base_url
string
default:"https://backend.noxus.ai"
The base URL of the Noxus backend. Can also be set via NOXUS_BACKEND_URL environment variable
​
load_nodes
boolean
default:"true"
Whether to automatically load available workflow node types on initialization
​
load_me
boolean
default:"true"
Whether to load user information and check admin permissions
​
extra_headers
dict
default:"None"
Additional HTTP headers to include with all requests

​
Environment Variables

The client respects these environment variables:
Override the default backend URL
export NOXUS_BACKEND_URL="https://your-custom-backend.com"
Set your API key (though passing it directly is recommended)
export NOXUS_API_KEY="your_api_key_here"

​
Resource Access

The client provides access to all Noxus resources through dedicated services: 
# Access different services
workflows = client.workflows.list()
conversations = client.conversations.list()
knowledge_bases = client.knowledge_bases.list()
agents = client.agents.list()
runs = client.runs.list()

# Admin functions (if you have admin permissions)
if client.admin.enabled:
    users = client.admin.list_users()

Workflows

client.workflows - Create and manage AI workflows

Conversations

client.conversations - Handle chat interactions

Knowledge Bases

client.knowledge_bases - Manage document repositories

Agents

client.agents - Deploy autonomous AI agents

Runs

client.runs - Monitor workflow executions

Admin

client.admin - Administrative functions

​
Platform Information Methods

The client provides methods to retrieve platform capabilities: 
# Get available workflow node types
nodes = client.get_nodes()
print(f"Available node types: {len(nodes)}")

# Get available AI models
models = client.get_models()
for model in models:
    print(f"Model: {model['name']} - {model['description']}")

# Get chat model presets
presets = client.get_chat_presets()
for preset in presets:
    print(f"Preset: {preset['name']} - {preset['model']}")

​
Asynchronous Versions

All platform information methods have async counterparts: 
import asyncio

async def get_platform_info():
    nodes = await client.aget_nodes()
    models = await client.aget_models()
    presets = await client.aget_chat_presets()
    return nodes, models, presets

# Run async function
nodes, models, presets = asyncio.run(get_platform_info())

​
Error Handling

The client handles various types of errors that can occur during API interactions: 
import httpx
from noxus_sdk.client import Client

try:
    client = Client(api_key="your_api_key")
    workflows = client.workflows.list()

except httpx.HTTPStatusError as e:
    if e.response.status_code == 401:
        print("Authentication failed - check your API key")
    elif e.response.status_code == 403:
        print("Access forbidden - check your permissions")
    elif e.response.status_code == 429:
        print("Rate limit exceeded - please wait before retrying")
    else:
        print(f"HTTP error {e.response.status_code}: {e.response.text}")

except httpx.RequestError as e:
    print(f"Network error: {e}")

except Exception as e:
    print(f"Unexpected error: {e}")

​
Best Practices

Never hardcode API keys in your source code:
import os
from noxus_sdk.client import Client

# ✅ Good - use environment variables
client = Client(api_key=os.getenv("NOXUS_API_KEY"))

# ❌ Bad - hardcoded API key
client = Client(api_key="noxus_1234567890abcdef")
Create one client instance and reuse it throughout your application:
# ✅ Good - singleton pattern
class NoxusService:
    _client = None
    
    @classmethod
    def get_client(cls):
        if cls._client is None:
            cls._client = Client(api_key=os.getenv("NOXUS_API_KEY"))
        return cls._client

# Use throughout your app
client = NoxusService.get_client()
Always implement proper error handling:
def safe_api_call(func, *args, **kwargs):
    try:
        return func(*args, **kwargs)
    except httpx.HTTPStatusError as e:
        logger.error(f"API error {e.response.status_code}: {e.response.text}")
        raise
    except httpx.RequestError as e:
        logger.error(f"Network error: {e}")
        raise

# Usage
workflows = safe_api_call(client.workflows.list)
Be mindful of resource usage with large datasets:
# ✅ Good - use pagination
page = 1
while True:
    workflows = client.workflows.list(page=page, page_size=50)
    if not workflows:
        break
    process_workflows(workflows)
    page += 1

# ❌ Bad - loading everything at once
all_workflows = client.workflows.list(page_size=10000)

​
Advanced Configuration

​
Custom HTTP Client

For advanced use cases, you can customize the underlying HTTP client: 
import httpx
from noxus_sdk.client import Client

# Create custom HTTP client with specific settings
http_client = httpx.Client(
    timeout=60.0,
    limits=httpx.Limits(max_connections=100, max_keepalive_connections=20)
)

# Note: This is a conceptual example - the actual SDK doesn't expose this yet
# but it shows the kind of customization that might be useful

​
Logging Configuration

Enable detailed logging for debugging: 
import logging
from noxus_sdk.client import Client

# Configure logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("noxus_sdk")

client = Client(api_key="your_api_key")

# Now all HTTP requests will be logged
workflows = client.workflows.list()

​
Testing with the Client

When writing tests, consider using dependency injection: 
import pytest
from unittest.mock import Mock
from noxus_sdk.client import Client

class MyService:
    def __init__(self, client: Client):
        self.client = client

    def get_workflow_count(self):
        workflows = self.client.workflows.list()
        return len(workflows)

# Test with mock client
def test_get_workflow_count():
    mock_client = Mock(spec=Client)
    mock_client.workflows.list.return_value = [Mock(), Mock(), Mock()]

    service = MyService(mock_client)
    count = service.get_workflow_count()

    assert count == 3
    mock_client.workflows.list.assert_called_once()

​
Next Steps

Authentication

Learn about API key management and security

Async Operations

Understand asynchronous programming with the SDK

Workflows

Start building AI workflows

API Reference

Explore the complete client API