Knowledge Base (RAG)

The Knowledge Base API lets you ground an agent's answers in your own documents instead of relying on whatever the model already knows. Upload text, link it to one or more agents, and opt in to retrieval on any chat call — PulseLABS finds the most relevant passages and injects them into the agent's context before it answers.

This is retrieval-augmented generation (RAG): nothing is fine-tuned, no model weights change. Each chat call retrieves fresh, relevant chunks at request time, so updating a source updates every future answer immediately.

How it works

Ingestion and retrieval both run through the same embedding pipeline used across PulseLABS — OpenAI's text-embedding-3-small when an OpenAI key is configured, or Ollama's nomic-embed-text for fully local setups. Both produce 768-dimensional vectors, so the same retrieval code works regardless of which provider is active.

1. Chunking — raw text is split into ~1200-character chunks with 150 characters of overlap, so context isn't lost at chunk boundaries.
2. Embedding — each chunk is embedded once at ingestion time and stored alongside the chunk text.
3. Retrieval — at chat time, the user's message is embedded and compared against every chunk in the agent's linked sources by cosine similarity.
4. Injection — the top-K matching chunks are appended to the agent's system prompt as a high-priority context block, labelled with their source name.

Ingesting a Knowledge Source

Send raw text — a doc page, a support FAQ, a pricing sheet, transcript, whatever your agent should know. PulseLABS chunks and embeds it server-side; there's no separate upload-then-process step.

{
  "id": "kns_xxx",
  "chunkCount": 14
}

curl -X POST https://api.pulsesoftwareapp.com/v1/knowledge-sources \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pricing FAQ",
    "description": "Internal pricing rules and edge cases",
    "content": "Annual plans get a 20% discount. Refunds are issued within 14 days of purchase...",
    "agentIds": ["agent_xxx"]
  }'

{
  "sources": [
    {
      "id": "kns_xxx",
      "name": "Pricing FAQ",
      "description": "Internal pricing rules and edge cases",
      "createdAt": "2026-06-20T10:00:00Z",
      "_count": { "chunks": 14 },
      "agents": [{ "id": "agent_xxx", "name": "Victoria Chen" }]
    }
  ]
}

{
  "source": {
    "id": "kns_xxx",
    "name": "Pricing FAQ",
    "agents": [{ "id": "agent_xxx", "name": "Victoria Chen" }],
    "_count": { "chunks": 14 }
  }
}

// 204 No Content

Linking Sources to Agents

A source only feeds an agent's answers once it's linked. Link it at ingestion time via agentIds, or link/unlink afterwards with these endpoints.

{
  "agent": {
    "id": "agent_xxx",
    "knowledgeSources": [{ "id": "kns_xxx", "name": "Pricing FAQ" }]
  }
}

// 204 No Content

Retrieving During Chat

Retrieval is opt-in per call — pass knowledge.enabled: true on a normal Agent Chat request. PulseLABS embeds the user's message, finds the top-K matching chunks across the agent's linked sources, and injects them as high-priority context before generating the response.

Request fields:

"knowledge": {
  "enabled": true,   // default false
  "topK": 5          // chunks to retrieve, 1–20, default 5
}

The response includes a knowledgeUsed array so you can cite or surface which passages informed the answer:

"knowledgeUsed": [
  {
    "sourceId": "kns_xxx",
    "sourceName": "Pricing FAQ",
    "chunkPreview": "Annual plans get a 20% discount. Refunds are issued within 14 days...",
    "similarity": 0.91
  }
]

curl -X POST https://api.pulsesoftwareapp.com/v1/agents/agent_xxx/chat \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Do annual plans get a discount?",
    "knowledge": { "enabled": true, "topK": 5 }
  }'