Readme V2 Knowledge Sync

Integrate your team's knowledge directly from your ReadMe V2 documentation into Brainfish. By syncing your ReadMe content, you can keep your AI agent's knowledge up-to-date automatically, ensuring it always provides the most accurate and relevant answers based on your documentation, guides, and other content.

This guide will walk you through the process of connecting and syncing your ReadMe V2 documentation as a knowledge source.

Step 1: Navigate to External Data and Add a New Source

From your Brainfish Dashboard, click on External Data in the left-hand navigation menu.

Click the + Source button.

From the list of external data sources, select ReadMe V2.

Step 2: Configure Your ReadMe V2 Connection

You will now see the "Configure ReadMe V2" form. You'll need to provide several pieces of information to establish the connection.

Integration Name

Source Name: Enter a descriptive name for your integration, such as "ReadMe V2 Documentation" or "Product Guides". This name must be at least 3 characters long.

Authentication

ReadMe V2 API Key: Enter your ReadMe V2 API key. You can find this in your ReadMe dashboard under API Keys.

API Key Requirements:

• Must start with rdme_
• Must be at least 32 characters long
• Should be a valid, unmasked API key

How to Find Your ReadMe API Key:

1. Log into your ReadMe dashboard
2. Navigate to Configuration → API Keys
3. Create a new API key or copy an existing one
4. Ensure the API key has the necessary permissions to read documentation

Documentation Domain

ReadMe Documentation Domain: Enter the full URL of your ReadMe documentation site.

Examples:

• https://docs.yourcompany.com
• https://yourcompany.readme.io

Domain Requirements:

• Must be a valid HTTP or HTTPS URL
• Must be publicly accessible
• Cannot be changed after the integration is created

Branch/Version Selection

Branch: Select which branch or version of your ReadMe documentation to sync from.

Available Options:

• Stable (Default): Production-ready content — recommended for most users
• Main: Latest development content
• Master: Legacy main branch

Content Type Configuration

Content Type: Choose what type of content you want to import from ReadMe V2.

Currently, Guides & Recipes are supported, which includes:

• Regular documentation pages
• Articles
• How-to guides
• Knowledge base content

Note: Additional content types (such as API references and recipes) will be available in future updates.

Category Selection

Categories: Select specific categories to import, or leave empty to import all available categories.

• The system will automatically load available categories once you provide a valid API key and select a branch
• You can choose specific categories to limit the scope of your import
• If no categories are selected, all available guide categories will be imported
• The status message will show how many categories are available and selected

Daily Sync

Enable Daily Sync: Toggle this option to automatically sync your ReadMe V2 content daily at 2:00 AM UTC.

Benefits of Daily Sync:

• Keeps your AI agent's knowledge current with your latest documentation
• Automatically imports new articles and updates existing ones
• Runs without manual intervention
• Uses system-level permissions to avoid email notifications

Click the + Add Source button to create the integration.

Step 3: Sync and Verify Your Content

After adding the source, Brainfish will begin importing content from your ReadMe V2 documentation.

On the External Data page, you will see your new ReadMe V2 source with a "Syncing" status. This process may take several minutes, depending on:

• The number of categories selected
• The amount of content in each category
• The complexity of your documentation structure

Once the sync is complete, the status will update to show:

• The number of guides imported
• The last sync timestamp
• Any sync errors (if applicable)

Viewing Imported Content:

1. Click on the newly created ReadMe V2 catalog card
2. Browse the list of imported guides and categories
3. Click the eye icon (👁️) next to any guide to preview its content
4. Verify that the content was imported correctly and is properly formatted

Step 4: Enable the Source for Your Agent

To start using this knowledge, you must enable the source and ensure your agent has access to it.

Enable the Knowledge Source:

1. On the External Data page, find your ReadMe V2 source card
2. Click the three-dots menu (...)
3. Ensure the source is marked as Enabled

Configure Agent Access:

1. Navigate to the Agents page from the left-hand menu
2. Select the agent you want to train with this new knowledge
3. In the agent configuration panel, go to Knowledge Settings
4. Choose one of the following options:
   • All sources: Agent will use all enabled knowledge sources (recommended)
   • Specific sources: Manually select your ReadMe V2 source from the dropdown menu

