Files

Knowledge files let you give your agent domain expertise. Instead of relying on what the underlying LLM knows from training data, you upload your own documents — product manuals, policy guides, technical specs, training materials — and the agent retrieves relevant content during conversations.

How it works

Files are organized into knowledge collections. A knowledge collection is a container that groups related documents together and connects them to a specific LLM provider. When your agent needs to answer a question, it searches the collection and grounds its response in your content.

Each collection is tied to a provider that determines which embedding and retrieval mechanisms are used. Set the provider to match the LLM your agent runs on.

Create a knowledge collection

curl -X POST https://companion-api.napster.com/public/knowledge-bases \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Documentation",
    "provider": "azureOpenAI"
  }'

Response:

{
  "id": "kb_abc123",
  "name": "Product Documentation",
  "provider": "azureOpenAI",
  "created": 1710000000
}

The provider field determines which embedding backend is used. Set it to azureOpenAI for Azure OpenAI deployments.

Upload a file

Upload a file to a collection by providing a publicly accessible URL. The platform downloads and processes the file for retrieval.

curl -X POST https://companion-api.napster.com/public/knowledge-bases/kb_abc123/files \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/documents/product-catalog.pdf"
  }'

Response:

{
  "id": "file_xyz789",
  "originalName": "product-catalog.pdf",
  "contentType": "application/pdf",
  "createdAt": "2026-03-10T12:00:00Z"
}

Supported file types

Attaching knowledge to an agent

After creating a collection and uploading files, attach it to your Omniagent by passing the collection ID in the knowledgeBaseId field when creating the agent:

curl -X POST https://companion-api.napster.com/public/agents \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companionId": "comp_abc123",
    "voiceId": "alloy",
    "knowledgeBaseId": "kb_abc123",
    "providerSettings": {}
  }'

Different agents can use different collections, and you can override the collection per channel using channel overrides.

File summaries

Each file in a knowledge collection can have a summary — a short description of what the file contains. Summaries help the agent understand what each file is about and improve the chances of retrieving the right content when answering questions. A clear, descriptive summary makes it more likely that the agent will draw on that file during relevant conversations.

To update a file's summary:

curl -X PATCH https://companion-api.napster.com/public/knowledge-bases/kb_abc123/files/file_abc123/summary \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Product return policy and refund procedures for all regions"
  }'

Other operations

Use the API reference for managing collections and files after creation: