API design (preview)

This page sketches the surface we're designing towards for future SDKs. None of this is live. The goal is to make our intentions clear so we can be held to them later.

Principles

• Sessions first. Long-lived sessions with structure instead of one-shot completions.
• Explicit safety. Safety settings and risk signals are part of the API, not bolted on.
• Traceability. Every reply can be traced back to a model version, adaptation, and session.
• Boring on purpose. HTTP APIs, JSON payloads, clear error codes. No magic transport.

Client example

A TypeScript client might have a shape along these lines. Names will change as we test it:

import { EunoiaClient } from "@shv/eunoia";

const client = new EunoiaClient({
  apiKey: process.env.EUNOIA_API_KEY!,
  baseUrl: "https://api.shvgroups.com",
});

Creating an agent and session

const agent = await client.agents.create({
  id: "support-assistant",
  model: "eunoia-v1",
  role: "support",
  tools: ["knowledge-base", "email"],
  safety: { maxRisk: "medium" },
});

const session = await client.sessions.create({
  agentId: agent.id,
  userId: "user-123",
});

Sending messages

const turn = await session.chat.send({
  message: "I can't access my account, it keeps logging me out.",
});

console.log(turn.text);
console.log(turn.metadata.modelVersion);
console.log(turn.signals?.riskLevel);

Streaming

For interactive tools and UIs, streaming is mandatory. A typical pattern could be:

for await (const chunk of session.chat.stream({
  message: "Walk me through the latest training run results.",
})) {
  process.stdout.write(chunk.textDelta);
}

Authentication and limits

When the time comes to open this up, there will be:

• per-project API keys with clear scopes,
• rate limits by organisation and endpoint,
• usage reporting broken down by model and feature.

None of that exists yet. This page is a design document in public, not an announcement. If you're interested in shaping this surface, reach out via the early access form and mention API design in your notes.