---
type: "TechArticle"
softwareVersion: "1.0.0"
url: "https://registry.docsloth.dev/components/api-playground.html"
markdown: "https://registry.docsloth.dev/docs/api-playground.md"
component: "api-playground"
section: "interactive"
trust_class: "interactive"
implementation_status: "implemented_native"
renderer: "native block"
install: "docsloth component add @docsloth/api-playground@1.0.0"
spec: "packages/contracts/component-specs/api-playground.md"
props_schema: "packages/contracts/component-props/api-playground.schema.json"
---

> Index: [Agent index](https://registry.docsloth.dev/llms.txt)

# api-playground

Describe an API request without executing it

| Field | Value |
| --- | --- |
| Trust class | interactive |
| Implementation status | implemented_native |
| Renderer | native block |
| Key prop (production schema) | method |
| Key prop (protocol fixture) | no protocol fixture published |
| Tools | none |
| Package version | 1.0.0 |
| Package digest | sha256:e32a8142a4770416496adb7e57a0f590b6c89bfb7f78bd6726b96295478a2e4e |

## Install

```sh
docsloth component add @docsloth/api-playground@1.0.0
```

Live package: sha256:e32a8142a4770416496adb7e57a0f590b6c89bfb7f78bd6726b96295478a2e4e with 2 file digest(s); the catalog entry is generated from the built package, not a placeholder.

## Props

The prop schema is normative in `packages/contracts/component-props/api-playground.schema.json`.

| Prop | Type | Required | Constraints |
| --- | --- | --- | --- |
| `method` | string | yes | maxLength: 32; pattern: ^[A-Za-z][A-Za-z0-9-]*$ |
| `path` | string | yes | maxLength: 500 |
| `baseUrl` | string | no | maxLength: 500; pattern: ^https?:// |
| `auth` | "none" \| "bearer" | no |  |
| `parameters` | array<object> | no |  |
| `requestBody` | object | no | additionalProperties: false |
| `requestBody.contentType` | string | no | maxLength: 200 |
| `requestBody.example` | string | no |  |
| `summary` | string | no | maxLength: 500 |

Example props generated from this schema:

```json
{
  "method": "GET",
  "path": "/v1/pets",
  "baseUrl": "https://api.example.com",
  "auth": "none",
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "required": true,
      "description": "Max items",
      "example": 10
    }
  ],
  "requestBody": {
    "contentType": "application/json",
    "example": "{\"name\":\"Rex\"}"
  },
  "summary": "Create a pet"
}
```

Required props: method, path.

## Example

Example document IR (the block the renderer consumes):

```json
{
  "type": "api-playground",
  "props": {
    "method": "POST",
    "path": "/v1/pets",
    "baseUrl": "https://api.example.com",
    "auth": "bearer",
    "summary": "Create a pet",
    "parameters": [
      {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Max items",
        "example": 10
      }
    ],
    "requestBody": {
      "contentType": "application/json",
      "example": "{\"name\":\"Rex\"}"
    }
  }
}
```

Renderer HTML (entities decoded and wrapped for display):

```html
<section class="ds-playground" data-component="api-playground" data-method="POST" data-auth="bearer" aria-label="POST /v1/pets API playground">
<p class="ds-playground-summary">Create a pet</p>
<p class="ds-playground-signature">
<span class="ds-method" data-method="POST">POST</span>
<code class="ds-playground-path">/v1/pets</code>
</p>
<pre class="ds-playground-example" aria-label="Example request">
<code>POST https://api.example.com/v1/pets?limit=10
Authorization: Bearer <token>
Content-Type: application/json

{"name":"Rex"}</code>
</pre>
<form class="ds-playground-form" data-ds-playground-form data-markdown-ignore="true" aria-label="Request builder">
<fieldset class="ds-playground-fields">
<legend>Parameters</legend>
<div class="ds-playground-field">
<label for="b-param-0">limit (query)</label>
<input id="b-param-0" name="limit" type="text" value="10" aria-describedby="b-param-0-hint">
<p class="ds-playground-hint" id="b-param-0-hint">Max items</p>
</div>
</fieldset>
<fieldset class="ds-playground-fields">
<legend>Request body (application/json)</legend>
<label for="b-body">Body (application/json)</label>
<textarea id="b-body" name="body" rows="4">{"name":"Rex"}</textarea>
</fieldset>
<button type="submit" class="ds-playground-run" data-ds-playground aria-label="Run request">Run</button>
</form>
<table class="ds-playground-params">
<thead>
<tr>
<th>name</th>
<th>in</th>
<th>required</th>
<th>description</th>
<th>example</th>
</tr>
</thead>
<tbody>
<tr>
<td>limit</td>
<td>query</td>
<td>no</td>
<td>Max items</td>
<td>10</td>
</tr>
</tbody>
</table>
<p class="ds-playground-note">Requests run in the host page. Nothing executes in the renderer.</p>
</section>
```

Preview (interface-only; the markup above is the same output):

The renderer resolves this component as a native block; the preview above is its real HTML output, and Markdown parity for native blocks is covered by the renderer test suite.

## Specification

Generated from `packages/contracts/component-specs/api-playground.md`.

### Contract

Packaged: this block ships as `@docsloth/api-playground@1.0.0` — an installable component package (kind `block`, capability `render.html`, Apache-2.0) whose production props schema is `packages/contracts/component-props/api-playground.schema.json` and whose catalog entry is in `packages/contracts/component-catalog.json`. No protocol manifest fixture is published (`manifest_fixture: null`): the fixture models a packaged protocol runtime this block does not have.

### Intended behavior

Build a request from an OpenAPI-style operation: method, path, optional base URL, auth mode, typed parameters and an optional request body. The example request line and parameter table are generated server-side from props, so the same request exists as inert HTML text and as an agent-readable `http` fence. The form is progressive enhancement only.

### Failure and fallback

A missing or invalid `method`/`path`, a non-array `parameters`, a parameter without a name, or a non-object `requestBody` degrades the whole block to the labelled fallback. An unknown `auth` value and a non-`http(s)` `baseUrl` degrade in place (ignored) instead of taking out the block.

### Required acceptance cases

Opening the page, reading the Markdown twin or submitting the form must never perform a network request, read a credential or execute renderer-supplied code without a host-provided handler. Also test empty data, missing parameters, a `bearer` example, browser without JS, mobile 360px, keyboard navigation, dark mode and an explicit constrained agent tool call. The server independently authorizes capability requests; a package manifest cannot grant authority.

### Data and maintenance

Data bindings resolve from a specific publication/release vector and permitted fact/evidence graph. Configuration edits create versioned component patches. Update invalidation uses dependency IDs, never indiscriminate whole-page regeneration. Human-owned props survive automatic updates unless invalidated with an explicit conflict. Missing optional resources leave an honest inert/readable fallback, not a broken page or fake success.

### Cost and tools

Pure/local interaction must never invoke a model by accident. Running a request is a host capability: the renderer emits no script, no inline handler and no `action`, and it never receives raw credentials. Any model, remote query or executor call must reserve approved budget before dispatch. The component may call only named tools in its signed manifest with valid typed inputs.

### Native renderer block

`packages/renderer` renders an `api-playground` block from the document IR. HTML emits an accessible `<form>` (`data-ds-playground-form`) whose inputs are `<label for=…>`-wired and described by their hints, a Run button carrying `data-ds-playground`, a server-side example request line and a parameter table. Markdown emits the same request as a fenced `http` example plus the same parameter table — the agent fallback — and repeats the progressive-enhancement note. Running requests is the host page's responsibility; nothing executes in the renderer.

#### Native block props

| prop | type | required | behaviour |
| --- | --- | --- | --- |
| `method` | string | yes | HTTP method token, normalised to upper case; missing or non-token values degrade to the fallback. |
| `path` | string | yes | Path (a missing leading `/` is added) or absolute URL; whitespace, quotes and angle brackets degrade to the fallback. |
| `baseUrl` | string | no | `http(s)` origin prefixed to the example URL; any other value is ignored. |
| `auth` | `'none' \| 'bearer'` | no | `bearer` adds an `Authorization: Bearer <token>` line to the example; any other value is ignored. |
| `parameters` | `{name, in, required?, description?, example?}[]` | no | One labelled input plus one table row per parameter; a wrong shape degrades to the fallback. |
| `requestBody` | `{contentType, example?}` | no | Adds a `Content-Type` line and body text; a wrong shape degrades to the fallback. |
| `summary` | string | no | Visible description of the operation, mirrored in Markdown. |

The form is interface-only chrome and is marked `data-markdown-ignore`; because hiding a focusable control would break assistive technology it stays in the accessibility tree. The parameter table, example request and note are content and are never ignored.

#### Example

```json
{
  "type": "api-playground",
  "props": {
    "method": "POST",
    "path": "/v1/pets",
    "baseUrl": "https://api.example.com",
    "auth": "bearer",
    "summary": "Create a pet",
    "parameters": [
      { "name": "limit", "in": "query", "required": false, "description": "Max items", "example": 10 }
    ],
    "requestBody": { "contentType": "application/json", "example": "{\"name\":\"Rex\"}" }
  }
}
```

## Package manifest

No protocol fixture is published for this renderer-native block.

| Field | Value |
| --- | --- |
| Fixture | none published |

## Sources

| Source | Path |
| --- | --- |
| Component page | https://registry.docsloth.dev/components/api-playground.html |
| Markdown twin | https://registry.docsloth.dev/docs/api-playground.md |
| LLM index | https://registry.docsloth.dev/llms.txt |
| Specification | packages/contracts/component-specs/api-playground.md |
| Prop schema | packages/contracts/component-props/api-playground.schema.json |
| Catalog | packages/contracts/component-catalog.json |