Skip to content
Sheaf DocsSearch the documentation⌘K
Latest
Download PDF

Reading settings

Theme
Article text size
Panel
API/API reference

API reference

Point sheaf.json at an OpenAPI document and the build generates a reference section: one page per operation, request examples in twenty languages, and an interactive sandbox that sends real requests through the platform proxy. The reference is part of the artifact, so it publishes and rolls back together with the prose around it.

For event contracts and schemas without HTTP operations, see AsyncAPI and GraphQL references.

Mounting a document

json
{
  "apiSpecs": [
    { "file": "openapi/acme.yaml", "mount": "/api", "title": "Acme API" },
    { "file": "openapi/billing.json", "mount": "/api/billing", "title": "Billing API" }
  ]
}
Key Required Meaning
file yes Path of the document in the repository. JSON or YAML.
mount yes Site path where the section appears, starting with /.
title no Heading of the section.

Up to fifty documents per site. /mcp and /.well-known/ are reserved, and a mount point that collides with a page address is a build error rather than a race.

A mount point is not a page, so it is not a page reference. Put it in navigation as an anchor with a relative target: { "label": "Reference", "target": "api" }.

Versions accepted

OpenAPI 3.0 and 3.1, in JSON or YAML.

Swagger 2.0 and anything else — the build says which version it found and which it accepts, instead of failing halfway through generation.

External references

$ref pointers to other hosts are resolved by Buildd during the build, before pages are generated, and only from hosts you list:

json
{
  "externalRefs": { "allowedHosts": ["schemas.acme.example"] }
}

An unreachable reference is a build error. The resolved content is bundled into the generated artifact; externalRefs does not permit reader-time requests and does not configure the interactive sandbox. That separation keeps a page from depending on a later remote response.

With no hosts listed, no external reference is fetched at all. Private ranges, loopback addresses and cloud metadata addresses are blocked regardless of what the list says.

Request examples

Every operation gets an example in twenty languages, generated from the operation itself — path and query parameters, headers, and a body built from the schema or from the example in the document.
Shell (cURL) Python (Requests) JavaScript (fetch) Node.js (fetch)
Go (net/http) Java (java.net.http) Kotlin (OkHttp) C# (HttpClient)
PHP (cURL) Ruby (net/http) Rust (reqwest) Swift (URLSession)
Objective-C (NSURLSession) C (libcurl) Crystal Clojure (clj-http)
OCaml (CoHTTP) R (httr) PowerShell (Invoke-RestMethod) HTTP/1.1

If a document is so unusual that examples cannot be produced for at least twenty languages, the build fails rather than shipping a reference with empty tabs.

The sandbox

Operation pages carry a sandbox: fill the parameters, send the request, read the response. The request does not go from the reader's browser to your API — it goes through the platform proxy, and the proxy only calls hosts you allow:

json
{
  "sandboxProxy": { "allowedHosts": ["api.acme.example"] }
}

Each entry is one exact DNS host: wildcards and IP literals are invalid. An address outside the list is refused. Private ranges, loopback and cloud metadata addresses are refused even if their host is listed.

Both are enforced on the proxied request, and redirects are not followed.

Each proxied request produces one usage event of type sandbox_proxy_request. See Usage and limits.

sandboxProxy is the sandbox's runtime outbound-request policy. It lives in sheaf.json rather than the control panel because it changes together with the specification it belongs to. The build seals the policy into the immutable artifact for the exact documentation version and language. A changed list therefore needs a new published build; historical artifacts that predate the sealed policy keep their documentation available but disable the sandbox.

What operation pages get for free

  • A markdown representation at the same address, like every other page: an agent reads the operation without rendering the sandbox.
  • Search coverage: operation summaries, descriptions and parameters are indexed with the rest of the corpus, so a reader searching for a field name lands on the operation.
  • The same rollback: the reference is inside the artifact, so a rollback restores the previous version of your API documentation, not just the prose.

Working example

The reference mounted at /api on this site is the usage contract of the platform itself: the endpoint that hands out usage events and their aggregate. The document lives in this repository at openapi/sheaf-usage-api.yaml, which is exactly how a tenant would keep theirs.

Built with Sheaf