Skip to main content

Read a published page

Retrieve a published page with its public header, footer, localization data, and SEO metadata using the delivery v1 page lookup.

Prerequisites

  • •A deployment exposing the delivery v1 OpenAPI document
  • •A registered website hostname and a published page

Request

GET /api/delivery/v1/pages/by-path
Accept: application/json

This read operation does not require a management API key. It returns published content only; there is no includeDraft parameter. Use the separate preview flow for unpublished revisions.

This operation supports section-based pages. A collection entrypoint, such as a configured blog or documentation index, returns 422 UNSUPPORTED_PAGE_KIND; it is not converted into an empty page. Collection rendering continues to use /api/v1/render/content-list in this release.

ParameterRequiredMeaning
domainYesRegistered website hostname without a scheme, port, or path, such as your-site.lit.page
pathYesPage path beginning with /, excluding a language prefix, query string, or fragment
languageNoLitPage language code, such as EN, FR, or ZH_CN; matching is case-insensitive

Omit language to use the website default. Sending an empty value is invalid. Repeated parameters, unknown parameters, IP-address tenant selection, traversal segments, and encoded path separators are rejected. The maximum hostname length is 253 characters; the maximum path length is 2,048 characters.

For a French version of /pricing, send path=/pricing&language=FR, rather than including /fr in the page path. The API does not silently substitute the English article when the requested translation is unavailable.

Make a request

The hosted API uses https://build.lit.page. After verifying that this deployment exposes delivery v1, read a public page with:

curl --get 'https://build.lit.page/api/delivery/v1/pages/by-path' \
  --data-urlencode 'domain=lit.page' \
  --data-urlencode 'path=/' \
  --header 'Accept: application/json'

The API hostname and the website hostname serve different purposes: build.lit.page hosts the API, while domain=lit.page selects the published website.

Test a local deployment

Replace the hostname and path with those of your local test fixture. The loopback address below is the API server; domain selects the website being read.

curl --get 'http://127.0.0.1:4401/api/delivery/v1/pages/by-path' \
  --data-urlencode 'domain=your-site.lit.page' \
  --data-urlencode 'path=/pricing' \
  --header 'Accept: application/json'

Use the verified API origin for your own deployment. API requests from a server are independent of browser CORS permissions; do not assume that a successful curl request authorizes cross-origin browser access.

Understand the response

A successful page resource has schemaVersion: 1 and kind: "page".

FieldMeaning
sitePublic site key, requested domain, canonical origin, and registered public origins
pagePage ID, published revision ID, public short ID, path, language, title, and description
content.sectionsOrdered authored page blocks
layoutPublic header and footer, theme, and supported appearance settings
localizationDefault/current language, available languages, navigation URLs, and public page identities
seoCanonical URL and the page's public SEO metadata

No draft body, account identity, or management settings are included. The page revision alone does not identify a complete site snapshot: public layout and SEO settings can change separately. Use the response ETag to validate the complete representation.

Handle a moved page

A successful address lookup can instead return:

{
  "schemaVersion": 1,
  "kind": "redirect",
  "redirect": {
    "status": 301,
    "location": "/content/docs"
  }
}

The lookup response is HTTP 200 JSON. Your website renderer should issue the indicated 301 at the visitor-facing URL. The destination is a site-relative path; it is not an arbitrary external URL. This prevents an API fetch from unexpectedly following a redirect to an HTML page.

Read from server-side JavaScript

async function readPublishedPage(apiOrigin, domain, path, language) {
  const url = new URL('/api/delivery/v1/pages/by-path', apiOrigin);
  url.searchParams.set('domain', domain);
  url.searchParams.set('path', path);
  if (language) url.searchParams.set('language', language);

  const response = await fetch(url, {
    headers: { Accept: 'application/json' },
    signal: AbortSignal.timeout(5000),
  });
  if (!response.ok) {
    const problem = await response.json();
    throw new Error(`Page request failed (${response.status}): ${problem.code}`);
  }
  const resource = await response.json();
  if (resource.schemaVersion !== 1 || !['page', 'redirect'].includes(resource.kind)) {
    throw new Error('Unsupported page resource');
  }
  return resource;
}

This example illustrates transport handling. Production integrations should additionally validate the full response against the supplied schema before rendering, and handle network errors separately. Never turn a failed request into a fabricated successful page.

See Errors, caching, and compatibility for conditional GET and status handling.