Management Operations

← Back to the API Reference index

Endpoint and request reference for every Management operation: agents, avatars, intellects, tools, skills, threads, messages, knowledge, lifecycle and insight settings.

All operations use the admin KS (createAdminToken), except where a section says otherwise. Agents, Avatars, Lifecycle and Insight Settings call the management host (https://api.avatar.us.kaltura.ai). Everything else calls the conversation host (https://genie.nvp1.ovp.kaltura.com). Hosts for other regions: Regions and base URLs.

Agents

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). It sits next to filter, not inside it. Threads and Messages below take orderBy 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; the exported PROTECTED_TAGS). Pass {confirmPermanent:true, allowProtected:true} to delete it anyway. This stops a cleanup-by-tag sweep from deleting an agent that is in use. The SDK reads the agent first. If that read fails (other than the agent not existing), the delete is refused with that error. {skipProtectedCheck:true} skips the read and the guard.

Avatars

Changing the look on update. On create, face and background travel together. On update:

• To change the background, send background alone. It applies to the avatar's current face.
• To change the face, send face and background together.

Avatars carry no adminTags. avatars.create and avatars.update throw bad_request before any network call if you pass it. Tag the parent agent instead.

Intellects

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 and the speech-recognition language in one idempotent call. Usage and options: Languages.

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]: Use api and code tools here. An api tool with wait_for_response is awaited. Every other tool runs without waiting. A failing tool does not fail the conversation. A thread-start tool 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

A standalone, partner-level entity, not embedded in an intellect. A name that is already in use returns 409. Skills below follow the same rule.

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

A standalone, partner-level reusable-instruction entity: {id (uuid), name, description, instructions}. SDK: mgmt.skills. A name that is already in use returns 409. Tools above follow the same rule.

Shared skills. A shared skill (partner_id: 0) appears in skills.list and can be attached with setSkillIds. skills.get, skills.update and skills.delete answer 404 not_found for it, so you cannot read, edit or delete it. setSkillIds rejects a skill id that does not exist or that you cannot use with 403 forbidden. intellectConfig.audit and doctor accept an attached shared skill.

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. Pass {confirmPermanent:true, force:true} to delete anyway. mgmt.tools.delete has the same guard with a tool_in_use error.

Threads

Token rules per method: Conversation & Analytics § Threads. threads.push needs an admin token. Which threads a token can reach: Security & Compliance § Session type. 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:

• Put orderBy inside filter (one of +createdAt, -createdAt, +updatedAt, -updatedAt).
• Send statusEquals/statusIn as numbers, 0 or 1.
• Use only the filter fields listed above. partnerIdIn is not supported.
• Pager is {pageIndex, pageSize} (1-based). Use pageIndex/pageSize, not {offset, limit}.
• pageSize is at most 500. This applies to every list and 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. agentIdEquals filters threads by agent. There is no "in" form: agentIdIn throws a validation_error before any network call.

request_vars on push goes through the same reserved-name check as converse, before any network call. See Conversation & Analytics § Reserved Template Variables.

See Conversation & Analytics § Threads for response shapes and delete behavior.

Messages, Feedback & Followups

SDK: mgmt.messages, mgmt.feedback, mgmt.followups. messages.list, get and share accept an admin, conversation or agent token (see Conversation & Analytics § Threads). messages.report, messages.reportSummary, feedback.list and followups.list need an admin token.

List feedback in depth. mgmt.feedback.list(ks, opts) reads feedback. It queries POST /message/list (and, for filter.agentIdEquals, POST /v1/thread/list first) and returns only the messages that carry a rating.

Filter: messageIdEquals, messageIdsIn, threadIdEquals, agentIdEquals, isPositiveEquals. agentIdEquals matches only threads opened with a token minted with that agentId (createAgentToken, or createConversationToken with agentId). It costs one thread query per matching thread. Set at least one of messageIdEquals, messageIdsIn, threadIdEquals or agentIdEquals. With none set, it reads every message for the partner.

Unlike every other list() in this SDK, awaiting feedback.list(...) collects every matching row across all underlying pages, not just the first page. Use a narrow filter.

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. Send only the keys listed. Sort with filter.orderBy.

threads.list, messages.list and followups.list merge opts.filter under a fixed objectType that you cannot override. feedback.list has its own filter shape (above).

Knowledge records

Full record lifecycle. SDK: mgmt.knowledge. An intellect links to a record through knowledge_ids. See Agent Components · Ground the Agent in Your Content (RAG) § Ground the Agent.

mgmt.knowledge.isIndexed(id, ks) wraps Get and reads status/config.sources[].indexers[].index_position. status does not tell you that indexing is complete. For the completion check, see Agent Components · Ground the Agent in Your Content (RAG) § Ground the Agent.

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. Call them one at a time for the same record id. Two overlapping calls can lose one of the changes.

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. Pass {confirmPermanent:true, force:true} to delete anyway. mgmt.tools.delete and mgmt.skills.delete use the same guard.

Lifecycle

An event-driven rule engine, not embedded in an intellect. SDK: mgmt.lifecycle. Full reference (rule shape, action types, CRUD + discovery methods) and a worked recipe: Lifecycle Rules. To check existing rules, and a partner's agents and intellects, for mistakes, use mgmt.lifecycle.audit, mgmt.intellectConfig.audit and mgmt.doctor. They only read. See Audit your rules.

Insight Settings

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.