Operation embeds

<Operation> renders one operation from your OpenAPI spec inside a prose page: the method bar, parameters, request body, responses, and the request console, generated from the same spec that powers your API reference. It exists for narrative pages that walk through an API while keeping every contract detail generated rather than hand-copied.

Usage

Configure your spec once:

apiReference:
  spec: openapi.json

Then embed an operation anywhere prose needs it:

Creating a sandbox is one call:

<Operation op="POST /sandboxes" />

The response arrives when the guest agent reports healthy.

The op value is the method and path exactly as they appear in your spec. A reference that matches nothing renders a visible danger callout in place, so a renamed endpoint cannot silently ship stale docs.

A live embed

This site configures its own spec, so here is a real one: the capabilities endpoint every Readsmith site serves, embedded in this prose page:

curl 'https://readsmith.dev/docs/_readsmith/api/ai/capabilities'

const response = await fetch("https://readsmith.dev/docs/_readsmith/api/ai/capabilities", {
  method: "GET",
});
const data = await response.json();

import requests

response = requests.get(
    "https://readsmith.dev/docs/_readsmith/api/ai/capabilities",
)
data = response.json()

curl 'https://readsmith.dev/docs/_readsmith/api/ai/capabilities'

{
  "search": false,
  "vectorSearch": false,
  "askAi": false
}

Props

When to embed, when not to

Embeds shine on site-only narrative pages: a walkthrough that interleaves prose with three or four fully specified calls. Two cautions from real use:

• A repository whose docs also render on GitHub should prefer plain Markdown there: component tags degrade to raw text outside Readsmith, while the generated API reference provides the rich version on the site.
• One operation per embed. A page of twenty embeds is an API reference wearing a costume; use apiReference.layout: pages and get navigation, search, and per-operation URLs for free.