How endpoints are ordered in your API Reference

When you connect an OpenAPI (OAS) catalog to your help center, Brainfish builds the API Reference sidebar directly from your spec. This article explains exactly how endpoints are ordered inside each tag (or tag group), and how to control that order.

TL;DR

Inside an OAS catalog, the sidebar is organised as:

Group → Tag folder → Endpoints

Ordering is driven by your OpenAPI spec, with one Brainfish convention applied: within each tag, write operations are listed before read operations. This matches the convention used by tools like Readme, where list/fetch endpoints appear at the bottom.

The four ordering layers

1. Top-level groups — x-tagGroups

If your spec includes the Redocly x-tagGroups extension, Brainfish renders one top-level folder per group, in the exact order of the array.

x-tagGroups:
  - name: Core
    tags:
      - Orders
      - Customers
  - name: Webhooks
    tags:
      - Events

To reorder groups, reorder the entries in x-tagGroups.

2. Tag folders inside a group

Within each group, tag folders follow the order of the tags array on that group entry. In the example above, Orders will always appear above Customers under Core.

If your spec does not define x-tagGroups, Brainfish falls back to a single-level layout: one folder per tag, in the order tags are first encountered while walking paths.

3. Endpoint order within a tag — writes before reads

This is the one Brainfish convention layered on top of the spec.

Within each tag folder, endpoints are split into two buckets:

• Writes — POST, PUT, PATCH, DELETE, OPTIONS
• Reads — GET, HEAD

All writes are listed first, then all reads. So a GET /orders will always sit below a POST /orders in the same tag, regardless of the order they appear in your spec.

4. Within writes (and within reads)

Inside each bucket, endpoints follow:

1. The order paths appear in your spec's paths object.
2. The order methods appear on each path object.

So if you want a specific POST /orders/refund to appear above POST /orders, just declare the /orders/refund path first.

How to reorder endpoints

You want to reorder…	Do this
Top-level groups	Reorder entries in x-tagGroups
Tag folders within a group	Reorder the tags array on that group
Tag folders (no x-tagGroups)	Reorder the paths so the first hit on a tag determines its position
Endpoints within a tag (same bucket)	Reorder the paths and/or methods in your spec
A GET to appear above a POST in the same tag	Not possible today — split them into different tags

What about untagged operations?

If an operation has no tags, Brainfish falls back to grouping by the first segment of the URL path. For example, GET /paypal/orders would be placed under a folder called Paypal.

Common questions

Can I set a per-endpoint sort order via an extension like x-order? Not today. Ordering is fully spec-driven, plus the writes-before-reads rule.

Can I disable the writes-before-reads rule? Not via configuration. If preserving exact spec order is important to you, let us know — it's a small change and we're tracking demand.

My endpoint appears in two tags. Will it show up twice? Yes — and that's intentional. Each tag folder contains an independent copy with a unique sidebar ID, so highlighting and deep links work correctly in both places.

Section ordering vs. endpoint ordering

Note that the section bar (e.g. Guides, API Reference) and the items inside a section (CMS collections + OAS catalogs) are ordered by your platform's site sections API, not by OpenAPI. This article only covers ordering inside an OAS catalog — i.e., what you see when you open an API Reference section.