Aywa RuntimeDocumentation
Website Create account

Runtime API

A migration-friendly API surface for production voice agents.

The runtime exposes assistants, phone numbers, calls, tools, credentials, logs, metrics, files, and webhook endpoints through a private HTTP API.

Authentication

Production routes require API authentication. Health and readiness endpoints stay public so load balancers and orchestration systems can probe the service.

Headers 
Authorization: Bearer <runtime-api-key>
X-API-Key: <runtime-api-key>

Supabase Auth can also be enabled for dashboard or user sessions. Runtime API keys remain the simplest mechanism for server-to-server traffic.

SDK-ready contract

The runtime API is designed for a TypeScript SDK that talks directly to the deployed runtime endpoint. The SDK client must receive an explicit baseUrl; the control plane at app.aywaruntime.com is for license, install, billing, support, and status workflows, not for call/data-path SDK traffic.

For a step-by-step backend setup, use the dedicated Runtime SDK guide.

Install 
npm install @aywa-ai/runtime-sdk
baseUrlRequired runtime URL, for example https://runtime.customer.example.com.
authRuntime API key sent as bearer token or X-API-Key.
idempotencyClient-provided keys for create/import flows where supported.
webhooksSigned event verification helpers for server events.
SDK shape 
import { AywaRuntimeClient } from "@aywa-ai/runtime-sdk";

const client = new AywaRuntimeClient({
  baseUrl: "https://runtime.customer.example.com",
  apiKey: process.env.AYWA_RUNTIME_API_KEY,
});
Interactive

Test your runtime API.

Enter the base URL of your deployed runtime and a runtime API key. The key is kept in this browser session and is used only for requests sent to the base URL you provide.

Browser requests require your runtime CORS policy to allow https://docs.aywaruntime.com. If CORS is closed, use the generated cURL locally.
Generated cURL 
curl -fsSL https://runtime.example.com/readyz
Response 
Run a request to see the response here.

Core resources

/assistantCreate, list, read, patch, and delete assistant configurations.
/phone-numberManage BYO phone numbers and their assistant or SIP credential bindings.
/callCreate outbound, inbound, web, or phone calls and inspect call state.
/toolCreate and manage tools that can be attached to assistant model configuration.
/credentialStore reusable server, webhook, provider, or BYO SIP credential references with redaction.
/webhook-endpointConfigure account-wide, assistant, phone-number, or tool webhook targets.
/fileStore file resources and expose content for tools or knowledge workflows.
/structured-outputDefine schema-backed post-call or on-demand structured extraction jobs.

Calls

A call owns the real-time session: media ingress, STT events, assistant turns, tools, TTS, recordings, logs, costs, and final report data.

POST/callCreate a call using assistant, transport, customer, phone, or web fields.
POST/call/phonePhone-specific create route for outbound telephony flows.
POST/call/webCreate a web call without a phone number or customer phone field.
POST/call/:id/controlSay, add message, end call, transfer, handoff, DTMF, or custom controls.
GET/call/:id/timelineSupport timeline merging logs, messages, webhooks, transcript summary, and artifacts.
GET/call/:id/costsProvider cost breakdown based on the configured rate card.
GET/call/:id/recordingMono recording artifact when recording is enabled.
GET/call/:id/recording/stereoStereo artifact when the stereo recording pipeline is enabled.
GET/call/:id/pcapSIP/RTP packet capture artifact when enabled for diagnostics.

Logs and observability

GET/logsUnified log stream.
GET/logs/callsCall event logs.
GET/logs/webhooksWebhook jobs and attempts with status, latency, and retry metadata.
POST/logs/webhooks/:id/replayReplay a stored attempt against the current target configuration.
POST/logs/webhooks/jobs/:id/retryRequeue a failed or skipped durable webhook job.
GET/analytics/summaryRuntime analytics summary when analytics storage is configured.
GET/sloCurrent SLO snapshot for voice pipeline, API, webhook success, and audio warnings.

