API playground

The API playground lets readers call your API from the docs, with a live request drawer on each endpoint. It is off by default, so check its settings and then turn it on.

Find it in Docs settings, under Playground.

Setting it up

Check where your API lives

Under API server, set the base URL, auth scheme and auth header name. Octri fills these in from your spec when it can. The playground and the generated SDKs both start from these values, so the try-it button and the SDK you ship point at the same place.
Turn it on

Under Playground, turn on Enable API playground.

Settings

Changes apply as soon as you save, without a publish. Each setting names its key under playground in octri.json, and the key octri docs playground set takes.

Enable API playgroundon or offdefault: off

Shows Try it on endpoint pages.

enabled · CLI enabled

Base URLURLdefault: your API server

Where playground requests go. Empty follows your project's API server, as your SDKs do. Point it at a sandbox to keep test traffic off production.

baseUrl · CLI baseUrl

Default auth schemechoicedefault: Project default

The credential the auth form asks a reader for.

Value	Studio label	The reader enters
`inherit`	Project default	Whatever your API server settings use
`none`	None	Nothing
`apiKey`	API key	A key, sent in the Auth header name
`bearer`	Bearer token	A token, sent as `Authorization: Bearer`
`basic`	Basic	A username and password
`oauth2`	OAuth 2.0	An access token

auth.type · CLI defaultAuth.type

Auth header nametextdefault: Authorization

The header an API key is sent in, such as X-API-Key.

auth.headerName · CLI defaultAuth.headerName

Allowed originslist of URLsdefault: none

Sites besides your docs that may send requests through the playground, such as your own site embedding it. Up to 20, each a full origin like https://acme.com.

allowedOrigins · CLI allowedOrigins

Request timeout (ms)numberdefault: 10000

How long a request may run before it's abandoned, from 1000 to 60000 milliseconds.

timeoutMs · CLI requestTimeoutMs

Where requests go

Octri picks the address in this order:

The playground's own base URL
Your API server base URL
The servers declared in your spec. A reader can choose between them

A request can only go to that address. Anything else is refused.

How requests reach your API

Playground requests go through Octri's server rather than directly from the reader's browser. That means:

Your API needs no CORS setup for the playground to work.
Your API sees requests from Octri's server, not the reader's address. If your API allows only certain IP addresses, playground requests will be refused. Point the playground at a sandbox instead.

Limits

To protect your API, each reader can send 10 requests a minute per project, and each IP address 30 a minute. Past that, the playground returns a 429 until the window resets.

Authentication

Readers enter their own credentials to try a request. The schemes come from your spec. See SDK authentication for how Octri reads them.

Use a sandbox if you can

Readers are calling a real API with real credentials. Pointing the playground at a sandbox lets them experiment without any risk to live data.

Examples

A playground pointed at a sandbox, with keys sent in their own header:

"playground": {
  "enabled": true,
  "baseUrl": "https://sandbox.acme.com/v1",
  "auth": { "type": "apiKey", "headerName": "X-API-Key" },
  "timeoutMs": 20000
}

octri docs playground set enabled=true baseUrl=https://sandbox.acme.com/v1 defaultAuth.type=apiKey defaultAuth.headerName=X-API-Key

Who can use it in the dashboard

Members need the API playground permission to run requests in the dashboard. See organizations and roles.

From the CLI

octri docs playground shows the playground's settings, and octri docs playground set changes them, such as enabled=true or the baseUrl it calls.