Management Operations

← Back to the API Reference index

All use the admin KS.

Agents — https://api.avatar.us.kaltura.ai

Filter keys: agentId, adminTagsIn, adminTagsNotIn, searchValue (case-insensitive substring match on displayName/agentId). An unrecognized key 400s.

The request also takes a top-level orderBy (+createdAt, -createdAt, +updatedAt, -updatedAt; anything else 400s) — a separate field from filter. This differs from Threads/Messages below, where orderBy nests inside filter. SDK: mgmt.agents.list(ks, opts) passes opts.filter through as-is and does not take orderBy.

mgmt.agents.delete refuses to delete an agent whose adminTags match a production marker (prod, production, keep, do-not-delete, live — see PROTECTED_TAGS in src/management/agents.js). It only proceeds when called with {confirmPermanent:true, allowProtected:true}. This guards against an automated cleanup-by-tag sweep deleting a real, in-use agent.

Avatars — https://api.avatar.us.kaltura.ai

Recomposing on update is asymmetric, unlike create (where face/background must travel together). The rule depends on the avatar's existing state:

• background alone recomposes against the avatar's current face — a valid "just change the background" update.
• face alone is accepted but silently a no-op: there's nothing to pair it with, so the existing visual is left untouched.

avatars.update does NOT reject either half alone.

avatar/create accepts and stores adminTags, and avatar/list adminTagsIn finds it. But no read path ever returns it, and avatar/update genuinely rejects it (no tag field on that request body). The SDK throws pre-network on either path rather than let you rely on a write-only field — tag the parent agent instead.

Intellects — https://genie.nvp1.ovp.kaltura.com

Create (POST /v1/intellect/add) isn't listed here. See Agent Components · Create and Configure an Intellect for creating an intellect with the SDK's default-applying mgmt.intellects.create().

Deleting an agent does not delete its avatar or intellect.

mgmt.setForcedLanguage({ configId, agentId, language, languageName?, asrProvider? }, ks) forces the reply language. It sets force_language on the intellect (the backend enforces it at runtime) and the agent's asr.language/asr.provider in one call. languageName is required only for a language code not in the SDK's built-in LANGUAGE_NAMES map; asrProvider defaults to 'kaltura'. Idempotent; language: null clears both (resets asr.language to 'en'). See README § Forcing the reply language.

Typed setters on mgmt.intellectConfig for the other single-purpose fields, all (configId, value, ks) and idempotent:

Each validates client-side and throws bad_request before any network call. See Agent Components · Create and Configure an Intellect for field semantics.

[^1]: Only api and code tools run at thread start; other tool types have no effect there. An api tool with wait_for_response is awaited; every other tool is fire-and-forget, and a failing tool does not fail the conversation. It never appears as a tool segment in the stream.

[^2]: null restores the defaults (analysis: { summary }, template: '{{ summary }}', content_type: 'text'). Every {{ key }} in template must be an analysis key (or summary when analysis is unset). The SDK rejects a mismatch client-side. The summary is skipped entirely when the thread has no human messages.

Tools — https://genie.nvp1.ovp.kaltura.com

A standalone, partner-level entity, not embedded in an intellect. A name that doesn't appear in your own list() can still be rejected with a 409 conflict, because names are also checked against a shared pool. The same applies to Skills below.

mgmt.tools.delete refuses by default with a typed tool_in_use error naming every intellect still listing the id in tool_ids. Pass {confirmPermanent:true, force:true} to delete anyway. Drop the id from each intellect's tool_ids first via mgmt.intellectConfig.setToolIds.

Skills — https://genie.nvp1.ovp.kaltura.com

A standalone, partner-level reusable-instruction entity — {id (uuid), name, description, instructions}. SDK: mgmt.skills. A name that doesn't appear in your own list() can still be rejected with a 409 conflict, because names are also checked against a shared pool. The same applies to Tools above.

Before deleting a Skill, mgmt.skills.delete lists every intellect and refuses with a typed skill_in_use error naming each one still referencing the id in skill_ids. It only proceeds when called with {confirmPermanent:true, force:true}. Tools' mgmt.tools.delete carries the identical tool_in_use guard.

Threads — https://genie.nvp1.ovp.kaltura.com

All thread endpoints require an admin KS (disableentitlement). SDK: mgmt.threads.{list, get, rename, setAnalysis, clearAnalysis, push, delete, transcript}.

Filter fields (list): agentIdEquals, contextIdEqual, createdAtGreaterThanOrEqual, createdAtLessThanOrEqual, idEquals, idsIn, isEverywhere, orderBy, partnerIdEquals, statusEquals, statusIn, updatedAtGreaterThanOrEqual, updatedAtLessThanOrEqual, userIdEquals.