Step 5: Test Your Integration

Finally, test that your agent can find and use information from the ReadMe V2 source.

Testing Steps:

1. Open the Agent Playground or visit your website where the agent is deployed
2. Ask a question related to the content from your ReadMe V2 documentation
3. The agent should provide a detailed answer based on the information from your guides
4. Expand the Sources section to see the specific ReadMe guide that was used to generate the answer
5. Verify that the source attribution shows your ReadMe V2 integration

Example Test Questions:

• "How do I [specific process from your documentation]?"
• "What is [concept explained in your guides]?"
• "Can you explain [feature documented in ReadMe]?"

You have now successfully integrated ReadMe V2 with Brainfish! Your agent will be able to answer questions using the knowledge from your ReadMe documentation.

Troubleshooting

Common Issues

"Invalid ReadMe v2 API Key" Error

• Cause: The API key is incorrect, expired, or doesn't have proper permissions
• Solution:
  • Verify the API key in your ReadMe dashboard
  • Ensure the key starts with rdme_ and is at least 32 characters
  • Check that the API key has read permissions for guides
  • Try creating a new API key if the current one is old

"Domain is not valid" Error

• Cause: The ReadMe domain URL is incorrectly formatted or inaccessible
• Solution:
  • Verify the URL format starts with https:// or http://
  • Ensure the domain is publicly accessible
  • Check that the URL points to your actual ReadMe documentation site
  • Test the URL in a browser to confirm it loads correctly

"Failed to load categories" Error

• Cause: API key or branch selection issues, or network connectivity problems
• Solution:
  • Verify your API key is correct and active
  • Try selecting a different branch (e.g., switch from "main" to "stable")
  • Check your ReadMe dashboard to ensure categories exist for the selected branch
  • Wait a moment and try again, as this might be a temporary network issue

"No categories found" Message

• Cause: The selected branch doesn't contain any guide categories
• Solution:
  • Switch to a different branch that contains your documentation
  • Check your ReadMe dashboard to confirm guides exist in the selected branch
  • Ensure your ReadMe project has published guide content

"Request timeout" Error

• Cause: ReadMe API is responding slowly or there are network issues
• Solution:
  • Wait a few minutes and try again
  • Check ReadMe's status page for any ongoing issues
  • Verify your internet connection is stable
  • Try during off-peak hours if the issue persists

Sync Fails After Initial Setup

• Cause: API key permissions changed, content structure modified, or ReadMe API issues
• Solution:
  • Check that your API key still has the necessary permissions
  • Verify the selected categories still exist in ReadMe
  • Review the error logs in the External Data section for specific error messages
  • Try manually triggering a sync to see if the issue persists

Content Not Appearing in Agent Responses

• Cause: Source not enabled, agent not configured to use the source, or content indexing issues
• Solution:
  • Verify the ReadMe V2 source is enabled in the External Data section
  • Check agent settings to ensure it's configured to use "All sources" or specifically includes the ReadMe V2 source
  • Wait a few minutes after sync completion for content to be fully indexed
  • Test with specific questions that should have clear answers in your ReadMe content

API Key Troubleshooting

Finding Your API Key:

1. Log into your ReadMe dashboard
2. Go to Configuration → API Keys
3. Look for existing keys or create a new one
4. Copy the full key including the rdme_ prefix

API Key Validation:

• Keys must start with rdme_
• Must be at least 32 characters long
• Should not be masked (showing *** characters)
• Must have read permissions for your documentation

Testing API Key: You can test your API key manually using curl:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "X-ReadMe-Version: stable" \
     https://api.readme.com/v2/branches/stable/categories/guides

Branch and Content Issues

Available Branches:

• stable: Most commonly used, contains published content
• main: Development branch, may contain unpublished content
• master: Legacy branch name, equivalent to main

Content Requirements:

• Only guide-type content is currently supported
• Content must be published and accessible via the API
• Categories must contain at least one published guide