npm install
npm dev
The dev command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
The documentation website is hosted by AWS Amplify. All changes merged to the main branch are automatically deployed to docs.epilot.io
When documenting your APIs, it's possible to perform changes and eval how they look within the docs portal while running locally.
For that, all you need to do is follow the instructions below:
DOCS_URL=http://localhost:3001/ npm run devto run the docs portal locallynpm run swagger-ui:watchto serve your api docs locally on your API project- Finally to bypass CORS you will want to get this Chrome extension
When you are done, just deploy your openapi.yml as you normally would. And don't forget to update your client sdk here.
The site search is a local plugin in src/plugins/search:
indexer.jsruns afternpm run buildand writesbuild/search-index.json. It indexes every section of the rendered docs and changelog pages, and every operation of the OpenAPI specs listed inredoc.config.js.engine.jsranks results in the browser (BM25F with field weights, stemming, prefix and typo matching, title and phrase boosts).theme/SearchBaris the search dialog (Ctrl/⌘ Kor/).
The dev server (npm start) has no index of its own: it serves the one from the last npm run build.
After changing the ranking, verify it against the built index:
npm run build
npm run test:search # relevance checks
npm run test:search -- "webhook signature" # print the results of a queryTo keep an element out of the index, add a data-search-ignore attribute to it.
CHANGELOG.md is the source of the API changelog. The plugin in src/plugins/changelog turns every ## YYYY-MM-DD <API name> section into an entry, with an RSS feed.
Write each section as a list of changes, one bullet per change:
## 2026-10-23 Workflows Definition API, Workflows Execution API
- [New] [Action needed] **Pass the workflow's main context to automations** — Tasks and triggers can define which context an automation receives. Be prepared for the new `main_context` source value.
- Flow template tasks accept a new optional `tasks[].input_context` field on `POST /v2/flows/templates`
- Automation input contexts accept the new `main_context` value for `source`
- [Minor] `DELETE /v1/snapshots/{id}` can respond with `409` when a conflicting operation is in progress- Say what changed for the consumer first.
**Title** — summarytells a reader what they can now do or have to do. The endpoints, fields and values go into nested bullets, which are shown collapsed as "API details". - Tag every change.
[Breaking],[Action needed](not breaking by our rules, but consumers have to handle something, like a new enum value),[Deprecated],[New],[Changed],[Fix]or[Minor]. A change can have several tags. Changes are shown most important first. - One entry per change. When a change spans several APIs, write one section and name the APIs in the heading, separated by commas. Don't repeat the change per API.
- Roll up the small things. Optional fields, new response codes and similar additions that nobody has to act on go into a single
[Minor]line per section, without a title.
The changelog has two views:
/api/changelog, the default, lists the core API surface: the tier 1 APIs, core entities and core events. The change type pages (Breaking, Deprecated) cover the same./api/changelog/alllists every section.
An API is tier 1 unless it has tier: 2 in redoc.config.js. Tier 2 APIs are also grouped under "More APIs" in the API reference. An API that is in the changelog but not in redoc.config.js counts as tier 2. Section headings are matched to APIs by title, spec file name or route, see tiers.js. The RSS feed and the entry pages include every section.
Sections written before this format have no tags. Their tags are inferred from the wording ((breaking), "deprecated", "must be prepared", "New …"), see format.js.