---
title: "How endpoints are ordered in your API Reference"
description: "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."
canonical_url: "https://help.brainfi.sh/articles/how-endpoints-are-ordered-in-your-api-reference-bG0Z93R2sL"
md_url: "https://help.brainfi.sh/articles/how-endpoints-are-ordered-in-your-api-reference-bG0Z93R2sL.md"
---
# 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.

```yaml
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.