Overview

Merge allows you to connect to any supported knowledge base system through a single, unified API. This guide provides a high-level overview of our general approach.

Common Models Overview

Merge normalizes Knowledge Base platforms into a shared set of common models, so you can build once and support multiple providers.

• Articles: Articles represent a form of content in the knowledge base system (for example, pages). Articles typically live within a container and may be nested depending on the source system.

• Attachments: Attachments represent files associated with articles or containers

• Containers: Containers represent a group of articles, such as spaces, folders, collections, or similar groupings.

• Groups: Groups represent any subset of Users. This can extend to company domains as well.

• Users: Users represent a user within the Knowledge Base account.

Authentication

Merge supports multiple categories of authentication for Knowledge Base integrations (support varies by integration):

1. Admin

2. Individual

With admin authentication, Merge pulls containers, articles, and attachments that the admin has access to.

Merge recommends admin authentication for most Knowledge Base use cases for the following reasons:

• Using up less third-party rate limits: Merge automatically handles third-party rate limits and backs off when a Linked Account is nearing these rate limits. Connecting one admin-level Linked Account is a more efficient use of these rate limits

• Faster syncs: Backing off when nearing third-party rate limits slows down syncs. Multiple individual-user Linked Accounts will unnecessarily slow down how quickly you can sync all the data you need from an end-user organization

• Access Control Lists (ACLs): Merge’s permissions models allow you to track who should have access to each file and build accurate ACLs. These are especially valuable when admin authentication is used as they provide precise data on permissions across the end user’s organization. Permissions models will still be mapped for Linked Accounts using individual authentication. However, they will not include permissions data for files that individual does not have access to.

Access control lists (ACLs)

An Access Control List is a security feature used in systems (e.g., networking, file systems, databases) to define rules for what users or systems can access specific resources and what actions they can perform on them.

Knowledge Base integrations can be used to build ACL-aware downstream systems, so consumers of the data only see content they are authorized to access.

You may also consider Implementing Customer-Managed Access Control Lists (ACLs) for Knowledge Base as an advanced approach.

Optimized data transfer

Selective Sync

Selective Sync lets your users select which containers and articles to grant access to. It also speeds up initial syncs by ensuring only relevant data is synced. This can be surfaced to your users as part of the Merge linking flow and be edited at any point.

Selective Sync can be configured in the Merge Dashboard under Advanced → Selective Sync.

Syncing data

Merge uses two mechanisms to efficiently sync data from third-party APIs:

1. Polling third-party APIs on a cadence to capture recurring updates

2. Receiving near real-time updates via third-party webhooks

These are optimized to sync data as efficiently as possible within the constraints of the third-party system involved. The highest sync frequencies provided by Merge are optimized based on third-party rate limits and performance at scale.

Knowledge base systems are highly dynamic, with constant changes to both content and permissions. Users frequently add, move, edit and delete articles, while permissions evolve as employees join organizations and content gets reorganized across folders and drives.

For applications that require near-real time delivery of accurate information, having access to the latest data is critical. This means keeping up with newly created articles and attachments, excluding recently deleted articles and attachments, or updating who should no longer have access to a file.

For AI and other near real-time use cases, Merge recommends using the highest sync frequency. For some models and integrations, recurring syncs run every few minutes to poll the latest data, ensuring that your system keeps up with the frequency of updates made by your end users. Consistently polling the third-party API provides the most comprehensive way of capturing all relevant changes. Third-party webhooks, while complementary, may have coverage gaps or be affected by third-party system outages, leading to missed updates.

Article content storage and access

Merge syncs and stores Knowledge Base metadata (containers, articles, attachments, and permissions). Article content is fetched via a time-bound download URL. Specifically, the article_content_download_url is a presigned URL that expires after 3 hours (TTL = 3 hours).

For use cases that require longer-lived access (for example, search indexing or AI/RAG pipelines), we recommend fetching content before expiration and storing it in your own system, refreshing content as needed.

Rate limits

Merge accounts for third-party rate limits when syncing data. These are different from Merge’s standardized API rate limits (your requests to Merge’s API).

Integration-specific guides

• Confluence - Integration nuances

• Notion - Integration nuances