📚 Knowledge Service

A Knowledge record is a curated collection of content that the Intellect can search and reference when answering questions. Attach one to an intellect via knowledge_ids to give your assistant access to your media library, documents, or external web content.

Base route: POST /v1/knowledge/{action}

How Knowledge Relates to Intellect

📚 Knowledge record
   └── sources
       ├── Internal: Kaltura category IDs → indexed media entries
       └── Web: public URLs → crawled and indexed content
                    │
                    ▼ attached via knowledge_ids
             🧠 Intellect

A knowledge record defines where to get content. The intellect decides whether to use it (via the use_knowledge_base capability).

Data Model

Knowledge

Field	Type	Description
`id`	number	Server-assigned Knowledge record ID
`name`	string	Display name
`description`	string	Optional description
`status`	`'READY'` \| `'DELETED'`	Lifecycle status
`config`	object	Knowledge base configuration (see below)
`tags`	string[]	Searchable tags
`partner_id`	number	Kaltura partner ID
`user_id`	string	ID of the user who created this record
`created_at` / `updated_at`	string (ISO date)	Timestamps

KnowledgeConfig

Field	Type	Description
`sources`	object[]	One or more knowledge sources to index

Source Types

Internal source — indexes Kaltura media entries via categories:

Field	Type	Required	Description
`type`	`'internal'`	✅ Yes	Source type discriminator
`language`	string	✅ Yes	BCP-47 language code for captions/assets (e.g. `'en'`, `'fr'`)
`categoryIds`	string[]	✅ Yes	Kaltura category IDs whose entries will be indexed
`indexers`	object[]	✅ Yes	Indexing strategies to apply (see below)
`customOperator`	object	No	Optional Kaltura ESearch operator to further filter entries

Web source — indexes content from public URLs:

Field	Type	Required	Description
`type`	`'web'`	✅ Yes	Source type discriminator
`urls`	string[]	✅ Yes	Public URLs to crawl and index

Indexers (for internal sources)

Each indexer defines a strategy for embedding entry content:

Field	Type	Description
`type`	number	Content type: `1`=caption, `2`=OCR, `3`=document, `4`=summary, `5`=custom
`strategy`	string	Embedding strategy: `EmbedCaptionV1`, `EmbedOcrV1`, `EmbedDocumentV1`, `EmbedSummaryV1`
`index_position`	number	Cursor tracking the last successfully indexed entry

Actions

`add` — Create a Knowledge Record

POST /v1/knowledge/add

Creates a new knowledge record. After creating it, use upload to add content or reference existing Kaltura categories.

Request body:

{
  "name": "Product Video Library",
  "description": "Indexed Kaltura video entries for product documentation",
  "tags": ["production", "videos"],
  "config": {
    "sources": [
      {
        "type": "internal",
        "language": "en",
        "categoryIds": ["cat_abc123", "cat_def456"],
        "indexers": [
          {
            "type": 1,
            "strategy": "EmbedCaptionV1",
            "index_position": 0
          },
          {
            "type": 3,
            "strategy": "EmbedDocumentV1",
            "index_position": 0
          }
        ]
      }
    ]
  }
}

Field	Type	Required	Description
`name`	string	No	Display name
`description`	string	No	Free-text description
`tags`	string[]	No	Searchable tags
`config`	object	No	Knowledge base configuration

Response: Returns the created Knowledge object with generated id.

Examples:

cURL — create with internal Kaltura source
curl -X POST "https://YOUR_API_HOST/v1/knowledge/add" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Video Library",
    "config": {
      "sources": [
        {
          "type": "internal",
          "language": "en",
          "categoryIds": ["cat_abc123"],
          "indexers": [
            { "type": 1, "strategy": "EmbedCaptionV1", "index_position": 0 }
          ]
        }
      ]
    }
  }'

