API Cookbook

Task-oriented examples for the Noxus API and SDK. Each recipe shows the same operation in four flavours — Python SDK, Python REST (requests), Node (fetch/axios), and cURL — so you can drop it straight into your stack.

Workflows

Create runs and get results — wait (sync), poll, or stream over SSE.

Agents

Chat with an agent, stream replies token-by-token, and tail live events.

Knowledge Bases

Upload and ingest documents, then search them.

Before you start

Get an API key

Create one under Workspace control → API keys. All requests authenticate with the X-API-KEY header.

Pick a base URL

The managed cloud is https://backend.noxus.ai. Self-hosted deployments use their own host — the Python SDK reads NOXUS_BACKEND_URL or accepts base_url= on the Client.

Install the SDK (optional)

pip install noxus-sdk for the Python examples. The REST/Node/cURL recipes have no dependency beyond an HTTP client.

Never commit API keys. Load them from an environment variable or a secret manager. The examples use your_api_key as a placeholder.

Which execution pattern should I use?

Pattern	Use it when	Avoid it when
Wait (sync)	Short, interactive runs where you want one response	Long-running or highly parallel work — it ties up a connection
Poll	Long runs, or many runs in parallel; you control the cadence	You need sub-second latency on completion
Stream (SSE)	Live UIs that show node-by-node / token-by-token progress	Simple server-to-server calls where you only need the result

⌘I

Introduction

Cookbook

Workflows

Runs

Knowledge Bases

Conversations

Agents (Co-workers)

Triggers

Deployments

Platform

Sandboxes

Tables

Variables

Insights

System keys

Roles

Admin

Upload

Inboxes

Analytics

Workflows

Agents

Knowledge Bases

Before you start

Which execution pattern should I use?

Workflows

Agents

Knowledge Bases

​Before you start

​Which execution pattern should I use?

Before you start

Which execution pattern should I use?