API Documentation

API Documentation in Treblle uses your OpenAPI specification, which can be generated by Treblle from available traffic or uploaded to Platform. Additionally, there is a robust Guides Editor that allows users to create custom pages to extend the specification and explain in detail specificities of the API. This page explains how to manage your OpenAPI specifications, understand the generated documentation, and use the Guides Editor to extend your docs.

Overview

When you open API Documentation from the left sidebar (under Documentation), you will see two main sections:

• OpenAPI Specification — displays the current default specification used to render your API docs.
• OpenAPI Specifications — a full list of all specification files that have been uploaded or generated for this API.

The default specification is highlighted with a DEFAULT badge. Only one specification can be set as the default at a time. The default specification is what consumers see when they visit your published API documentation.

Adding a New OpenAPI Specification

You can add a new OpenAPI specification in a number of ways: by uploading a file manually, or by having Treblle generate one from Platform traffic (if available). In this first release only manual upload and Platform generated specifications are possible, we will be adding CLI tool as well as a fully new Visual Studio Code plugin that will also be enabled to upload a specification.

Uploading a Specification

1. Navigate to API Documentation in the left sidebar.
2. Click + New OpenAPI Spec in the top-right corner of the OpenAPI Specifications table.
3. Select Upload from the dropdown.
4. In the Upload New OpenAPI Spec dialog, drag and drop your file into the upload area, or click the area to browse and select a file.
5. Click Upload to confirm.

Treblle supports OAS Version 3.x.x in both JSON and YAML formats.

Uploaded specifications will appear in the table with the source listed as User Upload, along with the uploader’s name and the date of upload.

Generating a Specification from Traffic

Treblle can automatically generate an OpenAPI specification by using the traffic available on Platform.

1. Click + New OpenAPI Spec and select Generate from the dropdown.
2. In the Generate OpenAPI Specification dialog, review the Specification Version field. It is pre-filled with the next suggested version number (e.g. 1.4.2). Update this value if needed.
3. Click Generate to start the process.

Generation runs in the background. A progress indicator will appear in the top-right area of the specifications table showing the current completion percentage (e.g. Generating… 30%). You can navigate away and return to this page to check the results once generation is complete.

Generated specifications will appear in the table with the source listed as Treblle Generated.

The OpenAPI Specifications Table

The specifications table lists all versions associated with your API. Each row displays the following columns:

Each row has two action icons on the right:

• Eye icon — preview the specification’s generated documentation.
• Three-dot menu — access additional actions including setting as default or deleting.

You can search across all specifications using the search bar above the table. Pagination controls at the bottom allow you to navigate large lists and adjust how many rows are shown per page.

Governance Score

Every specification in Treblle — whether manually uploaded or automatically generated — receives a Governance Score upon processing. The score reflects how well the specification adheres to design-time governance rules and appears as a letter grade alongside a numeric value out of 100. Design-time governance evaluates different aspects, all covered on API Governance page. The score is calculated automatically each time a specification is uploaded or generated, and is visible in the OpenAPI Specifications table.

Deleting a Specification

Warning: Deleting the default specification will make your API documentation invisible to consumers until a new default is assigned.

1. Click the three-dot menu on the specification row you want to remove.
2. Select Delete.
3. In the Delete OpenAPI Specification dialog, type DELETE in the confirmation field.
4. Click Delete to permanently remove the specification.

To cancel without deleting, click Cancel or the × icon to close the dialog.

Viewing Generated API Documentation

Treblle automatically generates documentation from your default OpenAPI specification, enriched with any custom made guide page.

To open the documentation, click View API Documentation on the default specification card at the top of the API Documentation page.

The generated documentation includes:

• API Overview — shows the base URL, key statistics (number of endpoints, number of consumers, average response size, average load time), and a download link for the OpenAPI specification. Base information like URL and number of endpoints is taken from the OpenAPI specification itself, while other data is pulled from Platform traffic, if there is any. Metadata such as category, environment, type, technical owner, business owner, and tags is displayed in a sidebar.
• Endpoint Reference — each endpoint is listed in the left sidebar, grouped by resource (e.g. Users, File Upload, Databases, Blocks). Selecting an endpoint shows its HTTP method, path, request body parameters, and response schema. Required fields are clearly marked. In the next iteration of our documentation, we will add an interactive Try It panel on the right allows consumers to execute requests directly from the documentation and view live responses.

Sources for OpenAPI Specifications

Specifications can reach Treblle from several sources:

• User Upload — manually uploaded via the Treblle web interface.
• VS Code — pushed directly from the Treblle VS Code extension.
• CLI — uploaded via the Treblle command-line tool, suitable for local or scripted workflows.
• CI/CD — automatically pushed as part of a continuous integration or delivery pipeline.
• Treblle Generated — created by Treblle based on observed API traffic.

The source is recorded against each specification in the table and is visible in the default specification card.

Guides Editor

The Guides Editor lets you create supplementary written guides that appear alongside the auto-generated endpoint reference in your documentation. Guides are useful for explaining authentication flows, onboarding steps, conceptual context, or any information that goes beyond what an OpenAPI specification can describe.

Accessing the Guides Editor

1. In the left sidebar, click Guides Editor under the Documentation section.
2. The editor opens with a list of existing guides in the left panel. A default empty screen is the starting point.

Adding a New Guide

Click + Add Guide in the top-left of the editor to create a new guide. It will appear in the left panel as New Guide. Click the guide name to open and begin editing it.

Editing Guide Content

The editor provides a rich text interface. To add content to a guide:

• Click anywhere in the editor body and start typing.
• Use the formatting toolbar at the top to apply styles: Bold, Italic, Underline, Strikethrough, Inline Code, and hyperlinks.
• Use the block type dropdown (defaulting to Text) to change the current block to a heading level or other type.

To insert a new content block, click the + icon that appears to the left of any line, or type / to open the block menu. The block menu provides the following options:

The Attach File and Add Image are yet to be aded to the Editor.

The On This Page panel on the right automatically generates a table of contents from the headings in your guide.

Previewing and Saving

• Click Preview in the top-right toolbar to see how the guide will appear to consumers.
• Click Save Changes to publish your edits. An Unsaved changes indicator will appear in the toolbar whenever there are pending changes that have not yet been saved.

Exiting the Editor

Click ← Exit Editor in the top-left to return to the main API Documentation view.