Custom Knowledge Base Connector

Connect your internal knowledge base or CMS to Cevro by exposing a REST API endpoint. Cevro will periodically fetch your articles and make them available to your AI agents.

Overview

The Custom KB Connector allows you to:

Sync articles from any REST API you control
Keep your knowledge base automatically updated (daily, weekly, or manual)
Receive instant updates via webhooks when content changes
Map your API’s response format to Cevro’s article schema

Quick Start

Create your API endpoint

Build a REST endpoint that returns your articles in JSON format.

Test the connection

Use the “Test Connection” feature in Cevro to verify your endpoint works.

Configure the connector

Set up authentication, field mapping, and sync frequency.

Start syncing

Trigger the initial sync and watch your articles appear in Cevro.

API Requirements

Your endpoint must return articles in JSON format. Cevro supports flexible field mapping, so you can adapt to most response structures.

Basic Response Format

{
  "articles": [
    {
      "id": "article-123",
      "title": "How to reset your password",
      "content": "<p>To reset your password, click the 'Forgot Password' link...</p>",
      "url": "https://help.example.com/password-reset",
      "category": "Account",
      "lastModified": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJwYWdlIjogMn0="
  }
}

Required Fields

Field	Description
`id`	Unique identifier for the article. Used to track updates and removals.
`title`	Article title displayed to users and used for search.
`content`	Article body. Can be HTML or plain text.

Optional Fields

Field	Description
`url`	Source URL for the article (displayed to users)
`category`	Category or folder for organization
`lastModified`	ISO 8601 timestamp for incremental sync

Field names are fully customizable. If your API uses body instead of content, or modified_at instead of lastModified, you can configure this in the field mapping.

Authentication

Cevro supports four authentication methods:

Bearer Token
Basic Auth
API Key
Custom Header

Authorization: Bearer your-token-here

Best for: APIs using JWT or OAuth tokensConfiguration:

{
  "authType": "bearer",
  "credentials": {
    "token": "your-bearer-token"
  }
}

Authorization: Basic base64(username:password)

Best for: Traditional username/password authenticationConfiguration:

{
  "authType": "basic",
  "credentials": {
    "username": "your-username",
    "password": "your-password"
  }
}

X-API-Key: your-api-key

Best for: Simple API key authenticationConfiguration:

{
  "authType": "api_key",
  "credentials": {
    "headerName": "X-API-Key",
    "apiKey": "your-api-key"
  }
}

Your-Custom-Header: your-value

Best for: Non-standard authentication schemesConfiguration:

{
  "authType": "custom_header",
  "credentials": {
    "headerName": "Your-Custom-Header",
    "headerValue": "your-value"
  }
}

Credentials are encrypted at rest using AES-256 encryption. Never share your API credentials publicly.

Field Mapping

If your API response doesn’t match the default format, configure field mapping using JSONPath expressions.

Default Mapping

{
  "articlesPath": "$.articles",
  "idField": "$.id",
  "titleField": "$.title",
  "contentField": "$.content",
  "urlField": "$.url",
  "categoryField": "$.category",
  "lastModifiedField": "$.lastModified"
}

Custom Mapping Examples

Nested articles array:

// API Response: { "data": { "items": [...] } }
{
  "articlesPath": "$.data.items"
}

Different field names:

// API uses "body" and "headline" instead of "content" and "title"
{
  "titleField": "$.headline",
  "contentField": "$.body"
}

Deeply nested fields:

// API returns: { "metadata": { "articleId": "123" } }
{
  "idField": "$.metadata.articleId"
}

Pagination

Cevro supports cursor-based and offset pagination to handle large article collections.

Cursor Pagination (Recommended)

Your API should accept a cursor parameter and return the next cursor in the response: Request: GET /articles?cursor=abc123&limit=100 Response:

{
  "articles": [...],
  "pagination": {
    "hasMore": true,
    "nextCursor": "def456"
  }
}

Configuration:

{
  "type": "cursor",
  "cursorParam": "cursor",
  "limitParam": "limit",
  "defaultLimit": 100,
  "hasMorePath": "$.pagination.hasMore",
  "nextCursorPath": "$.pagination.nextCursor"
}

Offset Pagination

If your API uses page numbers or offsets: Request: GET /articles?offset=100&limit=100 Configuration:

{
  "type": "offset",
  "cursorParam": "offset",
  "limitParam": "limit",
  "defaultLimit": 100
}

No Pagination

For small knowledge bases that return all articles in a single response:

{
  "type": "none"
}

Cevro limits syncs to 50,000 articles and 500 pagination pages to prevent runaway syncs. If you have more articles, consider filtering by category or date.

Webhooks

Enable instant syncs when your content changes by sending a webhook to Cevro.

Webhook URL

After creating your connector, you’ll receive a webhook URL:

https://api.cevro.ai/api/v1/webhooks/kb-sync/{integrationId}

Sending a Webhook

When your content changes, POST to the webhook URL:

curl -X POST "https://api.cevro.ai/api/v1/webhooks/kb-sync/{integrationId}" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: whsec_your_secret_here" \
  -d '{
    "event": "content_updated",
    "timestamp": "2025-01-15T10:30:00Z"
  }'

Webhook Payload

Field	Type	Description
`event`	string	Must be `"content_updated"`
`timestamp`	string	ISO 8601 timestamp of the change
`changedIds`	string[]	(Optional) Specific article IDs that changed

Security

