Knowledge Base API

The Knowledge Base API allows you to programmatically add, update, and delete content in your AI agent's knowledge base. This is useful for:

• Inventory sync - Keep product catalogs, car listings, or service offerings up-to-date
• Document management - Sync content from external CMS or document systems
• Data pipelines - Automate content ingestion from scrapers or ETL processes

Overview

The API uses a source-based approach where each piece of content is identified by an externalId that you control. This enables:

• Upsert semantics - Create or update sources in a single operation
• Deduplication - Content is only reprocessed when it actually changes
• Bulk operations - Efficiently sync many sources at once

Processing

All content is processed asynchronously:

1. You submit content via the API
2. The API returns immediately with a processing status
3. Content is chunked and embedded in the background
4. You can poll the GET endpoint to check processing status

Endpoints

Quick Start

1. Get your API key

Generate an API key from the Heppu dashboard under Settings > API Keys.

2. Find your collection ID

Navigate to Knowledge Base in the dashboard and select your collection. The collection ID is in the URL.

3. Sync your first source

curl -X POST https://v2.heppu.ai/api/v1/kb/sources \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionId": "your-collection-id",
    "externalId": "product-123",
    "title": "2024 Toyota Camry",
    "content": "# 2024 Toyota Camry\n\nThe 2024 Toyota Camry is a mid-size sedan...\n\n## Features\n- Hybrid powertrain\n- Advanced safety features\n\n## Pricing\nStarting at $28,400"
  }'

Content Format

Content should be provided as Markdown. The API supports:

• Headings (# H1, ## H2, etc.)
• Lists (ordered and unordered)
• Code blocks
• Tables
• Links and emphasis

The content is automatically chunked and embedded for semantic search. Recommended chunk size is 384 tokens with 32 token overlap (these are the defaults).

Related

• Sources - Single source operations
• Batch Sources - Batch operations