JavaScript — create with web source
const knowledge = await fetch('https://YOUR_API_HOST/v1/knowledge/add', {
  method: 'POST',
  headers: { Authorization: `KS ${ksToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Documentation Site',
    config: {
      sources: [
        {
          type: 'web',
          urls: ['https://docs.example.com/', 'https://docs.example.com/api/'],
        },
      ],
    },
  }),
}).then((res) => res.json());

console.log(`Created knowledge record: ${knowledge.id}`);

`get` — Retrieve a Knowledge Record

POST /v1/knowledge/get

Request body:

{ "id": 7 }

Field	Type	Required	Description
`id`	number	✅ Yes	The knowledge record ID to retrieve

Example:

cURL
curl -X POST "https://YOUR_API_HOST/v1/knowledge/get" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id": 7 }'

`update` — Update a Knowledge Record

POST /v1/knowledge/update

Update name, description, tags, or the full config. Only provided fields are changed.

Request body:

{
  "id": 7,
  "name": "Product Video Library (Updated)",
  "config": {
    "sources": [
      {
        "type": "internal",
        "language": "en",
        "categoryIds": ["cat_abc123", "cat_new789"],
        "indexers": [{ "type": 1, "strategy": "EmbedCaptionV1", "index_position": 0 }]
      }
    ]
  }
}

Field	Type	Required	Description
`id`	number	✅ Yes	The knowledge record to update
`name`	string	No	New display name
`description`	string	No	New description
`tags`	string[]	No	Replaces tag list
`config`	object	No	Replaces full knowledge config

`upload` — Upload Content to a Knowledge Record

POST /v1/knowledge/upload

Creates a Kaltura entry and upload token so you can ingest a file (video, audio, or document) into the knowledge base. The entry type is inferred from the file extension.

Request body:

{
  "id": 7,
  "name": "Q4 Product Demo",
  "file_name": "q4-demo.mp4",
  "category_id": "cat_abc123",
  "description": "Product demo video for Q4",
  "language": "English",
  "tags": ["demo", "q4"]
}

Field	Type	Required	Description
`id`	number	✅ Yes	Knowledge record ID to upload content to
`name`	string	✅ Yes	Display name for the Kaltura entry
`file_name`	string	✅ Yes	File name with extension (e.g. `lecture.mp4`, `notes.pdf`) — determines entry type
`category_id`	string	No	Kaltura category ID to assign the entry to. Defaults to the first configured category; creates one automatically if none exist
`description`	string	No	Optional description
`language`	string	No	Entry language (default: `'English'`)
`tags`	string[]	No	Tags for the Kaltura entry

Response:

{
  "upload_token_id": "0_abc123xyz",
  "entry_id": "1_def456ghi",
  "category_id": "cat_abc123"
}

Use the upload_token_id and entry_id with Kaltura's upload API to send the actual file.

Example:

JavaScript — get upload token then upload file
// Step 1: Get an upload token
const { upload_token_id, entry_id } = await fetch('https://YOUR_API_HOST/v1/knowledge/upload', {
  method: 'POST',
  headers: { Authorization: `KS ${ksToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: 7,
    name: 'Q4 Product Demo',
    file_name: 'q4-demo.mp4',
  }),
}).then((res) => res.json());

// Step 2: Upload the file using Kaltura's upload API
const formData = new FormData();
formData.append('fileData', videoFile);

await fetch(`https://www.kaltura.com/api_v3/service/uploadtoken/action/upload?uploadTokenId=${upload_token_id}&ks=${ksToken}`, { method: 'POST', body: formData });

console.log(`File uploaded to entry: ${entry_id}`);

`delete` — Delete a Knowledge Record

POST /v1/knowledge/delete

Permanently deletes a knowledge record.

Request body:

{ "id": 7 }

Check intellects before deleting

If an intellect references this knowledge record via knowledge_ids, remove it from there first to avoid broken configurations.

Attaching Knowledge to an Intellect

Once you have a knowledge record ID, attach it when creating or updating an intellect:

// Create an intellect with knowledge attached
const intellect = await fetch('https://YOUR_API_HOST/v1/intellect/add', {
  method: 'POST',
  headers: { Authorization: `KS ${ksToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'internal',
    name: 'Kali',
    status: 1,
    knowledge_ids: [7], // ← attach the knowledge record
    capabilities: {
      use_knowledge_base: 'on', // ← enable it
    },
  }),
}).then((res) => res.json());

info

Currently only one knowledge record can be attached per intellect (knowledge_ids has a max of 1 item).

Next Steps

🧠 Intellect Service — Attach this knowledge record via knowledge_ids and enable use_knowledge_base
🤖 Agent Service — Configure agents that use this intellect

How Knowledge Relates to Intellect​

Data Model​

Knowledge​

KnowledgeConfig​

Source Types​

Indexers (for internal sources)​

Actions​

add — Create a Knowledge Record​

get — Retrieve a Knowledge Record​

update — Update a Knowledge Record​

upload — Upload Content to a Knowledge Record​

delete — Delete a Knowledge Record​

Attaching Knowledge to an Intellect​

Next Steps​

How Knowledge Relates to Intellect

Data Model

Knowledge

KnowledgeConfig

Source Types

Indexers (for internal sources)

Actions

`add` — Create a Knowledge Record

`get` — Retrieve a Knowledge Record

`update` — Update a Knowledge Record

`upload` — Upload Content to a Knowledge Record

`delete` — Delete a Knowledge Record

Attaching Knowledge to an Intellect

Next Steps