API Reference

API Reference lets you build and publish a structured, public-facing API reference directly inside Hyperdocs. You define your APIs, document their endpoints, parameters, request bodies, responses, and code samples in the admin editor, then publish the result alongside your product docs, changelog, and help center — all on the same site.

How It Works

The API Reference editor lives at API Reference in your admin sidebar. It has two modes you switch between using the Edit and Preview buttons in the header:

•Edit mode is where you build your reference. A sidebar lists your API definitions, versions, and every category and endpoint. Selecting an item in the sidebar opens its editor in the main panel.

•Preview mode renders the full public-facing API reference exactly as visitors will see it, so you can review layout and content before saving.

A global Enabled / Disabled toggle in the header controls whether the API Reference tab appears on your public site. When disabled, the tab is hidden from visitors but your content is preserved in the editor.

Admin Editor Structure

The editor is organized into four sections, each accessible from the sidebar: API Definitions, Authentication, Versions, and individual Endpoints grouped under categories.

API Definitions

An API definition is the top-level container for one API. Each definition has a title and a base URL (for example, `https://api.example.com`). You can have more than one definition in a workspace — each appears as a separate selectable API in the sidebar.

Each definition card also has an API Explorer toggle. When on, a live Try It console is shown to visitors on each endpoint page, letting them send real requests from the browser.

To create a definition, click New Definition, enter a title and base URL, and save. To delete one, use the delete button on its card — at least one definition must always remain.

Authentication

The Authentication section lets you define reusable authentication methods that can be attached to individual endpoints. Two types are supported:

•API Key — a key sent in a request header or query parameter. You set the Type to `apiKey`, the Location to `header` or `query`, and the Key Name (for example, `x-api-key`).

•Bearer Token — a token sent in the `Authorization` header. You set the Type to `bearer` and the Key Name to `Authorization`.

Add a method using the + API Key or + Bearer Token buttons. Each method has an editable name. Methods you create here become available to attach to any endpoint via the Credentials panel in the endpoint editor.

Versions

The Versions section lists the API versions for the selected definition. Each version has a name (for example, `v1.0`) and three settings you can toggle:

•Deprecated — marks the version as deprecated for visitors.

•Visibility — controls whether the version is shown as Default, Public, or Hidden on the public site.

The active version is selected from the version dropdown at the top of the sidebar. The selected version determines which version prefix appears in endpoint URLs on the public site.

Categories and Endpoints

Endpoints are organized into categories. A category groups related endpoints under a shared name and slug, which becomes the URL path on the public site (for example, `/api-reference/users`).

To add a category, click the + button next to the Categories heading in the sidebar and enter a name. To add an endpoint inside a category, select the category and use the + button next to it.

Each endpoint has the following fields you edit in the main panel:

•Title — the human-readable name shown in the sidebar and on the public endpoint page.

•HTTP method — select from `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`, or `TRACE` using the method dropdown. Each method is color-coded.

•Path — the endpoint path appended to the base URL, for example `/users/{id}`.

•Description — a plain-text summary of what the endpoint does.

•Visibility — set to public to show the endpoint to visitors, or private to hide it from the public site while keeping it in the editor.

•Content — a rich block editor area where you can write longer documentation for the endpoint, using headings, paragraphs, lists, blockquotes, and code blocks.

Endpoint Detail Sections

Each endpoint editor has additional sections in the right-hand panel for documenting the full contract of the endpoint.

Parameters

Parameters are grouped into three types: Path Parameters, Query Parameters, and Header Parameters. For each parameter you set:

•Name — the parameter key as it appears in the request.

•Data type — choose from types including `string`, `number`, `integer`, `boolean`, `array`, `object`, and format variants such as `date`, `date-time`, `password`, `byte`, `binary`, and `json`.

•Required / optional — click the label to toggle whether the parameter is required.

•Default value — an optional default shown in the public reference.

•Description — a short explanation of what the parameter does.

