> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Playground

> Use the API Playground to edit, send, debug, and promote cataloged API requests. Follow the request-to-scenario workflow.

# API Playground

The API Playground is a Postman-style request runner inside Qodex.

Use it to explore endpoints by hand, debug imported requests, verify payloads, and promote a working request into a reusable scenario.

## What to use it for

The Playground is useful for three jobs:

1. **Exploration.** Hit endpoints by hand while the agent is reasoning about them, without leaving the app.
2. **Verification.** Re-run a captured request from a collection or test run to sanity-check behavior before generating a scenario.
3. **Authoring handoff.** Save a working request, then click **Generate tests** on its endpoint in the API catalog. Qodex opens a chat grounded on that exact endpoint row, so the agent starts from a request that already works instead of re-deriving it.

## Where to find it

The Playground has no sidebar row of its own. Open **API** under **Context** in the sidebar, then click **Open playground** in the page header for a blank request, or open an endpoint and click **Open in playground** to load it.

## How it works

Every endpoint the catalog knows about is editable in the Playground at `/p/<slug>/playground/<endpointId>`. The catalog row and the Playground row are the same row. Edit one and the other updates.

When you click **Send**, Qodex executes the request through the same HTTP executor used by the agent's `api_call` tool. The Playground and the agent see the same request behavior.

### Request tabs

| Tab | Edits |
| - | - |
| **Params** | Query and path parameters. Repeated keys serialize as `?tag=a&tag=b`. |
| **Headers** | Request headers, enabled or disabled per row. |
| **Body** | One of: `none`, `json`, `text`, `xml`, `form-urlencoded`, `multipart`, `binary`, `graphql`. Content-Type auto-sets per mode. |
| **Auth** | `none`, `inherit`, `basic`, `bearer`, or `apiKey`. `inherit` falls through to the collection's default auth. |
| **Post** | Postscript rules that capture values from the response into environment variables. See [Chaining and postscripts](https://qodex.ai/docs/api-testing-chaining.md). |
| **Settings** | Per-request execution settings. |

### Response tabs

| Tab | Shows |
| - | - |
| **Pretty** | Rendered JSON, XML, or text, with fold arrows on JSON and XML. GraphQL errors surface as a callout above the data block. A binary response shows its size instead. |
| **Raw** | Raw response body. |
| **Headers** | Response headers. |
| **Request** | The request exactly as it was sent: method, final URL, headers, and body, with variables and auth resolved. Use it to see which URL and token a failing call actually used. |
| **Timeline** | Per-phase timing: prepare, connect, request sent, time-to-first-byte, response received, done. |

On **Pretty** and **Raw**, icon buttons above the body let you search the response (Ctrl+F), copy the body, and download it as a file. A binary response downloads as its original bytes.

The **Request** tab is empty for a request sent through the Chrome extension or one stopped before it went out.

### Variable interpolation

Use `{{var}}` (or legacy `${VAR}`) anywhere in URL, headers, body, params, or auth. The executor resolves against the active environment at send time. Unresolved tokens stay as-is and surface a warning in the timeline; they do not fail the request.

Type `{{`, `${`, or `{` in a Playground field to get a list of the active environment's variables, and pick one to insert the full reference. In the Bearer token field, auth profiles are offered as one-click tags.

Every variable the request references appears as a chip below the URL bar. A resolved chip shows its value on hover; a chip for an auth profile token says it is resolved at send time. An unresolved chip is highlighted: click it to add the variable to the current environment.

Path variables have their own rows in the **Path variables** section of the Params tab. If the URL contains a path token such as `/users/:userId` or `/users/{id}`, fill it there and Qodex resolves the final request before sending. A value typed in the row wins over an environment variable of the same name. Leave the row empty to use the environment value; the row then says "from environment".

When a token is still unresolved, the Playground keeps it visible instead of silently replacing it. Add the value to the current environment, choose a different auth profile, or correct the variable name before relying on the request in a scenario.

### Environment switcher

Swap the active environment from the dropdown next to **Send**. Choose **No env** to send without environment variables. Same request, different base URL and credentials. The host-name indirection means a request that targets `${API_BASE_URL}/users` resolves correctly against every environment that declares a host named `api`.

## Deep-linkable URLs

Every saved endpoint has a stable URL:

```
/p/<project-slug>/playground/<endpointId>
```

Open the catalog, click **Open in playground**, and land directly on the editable request. Click **Share link** next to a saved request's name to copy its URL, then paste it into chat or a ticket and the recipient gets the same view.

Ad-hoc requests live at `/p/<slug>/playground` until you save them. Click **Save...**, name the request, and Qodex creates a catalog row with a permanent ID and a permanent URL.

## Delete a saved request

Open the saved request in the Playground, click **Delete** next to its name, then confirm **Delete**. Qodex removes the saved request and returns you to a new, unsaved request.

Use this only for requests you no longer want in the catalog. To keep the request but change its label, click its name to rename it. To make a variant, click **Duplicate**.

## cURL import and export

* **Import**: click **cURL↓** (Import cURL), paste a `curl ...` command, and click **Import**. The Playground parses method, URL, headers, body, and basic auth, and prefills the form.
* **Export**: click **cURL↑** (Copy as cURL) to copy a runnable command for the current request, resolved with the active environment. Auth profile tokens and inherited collection auth are filled in the same way **Send** fills them. A variable that cannot be resolved stays as its `{{placeholder}}` instead of becoming an empty string, so a missing value is easy to spot. GraphQL bodies serialize as a JSON payload on copy, so the cURL works against the same endpoint without further translation.

## Localhost targets

The hosted runner cannot reach `localhost` or other private addresses on your machine. When a request targets one, the Playground asks you to install the Qodex Chrome extension, which sends the request from your browser instead.

## When to use it

* Use it to explore an unfamiliar API while you decide what to test.
* Use it to reproduce a flaky scenario by hand and see what changed.
* Use it to sanity-check a request body before asking the agent to author from it.
* Use it to build a request iteratively, then save it and generate tests from it.

## When not to use it

* Regression. The playground is for one-off requests, not suites. Promote anything you want to run repeatedly into a scenario.
* Assertions. The playground has no assertion DSL today (planned for phase 2). Use scenarios for pass/fail logic.
* Multi-step flows. Postscripts (`postExtract`) write captured values back into the environment, but chaining multiple requests with explicit assertions belongs in a scenario.

## On the roadmap

> [!TIP]
>
> Pre-request and post-response scripts via a QuickJS sandbox. An assertions tab with operator dropdown. OAuth2 (four grant types) with token caching. Digest and AWS SigV4 auth. Per-request and per-folder variables in the scope stack. Phase 3: cookie jar UI, HTML preview tab, client certificates, folder-level batch runner, diff-vs-last-response view, GraphQL schema-aware completion.

## Related

> [card] [Endpoint catalog](https://qodex.ai/docs/api-testing-endpoint-catalog.md)
>
> Where playground requests live.

> [card] [Chaining and postscripts](https://qodex.ai/docs/api-testing-chaining.md)
>
> Capture response values into environment variables.

> [card] [Scenarios](https://qodex.ai/docs/api-testing-scenarios.md)
>
> Promote a working request into a saved test.

> [card] [Auth profiles](https://qodex.ai/docs/api-testing-auth-profiles.md)
>
> Run as multiple roles.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.