Current
API playground proxy
How the Try it panel sends API requests in proxy or browser mode and what each mode means for keys
Overview
The Try it panel on an API reference page sends a request to your API from your published docs. It sends the request in one of two ways. The mode decides whether your API needs CORS setup and whether the reader's API key passes through Doxa.
| Mode | Who sends the request | CORS needed on your API | Where the API key goes |
|---|---|---|---|
| Proxy (default) | The doxa-try-proxy Worker | No | Passes through Doxa in memory |
| Browser | The reader's browser | Yes | Goes from the browser to your API and never passes through Doxa |
Proxy mode
Proxy mode is the default. Readers do not need any setup for it to work, and your API does not need to allow requests from your docs domain.
When a reader selects Send, the panel does the following:
It reads the playground configuration. The answer gives the mode, the target host, and a
targetId.It posts the method, the path, and the
targetIdto the docs site. The request has no URL or host field, so the reader cannot choose where it goes. Doxa refuses the send if thetargetIddoes not match the current target.Doxa checks the request. It applies the kill switch, the target rules, the blocklist, and the limits. It then builds a new URL and new headers and sends the request to the API base URL in your site settings.
The panel shows the raw body that your API returned, along with its status and headers.
If the response has no x-doxa-try-result header, Doxa refused the request and did not send it to your API. If that header is present, the status and headers in it come from your API.
Browser mode
In browser mode, the reader's browser sends the request directly to your API. Use this mode only when your API already allows cross-origin requests from your docs site.
Your API must return CORS headers that allow the docs origin. Without them, the browser blocks the response, and the panel cannot show it.
Keys in browser mode:
In browser mode the key goes from the reader's browser straight to your API, and Doxa never sees it. In proxy mode the key passes through Doxa in memory while the request is forwarded. Do not put production keys in examples or page text.
Where requests go
Requests go only to the API base URL set in your site settings.
The
baseUrlshown on an endpoint page appears in the request samples. It does not decide where a reader's request is sent.Keep the base URL in your site settings and the URL in your examples the same, so readers can copy working requests.
Panel behavior
| What the reader sees | Cause | What happens next |
|---|---|---|
| A message that the playground is off | The playground is turned off for the site | The panel shows no Try it request |
| The key is cleared and Send is disabled, with a request to reload | The host in the configuration differs from the page's base URL | Reload the page to get the current configuration |
The panel shows no note about the mode or about a preview. It shows a message only when the playground is off.