> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Cookbook

> Copy-paste recipes for the most common API tasks, in every language

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.

<CardGroup cols={3}>
  <Card title="Workflows" icon="diagram-project" href="/api-reference/cookbook/workflows">
    Create runs and get results — wait (sync), poll, or stream over SSE.
  </Card>

  <Card title="Agents" icon="robot" href="/api-reference/cookbook/agents">
    Chat with an agent, stream replies token-by-token, and tail live events.
  </Card>

  <Card title="Knowledge Bases" icon="book" href="/api-reference/cookbook/knowledge-bases">
    Upload and ingest documents, then search them.
  </Card>
</CardGroup>

## Before you start

<Steps>
  <Step title="Get an API key">
    Create one under **Workspace settings → API keys**. All requests authenticate
    with the `X-API-KEY` header.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Install the SDK (optional)">
    `pip install noxus-sdk` for the Python examples. The REST/Node/cURL recipes
    have no dependency beyond an HTTP client.
  </Step>
</Steps>

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

## 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   |