Skip to main content
Audact
See the offer
All guides
On this page

TypeScript SDK

Official TypeScript SDK for Audact. A thin, dependency-free wrapper (Node ≥18 fetch/FormData/AbortSignal/URLSearchParams only) around Audact's HTTP services — Validator, Evidence Layer, LLM Proxy, Tenant Management, Voice Gateway, Agent Worker, Aggregator, Policy Engine, Audio Validator, and Org Management.

Install

bash

npm install @audactcore/sdk

Quick start

ts

import { AudactClient } from "@audactcore/sdk";

const client = new AudactClient({ apiKey: "aud_live_..." });

const result = await client.validator.validate({
  call_id: "a1b2c3d4-...",
  tenant_id: "t1t2t3...",
  config_id: "c1c2c3...",
  turn: 1,
  content: "Hello, I am an AI assistant.",
  context: {
    previous_turns: [],
    call_state: { disclosure_delivered: false },
  },
});

if (result.verdict === "ALLOW") {
  console.log("Content approved:", result.content);
}

Base URL

In production every service sits behind one public host, path-routed under /v1. Pass it once:

ts

const client = new AudactClient({ apiKey: "aud_live_...", baseUrl: "https://api.audact.ai" });

A trailing / or /v1 on baseUrl is stripped; requests go to https://api.audact.ai/v1/.... serviceUrls (per-service overrides, which win over baseUrl) are only needed for custom deployments.

Coverage

The SDK is at full parity with the documented API: 209 of 211 operations are covered (the remaining 2 are receive-side provider-to-platform webhooks — POST /telnyx/webhook and POST /webhooks/livekit — which are ingress endpoints Audact receives, never calls).

Sub-clientServiceAuthWhat it covers
client.validatorValidatorAPI keyPer-turn ACVF validation, finalize call score
client.evidenceEvidence LayerAPI keyEvidence events, chains, verify/reconstruct, calls, violations, Article 50 reports/exports, C2PA, receipts, delivery, transcript reconciliation
client.llmProxyLLM ProxyAPI keyCompliance-validated LLM chat completion (sync + streaming)
client.tenantsTenant ManagementAPI keyTenant CRUD, usage, API keys, configurations
client.numbersVoice GatewayAPI keyKYC documents/sets, number provisioning lifecycle (order, assign, suspend, resume, release, trunk)
client.callsVoice GatewayAPI keySIP call lifecycle (outbound/inbound/browser, hangup, status, handover, transfer), trunks, dispatch rules, admission URL, WS tickets
client.webhooksTenant ManagementAPI keyWebhook endpoint CRUD, test-ping, delivery history/resend, event-type/schema discovery, secret status/rotation
client.agentsAgent WorkerAPI keyAgent CRUD + duplicate, TTS voice catalog CRUD, pipeline status
client.toolsAgent WorkerAPI keyFunction-calling tool CRUD/test, agent-tool attach/detach
client.integrationsAgent WorkerAPI keyCal.com connection CRUD, health check, event-type discovery
client.knowledgeBasesTenant ManagementAPI keyKnowledge-base (RAG) CRUD, sources (url/text JSON + multipart file upload, reingest), agent links with retrieval tuning, crawl exclusions, retrieval test harness
client.aggregationAggregatorAPI key (public: getMetachain, verifyInclusion)Merkle aggregation proofs, public meta-chain, offline inclusion verification
client.policyPolicy EngineAPI keyPolicy evaluation, jurisdiction policy documents, calling-hours pre-check
client.audioAudio ValidatorAPI keySynchronous per-turn audio validation, post-call audio-to-transcript reconciliation
client.authTenant ManagementAPI keyAPI-key ↔ JWT session bridge (exchange, refresh)
client.orgOrg ManagementOrgBearer (JWT)Org self-service: signup/login/refresh/logout, profile, KYC
client.org (tenants)Org ManagementOrgBearer (JWT)Org-owned tenant lifecycle: list/create/get, soft-delete/enable/disable/restore, initialize, issue key, impersonate
client.piiEvidence LayerAPI keyPII vault shred by identity (shred, shredCall), call identities (listCallIdentities, linkCallIdentity), decrypt vault tokens (decrypt), erased-keyset status (listErasedKeysets), encryption settings (settings)

Added in 0.3.0

MethodRoute
client.pii.listErasedKeysets(callId, keysetIds)GET /v1/calls/{call_id}/pii/erased-keysets
client.evidence.listComplianceEvents(opts?)GET /v1/compliance/events

Error handling

Failed requests throw AudactError, populated from the API's {"error": {...}} envelope:

ts

import { AudactError } from "@audactcore/sdk";

try {
  await client.evidence.getCallDetail("missing");
} catch (err) {
  if (err instanceof AudactError) {
    console.error(err.status, err.code, err.message);
    console.error("request id:", err.requestId); // quote this to support
    if (err.hint) console.error("hint:", err.hint);
    if (err.status === 429) console.error("retry in", err.retryAfter, "s");
  }
}

hint, details and retryAfter may be undefined.

Auth flows

Most sub-clients send Authorization: Bearer <apiKey> using the apiKey passed to the AudactClient constructor. Two surfaces use a different bearer token (org and platform), set via setAuthToken() (or supplied up front in AudactClientOptions):

  • OrgBearer — a JWT obtained from client.org.login(). The SDK stores it on the org sub-client automatically; every subsequent client.org.* call (including the tenant-lifecycle methods) sends it instead of the API key.

Org login flow

ts

import { AudactClient } from "@audactcore/sdk";

const client = new AudactClient({ apiKey: "aud_live_..." });

// login() is public (no bearer required) and stores the returned access
// token on client.org automatically.
await client.org.login({ email: "admin@example.com", password: "hunter2" });

// Subsequent calls send `Authorization: Bearer <jwt>`.
const profile = await client.org.getProfile();
const tenants = await client.org.listTenants();

// Rotate the token before it expires, then clear it when done.
await client.org.refresh();
await client.org.logout();

Alternatively, start pre-authenticated:

ts

const client = new AudactClient({
  apiKey: "aud_live_...",
  orgToken: "<jwt from a prior login>",
});

A new client: webhooks

ts

const endpoint = await client.webhooks.createWebhook({
  url: "https://example.com/hooks/audact",
  events: ["call_ended", "compliance.violation_detected"],
  scope: "account",
});

await client.webhooks.testWebhook(endpoint.id);

const deliveries = await client.webhooks.listWebhookDeliveries(endpoint.id);

Development

bash

npm install
npx tsc --noEmit   # typecheck
npm run build      # emit dist/esm + dist/cjs
npm run test       # vitest

Source updated: October 19, 2026