Content REST contract v1 exposes one reviewed resource inventory per configured publication. The default base path is /content/v1. Protocol v1 is independent of the package release and publication version.
The host application supplies the API origin. The relative server URL /content/v1 describes a mount, not a live endpoint on this documentation site. Use the local example to try requests.
Available since 0.1.0-alpha.13.
Operations
The following references are generated from the reviewed OpenAPI source. They contain each operation's parameters, response schemas, examples, and source download.
| Operation | Purpose |
|---|---|
| List resource metadata | Discover resources and the loaded revision |
| List metadata headers | Check the inventory without a response body |
| Read resource metadata | Inspect one resource in a pinned revision |
| Read metadata headers | Check one resource without a response body |
| Read HTML or Markdown | Fetch original representation bytes |
| Read representation headers | Check representation headers without a response body |
Keep publication and revision together
All routes require a channel, version, and language. Omit revision only to discover the current inventory; copy its returned revision into subsequent requests. There is no pagination, search query, or fallback to another publication.
Treat the returned resource key as opaque. It identifies a page, section, or snippet instance independently of publication and revision. JavaScript integrations can use contentResourceKey(ref) from @shoalrun/cli/content. Do not substitute filenames, headings, or document IDs for the returned key.
Caching and revisions
Successful responses include a strong ETag containing the SHA-256 of their response bytes. If-None-Match can return 304 without a body. An inventory request without revision uses Cache-Control: no-cache. Successful revision-pinned requests use public, max-age=31536000, immutable.
An unavailable revision returns 409; the handler does not silently serve newer content. Errors use JSON with an error.code and error.message, and Cache-Control: no-store. HEAD returns the same status and headers without a body. The supplied browser client requests fresh responses and verifies representation bytes against the inventory; it does not maintain an HTTP response cache.
Host the reference handler
Import createContentRestHandler from @shoalrun/cli/content/server:
createContentRestHandler({ sources, basePath? }):
(request: Request) => Promise<Response>
sources is an array of already-open ContentSnapshot instances with distinct publications. basePath defaults to /content/v1; use an absolute path without a trailing slash. Segments accept ASCII letters, numbers, underscores, and hyphens. The caller owns the listener, routing, source disposal, and access policy. See serve content through REST for setup.
The adapter sends representation bytes unchanged. Continue hosting the original export's static asset and link mount. It does not supply authentication, search, editing, or revision history.
HTML, Markdown, and agents
Each native operation reference presents its source-backed request and response contract in HTML and Markdown. Agents can use those schemas and examples to list resources and request Markdown with the same publication and revision. HTML responses are passive content; the API does not supply application styling or browser behavior.