•Enum values — an optional list of allowed values. Click the enum control to add or remove values; they are displayed as chips on the public endpoint page.

Request Body

Click Add request body to attach a request body to an endpoint. The request body has a content type field (for example, `application/json`) and an example field where you enter a JSON object. The example is shown to visitors on the public endpoint page.

To remove the request body, click Remove in the section header.

Responses

Add one or more response definitions using the + Add Response button. For each response you select a status code from a picker organized by category (success, warning, error). Each response also has a content type and a JSON example that visitors can expand to read.

Response rows are color-coded by category: green for success (2xx), amber for redirects and warnings (3xx), and red for errors (4xx / 5xx).

Credentials

The Credentials panel lets you attach authentication methods to the endpoint. Click + to open a picker showing the auth methods you defined in the Authentication section. Attached methods are listed on the public endpoint page under the authentication details. Click the remove button on an attached method to detach it.

Custom Code Samples

The Custom Code Samples section lets you add language-specific code examples for the endpoint. Click + to pick a language (Shell, JavaScript, Python, PHP, Go, Java, C#, C++, PowerShell, Ruby, or Swift), then type or paste the code into the editor area. Multiple languages appear as tabs that visitors can switch between.

Public Visitor Experience

When the API Reference is enabled, it appears as a tab on your public documentation site. The public view has a left sidebar listing all categories and their endpoints. Visitors can:

•Browse categories — clicking a category shows a list of its public endpoints with their HTTP method badge and path.

•Open an endpoint — clicking an endpoint shows its full detail page: title, method, path, description, parameters table, request body example, response examples, authentication details, and code samples.

•View authentication — the Authentication page in the sidebar lists every auth method with its type, location, key name, and a formatted example header or query string.

•Only endpoints with Visibility set to public appear on the public site. Endpoints set to private are visible in the admin editor but hidden from visitors.

Saving Changes

Changes to definitions, authentication methods, versions, and endpoint content are saved by clicking Save in the header. The Save button is context-aware:

•When API Definitions is selected in the sidebar, clicking Save saves all definition titles, base URLs, and API Explorer settings.

•When Authentication is selected, clicking Save saves all auth methods for the current definition.

•When Versions is selected, clicking Save saves all version names, deprecated flags, and visibility settings.

•When an endpoint is selected, clicking Save saves the entire category — including all its endpoints, parameters, request bodies, responses, and code samples — in a single operation.

The button label changes to Saving… while the request is in flight and to Saved briefly after a successful save. The public API reference cache is refreshed automatically after each save so visitor-facing pages reflect your changes immediately.

Role-Based Access

Access to the API Reference editor is controlled by your workspace role:

•Admin and Editor roles can view the editor, add and edit all content, and toggle endpoint visibility.

•Viewer role can open the editor and read all content but cannot create, edit, delete, or save anything. All input fields and action buttons are disabled for Viewers.

•Only Admins can toggle the global Enabled / Disabled switch that controls whether the API Reference appears on the public site.

Steps to Build and Publish an API Reference

•Open your admin dashboard and select API Reference from the sidebar.

•In the sidebar, select API Definitions. Click New Definition, enter a title and base URL, and save.

•Select Authentication and add any auth methods your API uses — click + API Key or + Bearer Token, fill in the fields, and save.

•Select Versions to review or rename the default version. Set its Visibility and Deprecated flag as needed, then save.

•In the sidebar, click + next to Categories to create your first category. Give it a clear name that describes the group of endpoints it will contain.

•Select the category and click + to add an endpoint. Set the title, HTTP method, path, description, and Visibility to `public`.

•In the endpoint editor, add Parameters, a Request Body, Responses, Credentials, and Custom Code Samples as needed.

•Click Save to persist the endpoint and its category.

•Repeat for each category and endpoint in your API.

•Switch to Preview mode using the button in the header to review the public layout. Confirm that categories, endpoints, parameters, and examples appear as expected.

•Return to Edit mode and turn on the Enabled toggle in the header to make the API Reference visible on your public site.