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. Click Save as scenario on a working request and Qodex pre-fills a new API scenario with the same method, URL, headers, body, and auth, so the agent never has to re-derive a request that already works.
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. |
Response tabs
| Tab | Shows |
|---|---|
| Pretty | Rendered JSON, XML, or text. GraphQL errors surface as a severity-high callout above the data block. |
| Raw | Raw response body. |
| Headers | Response headers. |
| Timeline | Per-phase timing: prepare, connect, request sent, time-to-first-byte, response received, done. |
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. Hover any field to see the resolved value. Unresolved tokens stay as-is and surface a warning in the timeline; they do not fail the request.
Environment switcher
Swap the active environment from the top bar. 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. Save creates an api_endpoints row with a permanent ID and a permanent URL.
cURL import and export
- Import: paste a
curl ...command into the URL bar. The playground parses method, URL, headers, body, and basic auth, and prefills the form. - Export: click Copy as cURL to copy a runnable command for the current request. GraphQL bodies serialize as a JSON payload on copy, so the cURL works against the same endpoint without further translation.
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 promote it to a scenario in one click.
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.