Ingestion API

Overview

The Ingestion API lets you push structured data from any external source into your Reaktly knowledge base. Once ingested, content is automatically embedded and made available to the AI assistant.

Authentication

All requests require an API key with the iq:import scope:

curl -X POST https://api.reaktly.com/ingest \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Endpoints

`POST /ingest` — Single Item

Ingest a single item into your knowledge base.

Request Body:

Field	Type	Required	Description
`integrationId`	string	✅	Your integration UUID
`knowledgeBaseId`	string	✅	Target knowledge base UUID
`sourceType`	string	✅	Content type (PRODUCT, ARTICLE, PAGE, SERVICE, PERSON)
`externalId`	string	✅	Unique ID from your source system
`data.title`	string	✅	Title of the item
`data.content`	string	✅	Main text content (used for AI embedding)
`data.url`	string	❌	Link to the original resource
`data.sourceData`	object	❌	Structured metadata (price, SKU, author, etc.)
`data.hash`	string	❌	Content hash for change detection
`options.forceRefresh`	boolean	❌	Force re-processing even if unchanged
`options.priority`	string	❌	`"high"` or `"low"`

Example:

{
  "integrationId": "int_abc123",
  "knowledgeBaseId": "kb_xyz789",
  "sourceType": "ARTICLE",
  "externalId": "blog-post-42",
  "data": {
    "title": "How to Use Our Product",
    "content": "This comprehensive guide walks you through...",
    "url": "https://your-site.com/blog/how-to-use",
    "hash": "a1b2c3d4e5f6"
  }
}

Response:

{
  "status": "queued",
  "jobId": "int_abc123-blog-post-42"
}

`POST /ingest/bulk` — Batch Import

Ingest multiple items in a single request. Optimized for initial data loads.

Request Body:

{
  "items": [
    { /* CreateIngestionDto */ },
    { /* CreateIngestionDto */ }
  ]
}

Response:

{
  "status": "queued",
  "jobCount": 50,
  "estimatedTime": "5s",
  "jobIds": ["id-1", "id-2", "..."]
}

Language Examples

Node.js / TypeScript

const response = await fetch('https://api.reaktly.com/ingest', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.REAKTLY_API_KEY!,
  },
  body: JSON.stringify({
    integrationId: 'your-integration-id',
    knowledgeBaseId: 'your-kb-id',
    sourceType: 'ARTICLE',
    externalId: 'unique-id',
    data: {
      title: 'My Article',
      content: 'Full text content here...',
    },
  }),
});

Python

import requests

response = requests.post(
    "https://api.reaktly.com/ingest",
    json={
        "integrationId": "your-integration-id",
        "knowledgeBaseId": "your-kb-id",
        "sourceType": "ARTICLE",
        "externalId": "unique-id",
        "data": {
            "title": "My Article",
            "content": "Full text content here...",
        },
    },
    headers={"x-api-key": "YOUR_API_KEY"},
)

cURL

curl -X POST https://api.reaktly.com/ingest \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "integrationId": "your-integration-id",
    "knowledgeBaseId": "your-kb-id",
    "sourceType": "ARTICLE",
    "externalId": "unique-id",
    "data": {
      "title": "My Article",
      "content": "Full text content here..."
    }
  }'

For the complete API reference with all language examples, database-specific patterns, and CMS integration guides, see the full integration guide.

Ingestion API

On this page