Agent

The agent endpoint is the primary way to query your knowledge base using AI. It accepts a message and workspace IDs, performs vector search, and streams an AI-generated answer with source citations via Server-Sent Events (SSE).

Base URL

The agent runs on a dedicated endpoint, separate from the REST API:

https://agent.auboz.com

Query Agent

POST /agent/stream

Scope: chat:write

Requires: Active subscription + available credits

Request Body

{
  "message": "What are the key findings in the Q4 report?",
  "workspaceIds": ["ws_abc123"],
  "sessionId": "optional-session-id",
  "mode": "fast"
}

Parameters

Field	Type	Description
`message`	string	Required. The question to ask (max 50,000 characters)
`workspaceIds`	string[]	Required. Workspace IDs to search. Must be workspaces you own
`sessionId`	string	Optional. Pass to continue a conversation. Omit to start a new session
`mode`	string	`"fast"` (default) for single-pass answers, `"deep"` for multi-hop research with verification

Response (SSE Stream)

The response is a stream of Server-Sent Events. Each event has a type field indicating its kind.

Event order: job_started → token (repeated) → sources → done

SSE stream

data: {"type":"job_started","jobId":"job_abc123"}

data: {"type":"token","content":"The Q4 report "}

data: {"type":"token","content":"highlights revenue growth "}

data: {"type":"token","content":"of 40%..."}

data: {"type":"sources","sources":[{"doc_id":"doc_abc","filename":"Q4-Report.pdf","pages":[3,4]}]}

data: {"type":"done","jobId":"job_abc123","sessionId":"sess_xyz789","creditsUsed":2}

Event Types

Event	Fields	Description
`job_started`	`jobId`	Emitted once when processing begins
`token`	`content`	Streamed text chunk. Concatenate all `content` values for the full answer
`sources`	`sources`	Array of source documents referenced in the answer
`reasoning`	`steps`	Reasoning steps (emitted in `deep` mode)
`done`	`jobId`, `sessionId`, `creditsUsed`	Final event. Use `sessionId` for follow-up messages
`error`	`message`	Emitted if processing fails

Agent Modes

fast (default): Single-pass search and answer. Best for straightforward questions.

deep: Multi-hop research with iterative search refinement and answer verification. Uses more credits but produces more thorough, well-sourced answers for complex questions.

Examples

curl

curl (streaming)

curl -N -X POST https://agent.auboz.com/agent/stream \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarize the main contract terms",
    "workspaceIds": ["your-workspace-id"]
  }'

The -N flag disables output buffering so you see tokens as they arrive.

Python

Python (with sseclient-py)

import requests
import sseclient
import json

response = requests.post(
    "https://agent.auboz.com/agent/stream",
    headers={
        "Authorization": "Bearer sk_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "message": "Summarize the main contract terms",
        "workspaceIds": ["your-workspace-id"],
        "mode": "deep",
    },
    stream=True,
)

client = sseclient.SSEClient(response)
answer = ""
for event in client.events():
    data = json.loads(event.data)
    if data["type"] == "token":
        answer += data["content"]
        print(data["content"], end="", flush=True)
    elif data["type"] == "sources":
        print(f"\n\nSources: {data['sources']}")
    elif data["type"] == "done":
        print(f"\n\nSession: {data['sessionId']}")
        print(f"Credits used: {data['creditsUsed']}")
    elif data["type"] == "error":
        print(f"\nError: {data['message']}")

Install the SSE client: pip install sseclient-py

TypeScript

TypeScript (fetch)

const response = await fetch("https://agent.auboz.com/agent/stream", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Summarize the main contract terms",
    workspaceIds: ["your-workspace-id"],
  }),
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();
let answer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value, { stream: true });
  for (const line of chunk.split("\n")) {
    if (!line.startsWith("data: ")) continue;
    const data = JSON.parse(line.slice(6));

    switch (data.type) {
      case "token":
        answer += data.content;
        process.stdout.write(data.content);
        break;
      case "sources":
        console.log("\nSources:", data.sources);
        break;
      case "done":
        console.log(`\nSession: ${data.sessionId}`);
        console.log(`Credits: ${data.creditsUsed}`);
        break;
      case "error":
        console.error("Error:", data.message);
        break;
    }
  }
}

On this page