Rules to know:

• orderBy goes INSIDE filter (one of +createdAt, -createdAt, +updatedAt, -updatedAt). A top-level orderBy 422s.
• statusEquals/statusIn take 0/1. A numeric string ("0") is silently coerced and accepted, but a non-numeric string 422s.
• An unknown filter key 422s. partnerIdIn always 422s.
• Pager is {pageIndex, pageSize} (1-based) — {offset, limit} is ignored and returns the default page of 30.
• pageSize is capped server-side at 500; a higher value 422s. This applies to every Genie-backed list/report pager in this section (Threads, Messages, Feedback, Followups).

SDK: mgmt.threads.list(ks, opts) merges opts.filter under the fixed objectType, so it can't be overridden. It translates agentIdEquals to the server's own agent-scoping filter key on the wire. There's no server-side "in" equivalent for it: agentIdIn throws a validation_error before any network call rather than being silently dropped.

request_vars on push is validated by the SDK's own reserved-name guard before any network call, identically to converse — see Conversation & Analytics § Reserved Template Variables.

See Conversation & Analytics § Threads for response shapes and the compliance note on delete's soft-delete/purge timing.

Messages, Feedback & Followups — https://genie.nvp1.ovp.kaltura.com

SDK: mgmt.messages, mgmt.feedback, mgmt.followups.

List feedback in depth. mgmt.feedback.list(ks, opts) is the correct, permanent way to read feedback, not a stopgap. It queries POST /message/list (and, for filter.agentIdEquals, POST /v1/thread/list first) and returns only the messages carrying a rating.

Filter: messageIdEquals, messageIdsIn, threadIdEquals, agentIdEquals, isPositiveEquals. agentIdEquals only matches threads opened via sessions.createAgentToken, and costs one thread query per matching thread. With none of messageIdEquals/messageIdsIn/threadIdEquals/agentIdEquals set, it walks every message for the partner — scope it.

Unlike every other list() in this SDK, awaiting feedback.list(...) collects every matching row across all underlying pages, not just the first page. The rows are filtered client-side, so there's no single-page shortcut. A narrow filter matters more here than elsewhere.

Row shape: {message_id, thread_id, genie_id, user_id, is_positive, comment, created_at, updated_at}. ⚠️ SENSITIVE: comments are end-user-entered text.

Messages filter fields: createdAtGreaterThanOrEqual, createdAtLessThanOrEqual, genieIdEquals, idEquals, idsIn, isPositiveEquals, isPositiveIn, orderBy, threadIdEquals, updatedAtGreaterThanOrEqual, updatedAtLessThanOrEqual, userIdEquals. Unlike Threads, an unknown key here is silently ignored (200), not rejected. Only filter.orderBy sorts — a top-level orderBy is accepted but has no effect.

threads.list/messages.list/followups.list merge opts.filter under a fixed, mandatory objectType the caller can't override. feedback.list has its own filter shape (above), not that pattern.

Knowledge records — https://genie.nvp1.ovp.kaltura.com

Full record lifecycle. SDK: mgmt.knowledge. Linkage to an intellect is via knowledge_ids — see § Ground the Agent.

mgmt.knowledge.isIndexed(id, ks) wraps Get and reads status/config.sources[].indexers[].index_position. status is the record's own container-lifecycle flag, not an indexing-completion signal: see Agent Components · Ground the Agent in Your Content (RAG) § Ground the Agent for why, and for the real indexing-completion check.

mgmt.knowledge.addSource(id, source, ks) / removeSource(id, source, ks) read-merge-write one source into/out of config.sources without disturbing the others. Both skip the write (applied:false) when an identical source object is already present / already absent. Not safe to call concurrently for the same record id: two overlapping calls read the same pre-write config.sources, so the second write silently drops the first's change.

Before deleting a record, mgmt.knowledge.deleteRecord lists every intellect and refuses with a typed knowledge_in_use error naming each one still carrying the id in knowledge_ids. It only proceeds when called with {confirmPermanent:true, force:true} — the same guard mgmt.tools.delete/mgmt.skills.delete run for their own entities.

Lifecycle — https://api.avatar.us.kaltura.ai

An event-driven rule engine, not embedded in an intellect. SDK: mgmt.lifecycle. Full reference (rule shape, all 4 action types, CRUD + discovery methods) and a worked recipe: Lifecycle Rules.

Insight Settings — https://api.avatar.us.kaltura.ai

Reusable custom-insight definitions (key/title/prompt/valueType), referenced by id from a lifecycle rule's triggerInsightSettingsKai action — not embedded in an intellect. SDK: mgmt.insightSettings. See Lifecycle Rules.

Full reference and a worked recipe: Lifecycle Rules § InsightSettings.