# 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/`](https://github.com/kaltura/intelligent-agents-sdk/blob/main/docs/api/).

**New here?** Start with [Getting Started](https://kaltura.github.io/intelligent-agents-sdk/getting-started/index.md). Runtime details live in [Platform Overview](https://kaltura.github.io/intelligent-agents-sdk/explanation/architecture/index.md). The zero-dependency SDK is in [`README.md`](https://github.com/kaltura/intelligent-agents-sdk/blob/main/README.md).

**Credentials.** All examples need a partner ID and an admin secret ([Rich Media CMS → Settings → Integration Settings](https://kmc.kaltura.com/index.php/kmcng/settings/integrationSettings)). 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](https://kaltura.github.io/intelligent-agents-sdk/getting-started/index.md#step-1-get-your-credentials-1-minute). Never hardcode the secret.

Every endpoint is shown as a raw HTTP call plus its SDK wrapper. See [`README.md`](https://github.com/kaltura/intelligent-agents-sdk/blob/main/README.md) for the full `Management` method list.

---

## Contents

| File | Covers |
|------|--------|
| [Authentication & Services](https://kaltura.github.io/intelligent-agents-sdk/reference/api/authentication/index.md) | KS types and minting (`agentId`, `userId`, `sessionType`), `userId` binding, the five services and their base URLs, regions (`region`, `REGIONS`) |
| [Catalog & Assets](https://kaltura.github.io/intelligent-agents-sdk/reference/api/design/index.md) | Browse the catalog, custom voice (clone), provider voice import, custom visual (portrait, photo spec), custom face/background, end-to-end portrait recipe |
| [Agent Components](https://kaltura.github.io/intelligent-agents-sdk/reference/api/build/index.md) | Generate an agent profile, create/configure an intellect, preview a prompt, tools (`api`/`csv`/`code`/`client`/`var`), secrets, ground in your content (RAG), create an avatar, create an agent |
| [Widget & Runtime Init](https://kaltura.github.io/intelligent-agents-sdk/reference/api/deploy/index.md) | Resolve widget ID, initialize the browser runtime |
| [Conversation & Analytics](https://kaltura.github.io/intelligent-agents-sdk/reference/api/operate/index.md) | Converse (headless HTTP), reserved `sys__*` template variables, status, threads, feedback and follow-ups, usage analytics, knowledge search (MCP) |
| [Scripted-Video (STV-only) Sessions](https://github.com/kaltura/intelligent-agents-sdk/blob/main/docs/api/scripted-video.md) | Deprecated. Pre-authored speech sessions: auth, lifecycle, `say-audio` |
| [Management Operations](https://kaltura.github.io/intelligent-agents-sdk/reference/api/management-operations/index.md) | CRUD tables for agents, avatars, intellects, tools, skills, threads, messages/feedback/followups, knowledge records, lifecycle |
| [Lifecycle Rules](https://kaltura.github.io/intelligent-agents-sdk/reference/lifecycle/index.md) | Event-driven rules + InsightSettings (reusable custom-insight definitions) + EmailTemplates (`sendInsightEmail`'s `templateId`). Reference and [recipe](https://kaltura.github.io/intelligent-agents-sdk/guides/lifecycle-recipes/index.md) |
| [External API Integrations](https://kaltura.github.io/intelligent-agents-sdk/guides/external-api-integrations/index.md) | Wiring an agent-called tool to a durable write against your own external API (CRM, spreadsheet, ticketing), including the managed OAuth2 flow |
| [MCP Integrations](https://kaltura.github.io/intelligent-agents-sdk/guides/mcp-integrations/index.md) | Wiring a whole [MCP](https://modelcontextprotocol.io) server's tool surface at once: auth, multi-server namespacing, OAuth-gated servers |
| [Use-Case Catalog](https://kaltura.github.io/intelligent-agents-sdk/reference/use-cases/index.md) | All 14 use cases (UC-1 through UC-14) mapped to mechanisms and runnable scripts |
| [Site navigation](https://kaltura.github.io/intelligent-agents-sdk/guides/site-navigation/index.md) | Fire-and-forget `go_to` tool, compact SITE MAP prompt, `sections.json` manifest, browser `SiteNavigator` plugin |

---

**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](https://kaltura.github.io/intelligent-agents-sdk/reference/use-cases/index.md) 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.

| Status or error number | `err.code` | Fix |
|--------|-----|-----|
| 400 | `bad_request` | Fix the request body |
| 402 | `payment_required` | The server refused the request as Payment Required, which points to a plan or entitlement limit. Check the plan with your Kaltura contact. The SDK never retries it, and `err.retryable` is `false`. A temporary load limit is not a 402: a live conversation reports it as the retryable `capacity_unavailable`. |
| 403 | `forbidden` | Wrong KS type: admin KS for management, `geniegpcid` for conversations. Also: a user session without `userId` on thread get, list or delete. A user session asking for another user's thread gets 404 instead. See [Security & Compliance § Session type](https://kaltura.github.io/intelligent-agents-sdk/reference/security/index.md#session-type) |
| 405 | `method_not_allowed` | Use `GET` for `/assistant/status`; everything else is `POST` |
| 6001 | `capacity_unavailable` | No free avatar slot. Retry later or call `waitForCapacity()`. See [Capacity & the queue](https://kaltura.github.io/intelligent-agents-sdk/reference/architecture-reference/scale-and-sticky-sessions/index.md#capacity--the-queue-throwtonoagent--throwtoexceededtier) |
| 6002 | `tier_exceeded` | The account plan limit is reached. Not retryable. See [Capacity & the queue](https://kaltura.github.io/intelligent-agents-sdk/reference/architecture-reference/scale-and-sticky-sessions/index.md#capacity--the-queue-throwtonoagent--throwtoexceededtier) |
| none | `ice_failed` | The avatar media path never connected. `err.ice` says why. Retryable. See [ICE diagnostics](https://kaltura.github.io/intelligent-agents-sdk/reference/architecture-reference/resilience-and-failure-handling/index.md#ice-diagnostics) |
| none | `capacity_timeout` | `waitForCapacity()` found no free slot in time. See [Capacity & the queue](https://kaltura.github.io/intelligent-agents-sdk/reference/architecture-reference/scale-and-sticky-sessions/index.md#capacity--the-queue-throwtonoagent--throwtoexceededtier) |

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](https://kaltura.github.io/intelligent-agents-sdk/reference/architecture-reference/connection-and-handshake/index.md#full-connect-sequence-state-machine-order).

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

| Situation | `err.code` | Fix |
|---|-----|-----|
| The agent does not exist | `agent_not_found` | Check the `agentId` |
| The agent has no intellect | `intellect_not_found` | Create the intellect first |

### 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.

| Where | How |
|---|---|
| A failed call | `err.headers` (also in `err.toJSON()`). `undefined` when the response had none. |
| Every `Management` HTTP response, success or failure | `onResponse` hook on `new Management({ onResponse })`. |
| Every converse response | `onResponse` hook on `new KalturaChatSession({ onResponse })`. Tool-result posts are not reported. |
| Debug log | The `logger` receives a `⋯ <status> <path> headers` line. |

```js
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:

| `err.code` | Fix |
|---|-----|
| `region_unavailable` | The `region` does not offer that service. Pass its URL explicitly. See [Regions and base URLs](https://kaltura.github.io/intelligent-agents-sdk/reference/api/authentication/index.md#regions-and-base-urls) |
| `insecure_transport` | Use an `https://` base URL |

---

## Quick Reference

<div data-nova-target="api-reference-quickref" data-nova-label="Quick Reference example">

The full `Management` method surface (this doc's endpoints, wrapped) is listed in [`README.md`](https://github.com/kaltura/intelligent-agents-sdk/blob/main/README.md) → Management. Two common lookups:

```js
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());
```

</div>