Skip to main content
Agents are driven through conversations. You create a conversation bound to an agent, then send messages to it:
  • Create — POST /v1/conversations?assistant_id={agent_id}.
  • Chat (blocking) — POST /v1/conversations/{conversation_id}/chat returns the final reply.
  • Stream a reply — POST /v1/conversations/{conversation_id}/stream (Server-Sent Events).
  • Tail events — GET /v1/conversations/{conversation_id}/events (SSE for a run started elsewhere).
The streaming endpoints accept ?format=json for normalised {event, data} envelopes; omit it to receive raw Vercel AI SDK frames. Replace agent_id and your_api_key below.

​
Send a message and get the reply (blocking)

Simplest request/response. chat blocks until the agent finishes and returns its final message — use it when you only need the answer, not the intermediate steps.
# pip install noxus-sdk
from noxus_sdk.client import Client
from noxus_sdk.resources.conversations import MessageRequest

client = Client(api_key="your_api_key")

conversation = client.conversations.create("My Conversation", agent_id="agent_id")
print(f"conversation: {conversation.id}")

reply = conversation.chat(MessageRequest(content="Hello!"))
print(reply.parts)

import requests

base = "https://backend.noxus.ai"
headers = {"X-API-KEY": "your_api_key", "Content-Type": "application/json"}

# 1. Create the conversation
conv = requests.post(
    f"{base}/v1/conversations?assistant_id=agent_id",
    json={"name": "My Conversation"},
    headers=headers,
).json()
cid = conv["id"]

# 2. Chat (blocking) — returns the agent's last message
reply = requests.post(
    f"{base}/v1/conversations/{cid}/chat?assistant_id=agent_id",
    json={"content": "Hello!"},
    headers=headers,
).json()
print(reply["parts"])

const base = "https://backend.noxus.ai";
const headers = { "X-API-KEY": "your_api_key", "Content-Type": "application/json" };

// 1. Create the conversation
const conv = await fetch(`${base}/v1/conversations?assistant_id=agent_id`, {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "My Conversation" }),
}).then((r) => r.json());

// 2. Chat (blocking)
const reply = await fetch(
  `${base}/v1/conversations/${conv.id}/chat?assistant_id=agent_id`,
  { method: "POST", headers, body: JSON.stringify({ content: "Hello!" }) }
).then((r) => r.json());
console.log(reply.parts);

#!/bin/bash
base="https://backend.noxus.ai"

# 1. Create the conversation
cid=$(curl -s -X POST "$base/v1/conversations?assistant_id=agent_id" \
  -H "X-API-KEY: your_api_key" -H "Content-Type: application/json" \
  -d '{"name": "My Conversation"}' | jq -r '.id')

# 2. Chat (blocking)
curl -X POST "$base/v1/conversations/$cid/chat?assistant_id=agent_id" \
  -H "X-API-KEY: your_api_key" -H "Content-Type: application/json" \
  -d '{"content": "Hello!"}'

​
Stream the reply token-by-token (SSE)

Streams the agent’s response as it is generated. Best for chat UIs — render text deltas, tool calls, and steps as they arrive instead of waiting for the whole answer. Events look like text-delta, finish-step, etc.
from noxus_sdk.client import Client
from noxus_sdk.resources.conversations import MessageRequest

client = Client(api_key="your_api_key")
conversation = client.conversations.create("My Conversation", agent_id="agent_id")

for event in conversation.stream(MessageRequest(content="Hello!")):
    print(event.event, event.data)  # e.g. "text-delta", {...}

import json
import requests

base = "https://backend.noxus.ai"
cid = "<conversation_id>"  # from the create step
headers = {"X-API-KEY": "your_api_key", "Content-Type": "application/json"}

with requests.post(
    f"{base}/v1/conversations/{cid}/stream?assistant_id=agent_id&format=json",
    json={"content": "Hello!"},
    headers=headers,
    stream=True,
) as resp:
    for line in resp.iter_lines():
        if line and line.startswith(b"data:"):
            print(json.loads(line[len(b"data:"):]))

const base = "https://backend.noxus.ai";
const cid = "<conversation_id>"; // from the create step

