Integration Guide

# All REST requests use Bearer auth with your project API key
curl -H "Authorization: Bearer sk_your_api_key" \
  https://api.sonz.ai/api/v1/agents/{agentId}/chat

# Chat (SSE streaming response)
POST /api/v1/agents/{agentId}/chat
{ "messages": [{"role":"user","content":"Hello!"}], "user_id": "user-123" }

# Response: Server-Sent Events
# data: {"choices":[{"delta":{"content":"Hi"}}]}
# data: [DONE]

POST /api/v1/agents                              Create agent
GET  /api/v1/agents                              List agents
GET  /api/v1/agents/{agentId}                    Get agent
POST /api/v1/agents/{agentId}/chat               Chat (SSE streaming)
GET  /api/v1/agents/{agentId}/notifications       Pending notifications
POST /api/v1/agents/{agentId}/notifications/{id}/consume  Consume notification
GET  /api/v1/agents/{agentId}/notifications/history       Notification history

import { Sonzai } from "@sonzai-labs/agents";

const client = new Sonzai({ apiKey: "sk_your_api_key" });

// Chat (non-streaming)
const response = await client.agents.chat("agent-id", {
  messages: [{ role: "user", content: "Hello!" }],
  userId: "user-123",
});
console.log(response.content);

// Chat (streaming)
for await (const event of client.agents.chatStream("agent-id", {
  messages: [{ role: "user", content: "Tell me a story" }],
  userId: "user-123",
  language: "en",
  timezone: "America/New_York",
})) {
  process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

// Memory, personality, context engine data
const memory = await client.agents.memory.list("agent-id", { userId: "user-123" });
const personality = await client.agents.personality.get("agent-id");
const mood = await client.agents.getMood("agent-id", { userId: "user-123" });

from sonzai import Sonzai

client = Sonzai(api_key="sk_your_api_key")

# Chat (non-streaming)
response = client.agents.chat(
    "agent-id",
    messages=[{"role": "user", "content": "Hello!"}],
    user_id="user-123",
)
print(response.content)

# Chat (streaming)
for event in client.agents.chat(
    "agent-id",
    messages=[{"role": "user", "content": "Tell me a story"}],
    user_id="user-123",
    language="en",
    timezone="America/New_York",
    stream=True,
):
    print(event.content, end="", flush=True)

# Memory, personality, context engine data
memory = client.agents.memory.list("agent-id", user_id="user-123")
personality = client.agents.personality.get("agent-id")
mood = client.agents.get_mood("agent-id", user_id="user-123")

client.close()

// app/api/chat/route.ts (runs on your server)
import { Sonzai } from "@sonzai-labs/agents";

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });

export async function POST(req: Request) {
  const { agentId, messages, userId } = await req.json();
  const stream = client.agents.chatStream(agentId, { messages, userId });

  return new Response(
    new ReadableStream({
      async start(controller) {
        for await (const event of stream) {
          controller.enqueue(new TextEncoder().encode(
            `data: ${JSON.stringify(event)}\n\n`
          ));
        }
        controller.enqueue(new TextEncoder().encode("data: [DONE]\n\n"));
        controller.close();
      },
    }),
    { headers: { "Content-Type": "text/event-stream" } }
  );
}

// Calls YOUR server, not Sonzai directly
const res = await fetch("/api/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    agentId: "agent-uuid",
    messages: [{ role: "user", content: "Hello!" }],
    userId: "user-123",
  }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  // Parse SSE chunks from your proxy
  console.log(decoder.decode(value));
}

// server.ts
import express from "express";
import { Sonzai } from "@sonzai-labs/agents";

const app = express();
const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });

app.post("/api/chat", async (req, res) => {
  const { agentId, messages, userId } = req.body;
  res.setHeader("Content-Type", "text/event-stream");

  for await (const event of client.agents.chatStream(agentId, { messages, userId })) {
    res.write(`data: ${JSON.stringify(event)}\n\n`);
  }
  res.write("data: [DONE]\n\n");
  res.end();
});

import sonzai "github.com/sonz-ai/sonzai-go"

// Connects to api.sonz.ai by default — just provide your API key
client := sonzai.NewClient("sk_your_api_key")

// Override the base URL for local dev / self-hosted
client := sonzai.NewClient("sk_your_api_key",
    sonzai.WithBaseURL("http://localhost:8090"),
)

resp, err := client.Agents.Create(ctx, sonzai.CreateAgentRequest{
    Name:   "Luna",
    Gender: "female",
    Big5: sonzai.Big5Scores{
        Openness:          0.75,
        Conscientiousness: 0.60,
        Extraversion:      0.80,
        Agreeableness:     0.70,
        Neuroticism:       0.30,
    },
    Language: "en",
})
// resp.AgentID is the platform-generated UUID
// Store this in your user record

agent, err := client.Agents.Get(ctx, agentId)
// agent includes: name, personality prompt, big5, mood, etc.

stream, err := client.Agents.ChatStream(ctx, agentId, sonzai.ChatRequest{
    UserID:    userId,
    Messages: []sonzai.Message{
        {Role: "user", Content: "I had a great day hiking!"},
    },
    Language: "en",
})

// Read streaming events
for event := range stream {
    fmt.Print(event.Content)
}