API Request / Response

Use docspress/api-request to teach one HTTP exchange. It can remain a static request and example response, or become a guarded browser runner with editable inputs, live status, timing, headers, and response body.

Choose static or runnable

Keep the block static when the endpoint needs credentials, modifies data, has restrictive cross-origin policy, or should return a deterministic teaching example. Enable runnable for safe public or same-origin endpoints where live feedback materially helps the reader.

Use editable: false to offer a fixed runnable request. Relative endpoints resolve against the current site unless baseUrl is supplied.

GitHub preview

The readable Markdown envelope projects the request and response into separate collapsed <details> groups. Each summary exposes the method, endpoint, or response status before expansion, while headers and bodies remain syntax-highlighted fenced code inside the group.

This presentation exists only in Markdown. The hidden config remains authoritative and reconstructs the native docspress/api-request block in Gutenberg; DocsPress never sends the generated <details> markup to WordPress.

Attributes

method enum: HTTP request method.

DefaultGET ValuesGET, POST, PUT, PATCH, DELETE
endpoint string required: Relative or absolute request URL.

Default/wp-json/wp/v2/pages
headers string: One Name: value header per line.

DefaultAccept plus token placeholder
requestBody string: Example or runnable request body.
requestBodyFormat enum: Request editor formatting.

Defaultjson Valuesjson, raw
responseStatus string: Static example status.

Default200 OK
responseBody string: Static example response body.

DefaultExample JSON object
responseBodyFormat enum: Static response formatting.

Defaultjson Valuesjson, raw
runnable boolean: Adds the guarded browser runner.

Defaultfalse Valuestrue, false
editable boolean: Lets readers change the runnable URL, headers, and body.

Defaulttrue Valuestrue, false
allowUnsafe boolean: Author opt-in for mutating methods; readers must still confirm each run.

Defaultfalse Valuestrue, false
baseUrl url: Base used to resolve relative endpoints.
allowedOrigins string: Comma-separated exact origins permitted for cross-origin requests.

Valueshttps://api.example.com
timeout number: Runner timeout in milliseconds, clamped to 1000–30000.

Default10000 Values1000–30000

Static example

Request GET /wp-json/wp/v2/pages?context=edit

HeadersKey: value

Accept: application/jsonAuthorization: Bearer $WP_ACCESS_TOKEN

Response 200 OK

BodyJSON

[{
  "id": 42,
  "slug": "docs"
}]

Runnable example

Request GET /wp-json/

HeadersKey: value

Accept: application/json

Try it Run this request

Credentials omitted

Request URL Headers Body

Ready

Example response 200 OK

BodyJSON

{
  "name": "WordPress"
}

Static validation-error example

Request POST /wp-json/wp/v2/pages

HeadersKey: value

Accept: application/jsonContent-Type: application/jsonAuthorization: Bearer $WP_ACCESS_TOKEN

Request bodyJSON

{
  "title": "",
  "status": "publish"
}

Response 400 Bad Request

BodyJSON

{
  "code": "rest_invalid_param",
  "message": "Invalid parameter: title",
  "data": {
    "status": 400
  }
}

Runner safety

The runner sends requests with browser credentials omitted. It blocks Cookie, Host, Origin, Content-Length, Proxy-Authorization, Proxy-Connection, and every Sec-* header. Same-origin requests are allowed by default; cross-origin requests require an exact http or https origin in allowedOrigins.

POST, PUT, PATCH, and DELETE remain disabled unless the author enables allowUnsafe. Even then, the reader must complete a two-step confirmation immediately before execution. Run can be cancelled, Reset restores the authored request, and Copy as cURL excludes blocked headers.

Live output and accessibility

Live results report status, elapsed time, byte count, response headers, and body. Long response bodies use a responsive 16–26rem scroll area with a visible keyboard focus target and the label “Scrollable API response body.” Run, Cancel, Reset, and Copy status changes are announced to assistive technology.

Test the exact published origin and its CORS behavior. A successful static example does not guarantee that a browser can run the same request.