SDKs

Saaya ships two first-party SDKs, TypeScript and Python, and they are the fastest way to integrate. Both are thin wrappers over the REST API with idiomatic helpers for streaming, auth, and pagination.

TypeScript

install.sh
npm install @saaya/sdk
# or
pnpm add @saaya/sdk
# or
bun add @saaya/sdk
use.ts
import { Saaya } from "@saaya/sdk";

const saaya = new Saaya(); // reads SAAYA_API_KEY + SAAYA_ORG_ID from env

// REST-shaped, mirrors the API exactly.
const agent = await saaya.agents.create({ name: "Maya", prompt: "…" });

// Streaming helpers for live sessions.
const stream = await saaya.sessions.stream({ agentId: agent.id, channel: "chat" });
stream.on("message.agent", (m) => console.log(m.text));
await stream.send("Hi");

Python

install.sh
pip install saaya
# or
uv add saaya
use.py
from saaya import Saaya

saaya = Saaya()  # reads SAAYA_API_KEY + SAAYA_ORG_ID from env

agent = saaya.agents.create(name="Maya", prompt="…")

# Async streaming via the same client.
async with saaya.sessions.stream(agent_id=agent.id, channel="chat") as session:
    await session.send("Hi")
    async for event in session:
        if event.type == "message.agent":
            print(event.text)

Idioms

  • All list endpoints return a cursor, use `for await (const item of saaya.sessions.iterate({…}))` to auto-paginate.
  • Streaming methods return an `AsyncIterable` plus a typed event emitter, pick whichever fits your code.
  • Errors are typed: `SaayaApiError`, `SaayaAuthError`, `SaayaRateLimitError`. Catch the parent class for "any Saaya error".
  • Both SDKs respect `SAAYA_BASE_URL` for custom endpoints (sandbox, on-prem, or recorded fixtures).

Versioning

SDKs follow semver against the API. A major bump in the SDK only happens when the wire protocol changes. Most months you can `^` upgrade safely.
PreviousMCP endpointNextWebhook events
Was this page helpful?