const resp = await fetch(
  `${base}/v1/conversations/${cid}/stream?assistant_id=agent_id&format=json`,
  {
    method: "POST",
    headers: { "X-API-KEY": "your_api_key", "Content-Type": "application/json" },
    body: JSON.stringify({ content: "Hello!" }),
  }
);
const reader = resp.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value)); // SSE frames
}

#!/bin/bash
base="https://backend.noxus.ai"
cid="<conversation_id>"  # from the create step

# -N disables buffering so deltas arrive live
curl -N -X POST "$base/v1/conversations/$cid/stream?assistant_id=agent_id&format=json" \
  -H "X-API-KEY: your_api_key" -H "Content-Type: application/json" \
  -d '{"content": "Hello!"}'

​
Tail an in-progress conversation (SSE)

Attach to the live event stream of a run that was started elsewhere — for example a message you sent asynchronously, or a run shared across workers. Pass ?etag= to resume from a specific point in the stream.
from noxus_sdk.client import Client

client = Client(api_key="your_api_key")
conversation = client.conversations.get("conversation_id")

for event in conversation.iter_messages():  # or: async for ... in aiter_messages()
    print(event.event, event.data)

import json
import requests

base = "https://backend.noxus.ai"
cid = "conversation_id"

with requests.get(
    f"{base}/v1/conversations/{cid}/events?format=json",
    headers={"X-API-KEY": "your_api_key"},
    stream=True,
) as resp:
    for line in resp.iter_lines():
        if line and line.startswith(b"data:"):
            print(json.loads(line[len(b"data:"):]))

const base = "https://backend.noxus.ai";
const cid = "conversation_id";

const resp = await fetch(`${base}/v1/conversations/${cid}/events?format=json`, {
  headers: { "X-API-KEY": "your_api_key" },
});
const reader = resp.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

#!/bin/bash
base="https://backend.noxus.ai"
cid="conversation_id"

curl -N "$base/v1/conversations/$cid/events?format=json" \
  -H "X-API-KEY: your_api_key"

​
Send a message with file attachments

Attach files to a message via its files array. Each file needs a name plus either a public url or base64 b64_content (set type to the MIME type). A url is fetched server-side: it must be publicly reachable (private, loopback, and cloud-metadata addresses are rejected) and downloads are capped at 25 MB. This works with chat and with stream alike — the agent can read the attachment as part of the turn. 
from noxus_sdk.client import Client
from noxus_sdk.resources.conversations import MessageRequest, ConversationFile

client = Client(api_key="your_api_key")
conversation = client.conversations.create("My Conversation", agent_id="agent_id")

message = MessageRequest(
    content="Summarise this document",
    files=[ConversationFile(name="report.pdf", url="https://example.com/report.pdf")],
    # Or inline base64:
    # files=[ConversationFile(name="report.pdf", b64_content="<base64>", type="application/pdf")],
)
print(conversation.chat(message).parts)

import requests

base = "https://backend.noxus.ai"
headers = {"X-API-KEY": "your_api_key", "Content-Type": "application/json"}
cid = "<conversation_id>"  # from the create step

body = {
    "content": "Summarise this document",
    "files": [
        {
            "status": "success",
            "name": "report.pdf",
            "url": "https://example.com/report.pdf",
            "type": "application/pdf",
        }
    ],
}
reply = requests.post(
    f"{base}/v1/conversations/{cid}/chat?assistant_id=agent_id",
    json=body, headers=headers,
).json()
print(reply["parts"])

#!/bin/bash
base="https://backend.noxus.ai"
cid="<conversation_id>"  # from the create step

curl -X POST "$base/v1/conversations/$cid/chat?assistant_id=agent_id" \
  -H "X-API-KEY: your_api_key" -H "Content-Type: application/json" \
  -d '{
    "content": "Summarise this document",
    "files": [
      {"status": "success", "name": "report.pdf", "url": "https://example.com/report.pdf", "type": "application/pdf"}
    ]
  }'
Use a public url for files already hosted somewhere (fetched server-side, max 25 MB); use b64_content to inline a local file or one behind auth. The agent needs an enabled file-capable tool (e.g. file attachment / code execution) to act on attachments.
Chat flows use the same conversation endpoints — create the conversation with settings.agent_flow_id set to the chat flow’s id instead of passing assistant_id, then chat / stream exactly as above.