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 the collection to your agent when creating a connection. Pass the collection ID in the knowledgeBaseId field:

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

Different sessions for the same companion can use different collections.

Other operations

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