Getting Started with the Synthesis Search Connector API

The Synthesis Search Connector API lets your firm make content from outside systems - help centers, documentation platforms, websites, and other text-based sources - searchable in Synthesis. This article covers what the API does, what your team is responsible for, and how to set up your first Custom Search Connector.

What is the Search Connector API?

Many firms keep useful knowledge outside the intranet: IT how-to articles in a help desk tool, or newsletters on a public website. The Search Connector API gives you one consistent way to bring that content into Synthesis Search, so people can find it from the same search bar they already use.

Your developer writes a small program, called a Custom Search Connector, that reads content from your source system and sends it to Synthesis through the API. Once it's in, the content:

• Appears in Synthesis Search - in both the AI-powered Summary results and the keyword-based Everything results
• Shows your connector's icon so people can tell where a result came from
• Links back to the original source - clicking a result opens the content in its native source system
• Shows up in Content Optimization - clicks are tracked as external links, and you can see everything a connector has sent

A few things are helpful to know up front:

• Everyone at your firm can see it. Connector content is available to all of your Synthesis users (and only your Synthesis users). The API doesn't support per-item permissions or filtering by who is searching, so only connect content that's appropriate for everyone at your firm.
• It's for text. The API indexes text content. Images, videos, and files aren't indexed, and image tags inside HTML are ignored.
• It's for content people read, not data records. The API is designed for articles, pages, and posts. It isn't designed to import structured data from systems like Vantagepoint, Unanet, etc. - Synthesis has separate integrations for those.
• Every item needs a link. Each item you send includes a URL to its original source. Search results link to that page as a whole, not to a section within it.
• Synthesis doesn't fetch content for you. The API receives what your connector sends. Your connector is responsible for adding new content, updating changed content, and removing deleted content.

Is my content a good fit?

Good fits - text-based sources where each item has its own page:

• IT help desk and knowledge base articles (for example, Jitbit, Freshservice, or TeamDynamix)
• Documentation platforms and wikis
• Your firm's website, blog, or newsletter
• Course titles and descriptions from an external LMS

Not a good fit:

• File storage like SharePoint, Egnyte, or Teams - these often need permissions and contain files rather than text
• Video, image, or document libraries
• Structured records from ERP, CRM, or HR systems
• Content that should only be visible to some people at your firm

If you're not sure whether a source is a good fit, contact us at support@knowledge-architecture.com before you build. We're happy to talk it through.

Who does what

You don't need an in-house developer to use the API. The API documentation is public, so you can share it with an outside developer or consultant.

Before you begin

You'll need:

• Global Administrator access in Synthesis, to create connectors and get API keys
• A developer - in-house or hired - to build and maintain the connector
• To follow along with our example project, your developer will also need Node.js v24 (we recommend installing it with NVM) and a code editor like Visual Studio Code

Create a Custom Search Connector

Create one connector for each source system you want to connect.

1. In Synthesis, click the Settings cog, then select Settings under Configuration.
2. Go to Integrations > Custom Search Connectors.
3. Click Add connector.
4. Enter a Connector Name - for example, "IT Help Center."
5. Upload a Connector Icon. This icon appears next to this connector's content in search results. It should be exactly 100 x 100 pixels, saved as a .png or .svg file.
6. Add a Connector Description (up to 250 characters). This helps Synthesis AI understand what the content is and how it should be used in search. For example: "Connects to our help center. It contains troubleshooting guides, product documentation, and answers to common support questions."
7. Click Create.

Your new connector appears in the list with its API Key and Connector ID. Share both with your developer - your connector code uses them to send content to Synthesis.

Treat the API key like a password. Anyone with the key can send content to that connector.

Keep it disabled until you're ready

A connector can be enabled, disabled, or deleted, and each one does something different. Knowing the difference lets your developer build and test safely without showing unfinished content to your whole firm.

• Disabled - your connector can still send content to the API, but none of it appears in search. Use this while you're building and testing.
• Enabled - content from this connector appears in Synthesis Search for everyone at your firm.
• Rotate the API key - the old key stops working right away, and your connector can't send anything until it's updated with the new key. Use this if the key is exposed or you need to stop a connector quickly. Content already in Synthesis stays put.
• Deleted - the connector and all of its content are permanently removed. This can't be undone.

Our recommendation: keep a new connector disabled until you’re ready for its content to show in search, then enable it when you're ready for your firm to see it.

Build your connector

Your developer will find everything they need in two places:

• API documentation - describes each endpoint and lets your developer send test requests right from the browser. It also covers authentication and rate limits.
• Example GitHub project - a working connector that indexes Knowledge Architecture's Smarter by Design newsletter and podcast, plus a small TypeScript SDK. It's a good starting point to copy and adapt for your own source.

A few tips for your developer:

• Send clean text. Strip out images and page navigation, and send the main body text. Synthesis can only use the text you send.
• Only send what changed. The example project shows how to compare content between runs so you only send new or updated items.
• Plan around rate limits. Rate limits apply to your whole firm, not to each connector. If you run several connectors, stagger their schedules. The API returns headers that show your remaining quota and when it resets.
• Check the terms before scraping a website. If you're collecting content from a website your firm doesn't own, make sure its terms allow it. Some sites also block automated scraping.

See what's been indexed

You can see every item a connector has sent in Content Optimization.

1. In Synthesis, click the Settings cog, then select Content Optimization under Analytics.
2. Go to the Content Inventory tab.
3. Filter by Location and select your connector's name.

This is also a good way to check a connector's content before you enable it.

Troubleshooting

Connector content isn't showing up in search

• Check that the connector is enabled. Content from a disabled connector doesn't appear in search.
• Check Content Optimization. If the content isn't in the Content Inventory, Synthesis hasn't received it - check your connector's logs and the API response.

Content is out of date or still showing after it was deleted

Synthesis doesn't check your source system for changes. Make sure your connector is running on a schedule and sends updates and deletes, not just new items.

My source doesn't have a URL for each item

Each item needs a link. If your source doesn't have a page for each item, you can point items to a shared landing page. URLs don't need to be unique.

Questions or feedback

If you run into trouble, contact support@knowledge-architecture.com. That includes questions about the example GitHub project - please send those to support rather than opening an issue on GitHub.

We'd also love to hear what you're connecting - the sources you've connected, what's working, and what you wish the API could do all help us improve it. And please encourage your users to keep rating their search results. It's one of the most helpful ways to improve search over time.