Build a Custom Connector

Overview

You can push data from any source into Reaktly using the Ingestion API. This guide shows you how to build a connector for your specific data source.

Prerequisites

Before you start, you'll need:

A Reaktly API key with iq:import scope
Your Integration ID (from Settings → Integrations)
Your Knowledge Base ID (from Settings → Knowledge Base)
Access to your data source

Architecture

A typical connector follows this pattern:

Extract — Read data from your source
Transform — Map fields to the Reaktly ingestion format
Load — Push to the Ingestion API

Step-by-Step

1. Set Up Authentication

const config = {
  apiKey: process.env.REAKTLY_API_KEY,
  baseUrl: 'https://api.reaktly.com',
  integrationId: process.env.REAKTLY_INTEGRATION_ID,
  knowledgeBaseId: process.env.REAKTLY_KB_ID,
};

2. Build Your Transformer

Map your data to the Reaktly format:

function transform(item: YourDataType) {
  return {
    integrationId: config.integrationId,
    knowledgeBaseId: config.knowledgeBaseId,
    sourceType: 'ARTICLE', // or PRODUCT, SERVICE, PERSON, PAGE
    externalId: `your-source-${item.id}`,
    data: {
      title: item.title,
      content: item.body, // The text the AI will use
      url: `https://your-site.com/items/${item.slug}`,
      sourceData: {
        // Structured data for rich responses
        author: item.author,
        category: item.category,
      },
      hash: computeHash(item), // For change detection
    },
  };
}

3. Push to Reaktly

async function sync(items: YourDataType[]) {
  const transformed = items.map(transform);

  const response = await fetch(`${config.baseUrl}/ingest/bulk`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': config.apiKey,
    },
    body: JSON.stringify({ items: transformed }),
  });

  const result = await response.json();
  console.log(`Synced ${result.jobCount} items`);
}

Full Reference

For complete API documentation, language-specific examples, and database-specific patterns, see:

Build a Custom Connector

On this page