Quickstart

SDK Quickstart

Go from an empty project to your first Xpectrum response in a few minutes. The SDK gives your server a simple way to call chat, keep user context, and grow into workflows and voice.

What you will build

This guide creates a small server-side chat client. It sends a message for one user, prints the answer, and leaves room for streaming and conversation history when you are ready.

1. Create an API key

Create a Xpectrum workspace and API key in the dashboard. Keep the key private: it should live in your server environment, never in a browser bundle or public repository.

bash

export XPECTRUM_API_KEY="xpectrum_XXXXXXXXXXXXXXXX"

2. Install the SDK

bash

npm install xpectrum

The SDK talks to the same OpenAI-compatible API underneath, so you can also start with plain HTTP or an OpenAI client and add the SDK as your application becomes more involved.

3. Send your first message

typescript

import { XpectrumChat } from "xpectrum";

const chat = new XpectrumChat({
  baseUrl: "https://cloud.xpectrum.dev/v1",
  apiKey: process.env.XPECTRUM_API_KEY!,
  user: "user-123",
});

const response = await chat.send("Give me a one-sentence summary of our support queue.");
console.log(response.content);

Use a stable, non-sensitive user identifier. Xpectrum uses it to keep conversations and server-side memory associated with the right person.

4. Stream a response

Streaming lets your interface show the answer as it arrives instead of waiting for the complete response.

typescript

const stream = await chat.stream("Draft a reply to this customer message.");

for await (const chunk of stream) {
  process.stdout.write(chunk.content ?? "");
}

5. Put it behind your app server

Your browser should call your own application route. That route reads the secret key from the environment and calls Xpectrum on the user's behalf.

typescript

// app/api/chat/route.ts
import { XpectrumChat } from "xpectrum";

export async function POST(request: Request) {
  const { message, userId } = await request.json();
  const chat = new XpectrumChat({
    baseUrl: "https://cloud.xpectrum.dev/v1",
    apiKey: process.env.XPECTRUM_API_KEY!,
    user: userId,
  });

  const response = await chat.send(message);
  return Response.json({ content: response.content });
}

6. Keep building

Once the first request works, connect a knowledge base, add a workflow run, or give the experience a voice interface. The same API key and user context carry across those building blocks.

Common first questions

Can I use another language?

Yes. Xpectrum exposes HTTP endpoints with an OpenAI-compatible shape, so any language that can make authenticated requests can use it.

Can I call Xpectrum directly from the browser?

Only with a short-lived, server-issued credential. For most apps, keep the permanent API key in your server route.

Where do I see errors?

Start with the error reference. Errors use a predictable envelope and include an HTTP status that your route can pass on or translate for your UI.