Search API endpoint

Hi - unless it’s already a feature and I didn’t find it, it’d be really helpful for us to be able to search for docs on a hub via API.

This would be to support chatbot support that can retrieve guides for site users.

Hey @ed.long, that’s a cool request. I’m not sure when something like that would be possible, but I will chat with the team about it.

Cool, thanks @taylor. It’s something our success team is already working on building so will probably need to find a workaround if it’s a longer-term possibility. Can you replace the search service in Stoplight with a third party service e.g. Swiftype?

There’s been some teams who have explored implementing custom search. I’m checking to see if they went down that path…

Documentation is getting a revamp later this year and something like a search API would be potentially possible with it. What’s your timeline like?

Sorry for slow reply - we’re aiming for a rollout over the next week or 2. Currently looking at integrating Swiftype for search …

There might be a way with custom JavaScript, but we would need to do some more investigating.

Hey @ed.long, I’ve done some digging into Swiftype, and it looks like the Site Search functionality does work on Stoplight, but with some fairly big caveats:

  • It requires a Stoplight documentation plan with custom Javascript, as you have to include their JS widget.

  • It doesn’t look like versioned files are indexed. For example, if you offer multiple versions of your hub, only the latest version will be indexed.

  • It doesn’t look like the Swiftype crawler can index API documentation. I’m not able to get search working across any API endpoints (ie, searching for descriptions, object keys in a response body, etc). It works great for markdown and other free-form content, though.

  • You’ll have to disable the Stoplight search functionality with custom CSS and use the built-in Swiftype Site Search search tab option in the search customization section (or build your own search page/component). There may be a way to override the Stoplight search input, but I haven’t found a way to do it.

Hopefully that gives you some information to base a decision on. Let me know if you need me to clarify anything!

1 Like

Hey @ross - thanks for the pointers. This got a bit delayed with summer holidays and other priorities but hoping to take a look this week.

Yup, got this working in a basic way - will see what optimizations I can make and report back if it’s useful for others.