Backend API Reference — Kaltura Agentic Avatars

Every endpoint, the full agent lifecycle, and a verified use-case catalog, copy-paste ready. This page is the index. The reference itself lives in focused files under docs/api/.

New here? Start with Getting Started. Runtime details live in Platform Overview. The zero-dependency SDK is in README.md.

Credentials. All examples need a partner ID and an admin secret (Rich Media CMS → Settings → Integration Settings). The examples read them from AGENTIC_PARTNER_ID and AGENTIC_ADMIN_SECRET in the environment. The SDK itself never reads a .env file. Setup steps: Getting Started. Never hardcode the secret.

Every endpoint is shown as a raw HTTP call plus its SDK wrapper. See README.md for the full Management method list.

Contents

What can you build? A few examples:

• A concierge with memory (UC-2/UC-3)
• A GenUI-driven product demo (UC-4)
• A slide-deck walkthrough avatar (UC-10)
• A self-serve custom-voice/custom-portrait agent (UC-9/UC-13)
• An anonymous embeddable widget (UC-12)
• A fleet of A/B-tested personas (UC-5)

See the full Use-Case Catalog for all 13, each mapped to its key mechanism and a runnable script/tool.

Common Errors

The SDK wraps every error into a KalturaError with a stable err.code. Branch on that, not on message text or the raw response body.

A KalturaAvatarSession (and KalturaAgentSession while in avatar mode) adds two fields to its errors. err.phase names the connect step that failed. err.retryable says whether trying again can succeed. See connect timeouts.

A missing agent or intellect gets its own err.code, whatever the HTTP status:

Response headers (debugging and log search)

The SDK keeps the tracing headers of every response: x-* (minus browser-hardening ones), via, server, age, retry-after, traceparent, tracestate. Names are lowercase. Values are redacted. Headers whose name suggests a credential (token, key, secret, auth, cookie, ks) and client-IP headers are dropped.

const mgmt = new Management({
  partnerId, adminSecret,
  onResponse: ({ method, path, status, attempt, requestId, headers }) =>
    log.info({ method, path, status, attempt, requestId, headers }),
});

try { await mgmt.agents.get(agentId, ks); }
catch (err) { log.error({ code: err.code, requestId: err.requestId, headers: err.headers }); }

onResponse fires once per attempt, so a retried call shows every try. A hook that throws is ignored. requestId is the server's id when it sends one, else an id the SDK makes up (empty on streamed converse calls). Quote the header ids, not a made-up requestId, when you ask Kaltura support to trace a call.

In a browser, fetch only exposes the headers the server lists in Access-Control-Expose-Headers, so headers may be sparse there.

Base URL config errors are thrown before any request:

Quick Reference

import { Management } from '@kaltura/intelligent-agents/management';
const mgmt = new Management({ partnerId, adminSecret });
const ks = await mgmt.sessions.createAdminToken({ userId: 'admin@example.com' });

console.log(await mgmt.agents.list(ks).all());
console.log(await mgmt.intellects.list(ks).all());