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:- Exploration. Hit endpoints by hand while the agent is reasoning about them, without leaving the app.
- Verification. Re-run a captured request from a collection or test run to sanity-check behavior before generating a scenario.
- 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
Response tabs
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/<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 reachlocalhost 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
Related
Endpoint catalog
Where playground requests live.
Chaining and postscripts
Capture response values into environment variables.
Scenarios
Promote a working request into a saved test.
Auth profiles
Run as multiple roles.