Exposing Your APIs with openapi.json
To make your documentation content accessible to AI tools, search engines, and developer platforms like Microsoft Copilot, it's helpful to provide a machine-readable API specification using the openapi.json format. This allows external systems to understand how to interact with your help content programmatically.
What is openapi.json?
openapi.json is a standard file based on the OpenAPI Specification that describes an API's endpoints, parameters and responses in a structured JSON format. It's widely supported by developer tools, SDK generators and AI platforms.
Why Publish an openapi.json File?
- Lets Microsoft Copilot, ChatGPT and other AI tools search your help content
- Helps developer tools generate clients automatically
- Gives third-party systems a clear way to query your documentation
- Complements your ai.txt file for AI crawler support
HelpGuides Support for openapi.json
HelpGuides generates an openapi.json file for your site automatically. It describes your site's public search API, so AI platforms and other tools can search your published articles. It's at the root of your site. For example:
https://docs.helpguides.io/openapi.json
The search API
The API has one endpoint. It needs no authentication and only returns published articles.
| Parameter | Required | Description |
|---|---|---|
s | Yes | What to search for. Start with keyword: to match exact words instead of meaning. |
article_only | No | true to return each article once. By default, results are sections of articles, so an article can appear more than once. |
It returns up to 10 results. Each has the article's postuid, title, slug, status, the matching section and its anchor, the section's content, an excerpt with matches highlighted, and the date it was last updated:
This endpoint returns articles only; it doesn't write an AI answer. For answers, see AI Answers on Your Help Site. To let an AI assistant read and edit your documentation, see Model Context Protocol.