Runtime activation

The installer uses a short-lived install token for the first activation. After that, the runtime can check in with its own instance key so the cockpit receives real heartbeat metadata, redacted inventory, and license lease renewals.

POST/v1/runtime/check-inCreate or update a runtime deployment heartbeat for the control plane.
POST/v1/runtime/inventorySync redacted runtime resources without prompts, transcripts, phone numbers, secrets, or call logs.
POST/v1/runtime/license/renewIssue a short-lived signed license lease for an activated runtime slot.
Runtime check-in 
{
  "installToken": "aywa_install_...",
  "instanceKey": "generated-on-the-runtime-host",
  "name": "private-beta-vps",
  "runtimeVersion": "0.1.0",
  "agentVersion": "0.1.0",
  "dashboardUrl": "https://runtime.customer.example.com",
  "apiUrl": "https://api.runtime.customer.example.com",
  "region": "eu-west",
  "accessMode": "public_https",
  "status": "healthy",
  "capabilities": {
    "phoneCalls": true,
    "webCalls": true,
    "toolCalls": true
  },
  "healthSummary": {
    "medianTurnMs": 482
  },
  "licenseState": "active",
  "syncCursor": "2026-06-23T18:00:00.000Z",
  "lastAppliedRevision": "rel_2026_06_23",
  "generatedAt": "2026-06-23T18:00:00.000Z"
}
Redacted inventory sync 
{
  "instanceKey": "generated-on-the-runtime-host",
  "syncCursor": "2026-06-23T18:05:00.000Z",
  "resources": [
    {
      "kind": "assistant",
      "localResourceId": "assistant_local_01",
      "displayName": "Support voice agent",
      "version": "2026-06-23",
      "revision": "rev_42",
      "checksum": "sha256:...",
      "manifestRedacted": true,
      "metadata": {
        "language": "en",
        "channel": "phone"
      }
    }
  ]
}
License lease renewal 
{
  "instanceKey": "generated-on-the-runtime-host",
  "runtimeVersion": "0.1.0",
  "agentVersion": "0.1.0",
  "nonce": "renewal-attempt-uuid"
}

Runtime sync rejects sensitive keys such as prompts, transcripts, recordings, phone numbers, provider credentials, routing rules, raw logs, and tool payloads. Registry tokens are issued through a separate endpoint and are not included in license renewals.

List filters

List endpoints support date and limit filters for migration tooling and dashboard pagination.

Query params 
?limit=50
?createdAtGt=2026-05-01T00:00:00.000Z
?createdAtLt=2026-06-01T00:00:00.000Z
?updatedAtGe=2026-05-15T00:00:00.000Z
?updatedAtLe=2026-05-31T23:59:59.999Z

Organization-scoped runtime APIs

Runtime APIs can be scoped to a runtime-local organization with X-Organization-Id or the SDK organizationId option. This value is not the app.aywaruntime.com workspace id. It is the organization id generated by the deployed runtime when a local client, brand, department, or SaaS customer workspace is created.

Default path: single-organization deployments can omit the header. Multi-organization deployments should use the runtime-generated organization id returned by the dashboard or API. Do not invent this id in normal product flows; manual ids are reserved for migration and import tooling.
Organization-scoped request 
curl "$RUNTIME_URL/assistant" \
  -H "Authorization: Bearer $RUNTIME_API_KEY" \
  -H "X-Organization-Id: $AYWA_RUNTIME_ORGANIZATION_ID"

FreeSWITCH and media hooks

FreeSWITCH remains a telephony edge. The runtime accepts inbound calls, lifecycle events, and audio hooks so media enters the same STT, recording, live listen, and runtime log path.

POST/freeswitch/inboundCreate an inbound call from a routed DID or SIP URI.
POST/freeswitch/eventsMap progress, answer, and hangup events into call status updates.
POST/freeswitch/audioPush audio chunks into the runtime audio pipeline.
POST/internal/calls/:id/audioInternal media bridge audio ingress.