Runtime SDK - Aywa Runtime Docs

Before you install the SDK

The SDK is the developer layer for an already deployed runtime. Install the runtime first, wait for the heartbeat in app.aywaruntime.com, then create a runtime API key inside the private runtime dashboard.

1. Runtime URL

Use the public URL of your deployed runtime, for example https://runtime.customer.example.com.

2. API key

Create a runtime API key from the runtime dashboard. Keep it in your server environment.

3. Backend only

Call the SDK from trusted backend code. Do not expose runtime API keys in browsers or mobile apps.

4. Organization

Pass the runtime organization id when your runtime hosts several app organizations.

Install

Package

npm install @aywa-ai/runtime-sdk

The package name is @aywa-ai/runtime-sdk. It is runtime-only: billing, install tokens, license management, and support tickets stay in app.aywaruntime.com.

Create a client

The constructor requires baseUrl. This is intentional: self-hosted customers must know exactly which runtime receives API traffic.

server.ts

import { AywaRuntimeClient } from "@aywa-ai/runtime-sdk";

const aywa = new AywaRuntimeClient({
  baseUrl: process.env.AYWA_RUNTIME_BASE_URL,
  apiKey: process.env.AYWA_RUNTIME_API_KEY,
  organizationId: process.env.AYWA_RUNTIME_ORGANIZATION_ID,
});

AYWA_RUNTIME_BASE_URLYour deployed runtime endpoint, never the control plane.

AYWA_RUNTIME_API_KEYRuntime API key generated in the private runtime dashboard.

AYWA_RUNTIME_ORGANIZATION_IDOptional when the API key is scoped to one runtime organization; explicit is better for multi-tenant apps.

First read call

Start with a read-only request before creating resources. This validates auth, network, CORS policy for server environments, and organization scope.

List assistants

const assistants = await aywa.assistants.list({
  limit: 20,
});

console.log(assistants.items.map((assistant) => ({
  id: assistant.id,
  name: assistant.name,
})));

Create or import resources

Use idempotency keys for create/import flows so retries do not duplicate production resources. During migration, keep the source id mapping generated by the runtime migration assistant.

Create a draft assistant

const assistant = await aywa.assistants.create(
  {
    name: "Support concierge",
    model: {
      provider: "openai",
      model: "gpt-4.1-mini",
    },
  },
  {
    idempotencyKey: "assistant-support-concierge-v1",
  },
);

Assistants

Create, list, update, and delete assistant drafts through the runtime API surface.

Phone numbers

Import BYO phone numbers and keep telephony ownership in your runtime environment.

Tools

Read tool definitions and align backend tool contracts with the runtime webhook model.

Migration

Use generated mapping SQL to replace source IDs in your application database.

Webhooks and tools

Tool execution and server events stay runtime-side. Use signed webhooks for production callbacks and route external actions through a backend you control.

Webhook verifier shape

import { verifyAywaRuntimeWebhook } from "@aywa-ai/runtime-sdk/webhooks";

const event = verifyAywaRuntimeWebhook({
  body: rawBody,
  headers: request.headers,
  secret: process.env.AYWA_RUNTIME_WEBHOOK_SECRET,
});

See Tools and webhooks for event families, retry behavior, replay, and outbound request guardrails.

Production checklist

1baseUrlConfigured explicitly and points to the customer runtime.

2apiKeyStored server-side only and rotated from the runtime dashboard.

3organizationIdPassed explicitly for SaaS products with several runtime organizations.

4idempotencyKeyUsed for create/import operations that may be retried.

5webhooksVerified with signatures before processing runtime events.

Use your private runtime from backend code.