The webhook secret is provided when you create the connector (shown only once)
Include the secret in the X-Webhook-Secret header
Webhooks are rate-limited to 10 requests per minute

Sync Frequency

Choose how often Cevro fetches your articles:

Frequency	Description
Daily	Syncs every day at 1 AM (default)
Weekly	Syncs every Monday at 1 AM
Manual	Only syncs when you trigger it

Use webhooks alongside scheduled syncs for the best of both worlds: automatic daily updates plus instant syncs when content changes.

Content Guidelines

HTML Content

Article content can include HTML. Cevro will:

Preserve formatting (headings, lists, links, tables)
Remove <script> tags for security
Remove inline event handlers (onclick, onload, etc.)
Truncate content exceeding 10 MB

Best Practices

Use semantic HTML

Structure content with proper headings (h1, h2), lists, and paragraphs for better AI comprehension.

Include context

Articles should be self-contained. The AI may not see other articles when answering a question.

Keep titles descriptive

Use clear, searchable titles. “Password Reset” is better than “Article 47”.

Update lastModified

Including timestamps helps Cevro identify which articles have changed.

Troubleshooting

Connection test fails with 'No articles found'

Check your articlesPath field mapping. If your API returns { "data": [...] } instead of { "articles": [...] }, update the mapping to "$.data".

Authentication error

Verify your credentials are correct. For Bearer tokens, ensure you’re not including the “Bearer ” prefix in the token value (Cevro adds it automatically).

Sync times out

Large knowledge bases may take time to sync. Check the sync logs for progress. If consistently timing out, consider:

Increasing your API’s timeout
Reducing the number of articles per page
Filtering to essential articles only

Articles not updating

Ensure your API returns different content when articles change. Cevro compares article content to detect updates. Also verify the lastModified field is updating correctly.

Webhook not triggering sync

Verify the X-Webhook-Secret header matches the secret shown during connector creation
Check that your request body includes "event": "content_updated"
Webhooks are rate-limited to 10/minute

API Reference

Test Connection

Test your endpoint configuration without creating a connector.

POST /api/v1/integrations/kb-connectors/test

Request:

{
  "endpointUrl": "https://your-api.com/articles",
  "authType": "bearer",
  "credentials": {
    "token": "your-token"
  },
  "fieldMapping": {
    "articlesPath": "$.data"
  }
}

Response:

{
  "success": true,
  "articlesCount": 150,
  "sampleArticle": {
    "id": "article-1",
    "title": "Getting Started",
    "contentPreview": "Welcome to our platform..."
  },
  "detectedSchema": {
    "fields": ["id", "title", "body", "created_at"],
    "suggestedMapping": {
      "idField": "$.id",
      "titleField": "$.title",
      "contentField": "$.body"
    }
  }
}

Trigger Manual Sync

POST /api/v1/integrations/kb-connectors/{id}/sync

Query Parameters:

forceFresh=true - Re-sync all articles, ignoring lastModified timestamps

View Sync Logs

GET /api/v1/integrations/kb-connectors/{id}/sync-logs?limit=50

Security

Cevro implements several security measures:

Credential encryption: All credentials are encrypted at rest using AES-256
SSRF protection: Internal/private IP addresses are blocked (localhost, 10.x.x.x, 192.168.x.x, etc.)
Content sanitization: Script tags and event handlers are removed from article content
Rate limiting: Webhooks are limited to 10 requests per minute
Webhook authentication: Constant-time comparison prevents timing attacks on secrets

Get Started

AI Ticket Handling

Analytics & Insights

Working with Human Agents

Responsible Gaming

Settings

Security & Compliance

Custom Integrations

Custom Knowledge Base Connector

Overview

Quick Start

API Requirements

Basic Response Format

Required Fields

Optional Fields

Authentication

Field Mapping

Default Mapping

Custom Mapping Examples

Webhooks

Webhook URL

Sending a Webhook

Webhook Payload

Security

Sync Frequency

Content Guidelines

HTML Content

Best Practices

Use semantic HTML

Include context

Keep titles descriptive

Update lastModified

Troubleshooting

API Reference

Test Connection

Trigger Manual Sync

View Sync Logs

Security

Get Started

AI Ticket Handling

Analytics & Insights

Working with Human Agents

Responsible Gaming

Settings

Security & Compliance

Custom Integrations

​Overview

​Quick Start

​API Requirements

​Basic Response Format

​Required Fields

​Optional Fields

​Authentication

​Field Mapping

​Default Mapping

​Custom Mapping Examples

​Pagination

​Cursor Pagination (Recommended)

​Offset Pagination

​No Pagination

​Webhooks

​Webhook URL

​Sending a Webhook

​Webhook Payload

​Security

​Sync Frequency

​Content Guidelines

​HTML Content

​Best Practices

Use semantic HTML

Include context

Keep titles descriptive

Update lastModified

​Troubleshooting

​API Reference

​Test Connection

​Trigger Manual Sync

​View Sync Logs

​Security

Overview

Quick Start

API Requirements

Basic Response Format

Required Fields

Optional Fields

Authentication

Field Mapping

Default Mapping

Custom Mapping Examples

Pagination

Cursor Pagination (Recommended)

Offset Pagination

No Pagination

Webhooks

Webhook URL

Sending a Webhook

Webhook Payload

Security

Sync Frequency

Content Guidelines

HTML Content

Best Practices

Troubleshooting

API Reference

Test Connection

Trigger Manual Sync

View Sync Logs

Security