For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Slack communityLog inBook a demo
  • Getting Started
    • Overview
    • Quickstart
    • Customer Showcase
  • Writing Content
    • Markdown
    • Visual Editor
    • Reusable Markdown
    • Custom React Components
      • Generate API Reference
      • SDK Snippets
      • HTTP Snippets
      • Endpoint Errors
      • Audiences
      • Customize API Reference Layout
      • Write Markdown in API Reference
      • Generate Webhook Reference
      • Multiple Server URLs
      • Generate WebSocket Reference
      • Generate OpenRPC Reference
    • Changelog
LogoLogo
Slack communityLog inBook a demo
On this page
  • Ordering the API Reference
  • Alphabetizing endpoints and sections
  • Ordering top-level sections
  • Ordering section contents
  • Customizing the API Reference
  • Flattening sections
  • Styling endpoints
  • Hiding endpoints
  • Adding custom sections
  • Adding a section overview
  • Adding pages and links
  • Disable long-scrolling
API References

Customize API Reference layout

Was this page helpful?
Previous

Write Markdown content in your API Reference

Next
Built with

When you include an API in your docs.yml file, you can customize how the endpoints and sections are displayed in the sidebar navigation. By default, the reference will generate a navigation hierarchy based on the structure of the API spec, but several customizations can be configured.

API Sections

If you are using an OpenAPI Specification, sections are created based on the tags property, converted to lowerCamelCase convention (e.g., createUser). If you are using a Fern Definition, sections are created based on the service file names.

If you would like to only display a subset of endpoints, read more about the Audiences property for OpenAPI Specifications or Fern Definitions.

Ordering the API Reference

Alphabetizing endpoints and sections

To sort all sections and endpoints alphabetically, unless explicitly ordered in layout, set alphabetized to true.

docs.yml
1navigation: 
2  - api: API Reference
3    alphabetized: true

Ordering top-level sections

The layout option allows you to specify the order of sub-packages, sections, endpoints, and pages at the top level of your API Reference.

OpenAPI Specification
Fern Definition
docs.yml
1navigation: 
2  - api: API Reference
3    layout: 
4      - POST /user
5      - user
6      - store
7      - plant
Ordered API Reference

Ordering section contents

Adding a : after the section name allows you to specify the order of its nested sub-packages and endpoints.

Referencing Endpoints

To reference an endpoint, you can use either:

  • METHOD /path/name (best for OpenAPI Specification)
  • serviceName.endpointName (best for Fern Definition)
OpenAPI Specification
Fern Definition

You can reference an endpoint using the format METHOD /path.

docs.yml
1navigation: 
2  - api: API Reference
3    layout: 
4      - user: 
5          - POST /user
6          - PUT /user/{username}
7          - DELETE /user/{username}
Content ordered in the API Reference

Customizing the API Reference

Flattening sections

To remove the API Reference title and display the section contents, set flattened to true.

docs.yml
1navigation: 
2  - api: API Reference
3    flattened: true
Flattened API Reference

Styling endpoints

To customize the display of an endpoint, you can add a title. You can also use slug to customize the endpoint URL.

OpenAPI Specification
Fern Definition
docs.yml
1navigation: 
2  - api: API Reference
3    layout: 
4      - user: 
5          - endpoint: POST /user
6            title: Create a User
7            slug: user-creation
8          - DELETE /user/{username}
Setting an endpoint title

Hiding endpoints

You can hide an endpoint from the API reference by setting hidden to true. The endpoint will still be accessible at its URL.

OpenAPI Specification
Fern Definition
docs.yml
1navigation: 
2  - api: API Reference
3    paginated: true
4    layout: 
5      - user: 
6          - endpoint: POST /user
7            title: Create a User
8            slug: user-creation
9          - endpoint: DELETE /user/{username}
10            hidden: true
Fully hidden endpoints

For best results, API References with hidden endpoints should use the paginated: true configuration to avoid discovering endpoints from long-scrolling.

Adding custom sections

You can add arbitrary folders in the sidebar by adding a section to your API Reference layout. A section can comprise entire groups of endpoints, individual endpoints, or even just Markdown pages. Sections can be customized by adding properties like a icon, summary, slug (or skip-slug), and contents.

OpenAPI Specification
Fern Definition
docs.yml
1navigation: 
2  - api: API Reference
3    layout: 
4      - section: My Section
5        icon: flower
6        contents: 
7          - PUT /user/{username}
8          - plant
9          - plantInfo # tag names are converted to camelCase convention
Custom section in the API Reference

Adding a section overview

The summary property allows you to add an .md or .mdx page as an overview of the API Reference or a section.

docs.yml
1navigation: 
2  - api: API Reference
3    summary: pages/api-overview.mdx
4    layout: 
5      - user: 
6          summary: pages/user-overview.mdx
API Reference with a summary page

Adding pages and links

You can add regular pages and external links within your API Reference.

docs.yml
1navigation: 
2  - api: API Reference
3    layout: 
4      - user: 
5          contents: 
6            - page: User Guide
7              path: ./docs/pages/user-guide.mdx
8            - link: Link Title
9              href: http://google.com

Disable long-scrolling

By default, the API Reference renders all endpoints on a single page (long-scrolling). To create separate pages for each endpoint, set paginated: true.

docs.yml
1navigation: 
2  - api: API Reference
3    paginated: true