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, next to filter, not inside it. -createdAt and -updatedAt sort newest first. +createdAt is ignored. +updatedAt cannot be told apart from no orderBy. Any other value returns bad_request (400), and the error lists the four accepted values. Threads and Messages below take orderBy inside filter. SDK: mgmt.agents.list(ks, { filter, orderBy }) sends both as-is.

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

filter.nameLike on intellects, tools and skills matches the whole name, case-insensitive. Add % for a partial match, for example '%support%'. On knowledge records it is a partial match without %.

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:false runs without waiting; every other thread-start tool is waited for. The result is not given to the model. 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. A template the server rejects returns 400 bad_request. 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, condition?}. condition is a bare condition expression, checked before the call. A template form like {{ x }} throws bad_request. SDK: mgmt.skills. A name that is already in use returns 409. Tools above follow the same rule.

Variables in skills. The instructions of a skill render {{ variable }} placeholders and template tags, like prompt blocks, in every mode ('adhoc', 'adhoc-save' and 'preloaded'). A literal {{ or {% in instructions is read as template syntax, so avoid it in plain text.

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, agentIdIn, contextIdEqual, createdAtGreaterThanOrEqual, createdAtLessThanOrEqual, idEquals, idsIn, isEverywhere, orderBy, originEquals, originIn, partnerIdEquals, statusEquals, statusIn, updatedAtGreaterThanOrEqual, updatedAtLessThanOrEqual, userIdEquals. Origin values: Conversation & Analytics § Threads.

Rules to know:

• Put orderBy inside filter (one of +createdAt, -createdAt, +updatedAt, -updatedAt).
• Send statusEquals/statusIn as numbers, 0 or 1. statusEquals: 1 returns deleted threads, which the default list omits (Conversation & Analytics § Threads).
• 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).

SDK: mgmt.threads.list(ks, opts) merges opts.filter under the fixed objectType, so it can't be overridden. agentIdEquals filters by one agent, agentIdIn by several.

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

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

Message record (messages.list, messages.get): id, thread_id, genie_id, user_id, partner_id, created_at, updated_at, human (the user text), assistant (a list of typed parts), type, is_positive, comment. type marks the kind of message, for example 0 for a normal turn and 4 for a message added with threads.push.

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 at least one message query per matching thread, and more for threads with many messages. 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. Only filter.orderBy sorts. Without it the order of messages is not defined, so do not rely on it.

threads.list and messages.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.