Qalyb

Developer overview

Updated July 2026

Everything you can click in the Qalyb dashboard, you can also drive from code. This page is your map of the developer surface: the v1 REST API, the TypeScript SDK, webhooks, and the embed script.

Everything you build on Qalyb runs against a single, versioned REST API. With it you can create and run voice and chat agents, place outbound calls, start in-browser voice sessions, call the Models API (text-to-speech, speech-to-text, and chat completions) directly, and receive real-time event notifications over webhooks. Below you'll find the base URL, auth in one line, and a pointer to the right doc for each surface.

Base URL

Every endpoint lives under the versioned /v1 prefix on the production host:

text
https://api.qalyb.ai/v1

There is one environment. Requests are JSON in, JSON out (with two exceptions: text-to-speech returns raw audio bytes, and speech-to-text takes a multipart upload). An interactive, always-current reference — generated from the live OpenAPI spec — is at the API reference.

qalyb.ai/docs/api
The interactive API reference renders every /v1 endpoint with a built-in request tester.

What you can build

The /v1 surface is organized into four areas:

AreaWhat it coversKey routes
AgentsFull CRUD plus call orchestration — create an agent, then place calls with it./v1/agents, /v1/agents/:id/calls, /v1/agents/:id/web-call
CallsRead a call's status, duration, and transcript after it runs./v1/calls/:id
VoicesList and fetch every voice available to your workspace (your own plus system voices); update or delete the ones your workspace owns./v1/voices, /v1/voices/:id
Models APICall the underlying TTS, STT, and LLM directly — no agent required. Useful for standalone synthesis, transcription, or chat./v1/tts, /v1/stt, /v1/llm/chat

Authentication in one line

Send an organization API key as a bearer token on every request. Keys look like sk-live-... and authenticate as an admin of your org:

curl · bash
curl https://api.qalyb.ai/v1/me \
  -H "Authorization: Bearer sk-live-..."

The fastest way to confirm a key works is GET /v1/me, which introspects the credential and returns the identity it resolves to:

GET /v1/me · json
{
  "authenticated": true,
  "authType": "api_key",
  "organizationId": "org_8f1c...",
  "user": { "id": "...", "email": "..." }
}
Creating a key:
keys are minted and revoked from API key management in your workspace settings. You need the org admin role (key management is available on the Pro and Ultra plans), and the full key value is shown once at creation — copy it then, because afterwards only the prefix is visible. Full setup is in Authentication.
app.qalyb.ai
API keys are created and revoked by workspace admins. The full sk-live- value is revealed only once, at creation.

The SDK

The official TypeScript SDK (@qalyb/sdk) is a typed, Zod-validated wrapper over the same /v1 routes. It exposes namespaces for agents, calls, voices, and the Models API, and throws a typed QalybApiError (with status, code, and message) on any non-2xx response. It targets Node 18+, Bun, Deno, and Cloudflare Workers, and defaults its base URL to https://api.qalyb.ai.

quickstart.ts · ts
import { Qalyb } from '@qalyb/sdk';

const qalyb = new Qalyb({ apiKey: process.env.QALYB_API_KEY! });

// Create an agent, then place a call
const agent = await qalyb.agents.create({
  name: 'Bookings Concierge',
  personaId: 'p47e2c12-8b8d-4f8e-9b16-7c1a8f9c3a01',
});

const call = await qalyb.agents.startCall(agent.id, {
  phoneNumber: '+971501234567',
});
SDK availability:
the TypeScript SDK is in private preview and is not yet published to the public npm registry. A Python SDK is on the roadmap (marked "coming soon") — until it lands, call the REST API directly from Python with any HTTP client. See SDKs for current status and install details.

Webhooks

Webhooks push real-time event notifications to your own HTTPS endpoints as conversations happen — a call starting, a call completing, post-call analysis finishing, or a widget / messaging session beginning and ending. You register receiver URLs, subscribe to events per channel, and Qalyb POSTs a signed payload to each one.

Every delivery carries an X-Qalyb-Signature header so you can verify it came from Qalyb. The signature is an HMAC-SHA256 over "<timestamp>.<body>", encoded as t=<timestamp>,v1=<hex> — not a bare HMAC of the body. The actually-dispatched events are call.started, call.completed, call.failed, call.analyzed, widget.started, widget.completed, and per-channel messaging variants such as whatsapp.started / whatsapp.completed.

Webhooks are managed from the main sidebar under Webhooks (/webhooks) — register endpoints, choose channels and events, reveal or rotate the signing secret, send a test delivery, and watch delivery logs. The verification snippet shown on the endpoint's Security tab is the authoritative reference for checking signatures.

Important:
managing webhooks requires the org admin role — non-admins see an "Admin access required" wall. Full event list, payload shape, and signature verification code are in the webhooks guide.

The embed script

To put a chat or voice agent on your own website, drop in the embed script. It loads the Qalyb widget bundle from the CDN and self-initializes from a widget token — no API key and no extra code:

index.html · html
<script
  src="https://cdn.qalyb.ai/widget.js"
  data-qalyb-token="YOUR_FULL_WIDGET_TOKEN"
  async
></script>

The widget token is separate from your sk-live- API key: it is scoped to a single widget and is safe to ship in client-side HTML. Generate it when you create a web widget channel. Customization (attributes, the JavaScript API, and the React component) is covered in the embed guide.

Streaming

The current API is request/response only. LLM chat completions are non-streaming (stream: true returns a 400), and TTS returns the full audio buffer rather than a stream. A WebSocket surface for low-latency streaming is planned but not yet available.

Was this guide helpful?
Next →
Authentication