Overview

Every endpoint page in your API reference shows a request example with code samples and the example responses from your spec. The Try it button opens the API playground, where readers fill in parameters and, in relay mode, send a real request to your API.

You set the playground and the code samples for each API version on the version's Settings tab, which shows these settings once the version is published. To choose relay mode or change the allowed servers, you also need the Manage API permission in addition to Manage Help Center, as described in Admin roles.

Choose a Try it mode

Try it mode decides what the Try it button does on every endpoint page of the version:

In relay mode, the API keys that readers type pass through the Featurebase relay on their way to your API.

Set up Try it

Set the mode and allowed servers

1. Go to Settings → Help Center → API reference

2. Open the API version and its Settings tab

3. Under Try it, choose a Try it mode

4. Under Allowed servers, select each server readers may call

5. Click 'Save settings'

The list shows the servers from your spec. Only public HTTPS servers on the standard port (443) can be allowed. If the spec has no servers, Try it shows samples only.

Test the connection

After you save, click 'Test connection' next to an allowed server. Featurebase sends one request without credentials and shows three checks:

• Reachable: The server answered. A 401 or 403 answer is normal without an API key

• TLS: The server's certificate is valid

• Relay: The relay can send to this server from your Workspace

The result recommends a mode. If it differs from the current mode, click 'Use Relay' or 'Use Samples only' in the result, then click 'Save settings'.

Choose the code samples

The Code examples section on the same Settings tab controls the request example on every endpoint page and in the playground:

• Example languages: Choose from cURL, JavaScript, Python, PHP, Go, Java, Ruby, C#, and TypeScript. New versions start with cURL, JavaScript, and Python, and at least one language must stay on

• Example defaults: Choose All parameters or Required only for the parameters the generated examples include. The playground uses this until a reader types a value

• Expand child attributes: Under Parameters, open nested object fields by default

Click 'Save settings' to apply your changes.

To show your own samples, add x-codeSamples (or x-code-samples) to an operation in your spec. Each entry needs a lang and a source, with an optional label. These samples appear first in the language switcher, before the generated ones.

What readers see

On an endpoint page

The request example sits next to the endpoint description, with a language switcher and a copy button. The language a reader picks stays selected on other endpoint pages in the same browser. Below it, the response examples show one tab per documented status code.

Readers can also save the OpenAPI file of the version they are viewing with 'Download spec' in the page actions menu.

In the playground

The playground lists the endpoint's Authorization, Path, Query, Header, and Body fields, a live code sample, and a server picker when the spec has more than one server. After Send, readers see the status, time, size, body, and headers of the response.

The playground supports:

• Authentication: Basic auth, bearer tokens, and API keys in a header or query parameter. OAuth 2.0 and OpenID Connect work by pasting an access token

• Requests: Path, query, and header parameters, JSON bodies, form fields, and plain-text bodies

• Sizes: Request bodies up to 256 KB, and up to 2 MB of each response

Cookies are removed before a request reaches your API, so cookie parameters and cookie-based API keys do not work. File uploads, streamed responses, and private or local servers are not supported.

FAQs