> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/api-references/guides/openapi-layouts.md).

# OpenAPI layouts

When you insert an **OpenAPI Reference**, GitBook can organize operations in two ways.

Choose the layout that matches how you want people to browse your API.

### Access this setting

To choose a layout:

1. In your space, click **Add new\...** → **OpenAPI Reference**. You can also edit an existing OpenAPI Reference.
2. Choose your OpenAPI spec.
3. In **Page structure**, select **One page per tag** or **One page per operation**.

For the full setup flow, see [Insert API reference in your docs](/docs/api-references/openapi/insert-api-reference-in-your-docs.md).

### Available layouts

GitBook supports two layouts:

* **One page per tag** creates one page for each tag. Each page lists all operations with that tag.
* **One page per operation** creates one page for each operation. GitBook groups those pages by tag in the table of contents.

### Example input

Both layouts start from the same OpenAPI data:

{% code title="openapi.yaml" %}

```yaml
paths:
  /users:
    get:
      tags:
        - users
      summary: List users
    post:
      tags:
        - users
      summary: Create user
```

{% endcode %}

### One page per tag

Use this layout when each tag represents a clear section of your API.

It works well when you want overview pages, fewer entries in the navigation, and related endpoints on the same page.

With this layout, both operations appear on the same generated page for the `users` tag.

### One page per operation

Use this layout when you want direct links to individual endpoints.

It works well for large APIs, or when each endpoint needs its own page in the navigation.

With this layout, GitBook creates one page for `GET /users` and one page for `POST /users`. Both pages appear under the `users` tag group.

### Quick recommendation

Choose **One page per tag** for smaller APIs, or when each tag is a clear section.

Choose **One page per operation** for larger APIs, or when you want a dedicated page for each endpoint.

### Control the generated navigation

In both layouts, GitBook uses your OpenAPI tags to organize the reference.

To control order, hierarchy, page titles, icons, and descriptions, see [Structuring your API reference](/docs/api-references/guides/structuring-your-api-reference.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/api-references/guides/openapi-layouts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.