Skip to main content

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.

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)

​
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", {...}

​
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)

​
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)
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.