Skip to main content

LitPage content management API

Discover your LitPage site, read CMS content with Management v2, and use revision IDs to save and publish the intended draft.

Use the LitPage content management API to find your site, read its CMS content, and automate publication. The hosted base URL is https://build.lit.page/api/v2. Paths below are relative to that base.

Send Authorization: ApiKey ${LITPAGE_WORKSPACE_KEY} for every request. Use a Workspace Key with read access for GET and write access for saving and publishing. Send Content-Type: application/json with JSON request bodies. Keep requests with this credential on your server or in CI.

Find the target site

  • GET /sites takes no parameters or body. HTTP 200 returns a data array of accessible sites.
  • GET /sites/resolve requires one query string, subdomain. Supply a bare subdomain such as my-site, its my-site.lit.page hostname, or an active custom hostname. Send no body. HTTP 200 returns one site object in data.
  • GET /content-types takes no parameters or body. HTTP 200 returns the content type descriptors in data. Each descriptor includes a type ID, name, description, route prefix and pattern, maturity, example path, and capabilities. The capabilities report typed Markdown availability and nullable detail and collection contract versions. The hosted registry marks BLOG, DOC, and CHANGELOG as core.
curl --fail-with-body --get 'https://build.lit.page/api/v2/sites/resolve' \
  --header "Authorization: ApiKey ${LITPAGE_WORKSPACE_KEY}" \
  --data-urlencode "subdomain=${LITPAGE_SUBDOMAIN}"

Set LITPAGE_SUBDOMAIN to your site's subdomain. The site object's siteId is a string ID for management paths. The subdomain, name, defaultDomain (URL), and defaultLanguage fields are strings. customDomain is the active custom hostname or null. createdAt and updatedAt are date-time strings. An inaccessible hostname returns 404 from resolve. Check it against the result of /sites.

Read CMS content and revisions

Replace {siteId} with the ID from site discovery. For {contentId}, use the item ID, and for {slug} use the URL-encoded article slug. The GET routes take no body.

  • GET /sites/{siteId}/contents returns HTTP 200 with item summaries in data. Optional query fields are type (defaults to BLOG), language (such as EN), status (DRAFT, PUBLISHED, or ARCHIVED), search (matches title or excerpt), page (positive page number, default 1), and limit (1–100, default 20). Omit optional filters you do not need.
  • GET /sites/{siteId}/contents/{contentId} returns HTTP 200 with an item and its body in data. No query fields are needed.
  • GET /sites/{siteId}/contents/by-slug/{slug} returns HTTP 200 with an item and its body in data. Include type=DOC for documents and specify language=EN or the intended language to select a translation. Type defaults to BLOG. Use the list route for search and pagination. If the slug exists in multiple languages, omitting language can return 400 LANGUAGE_REQUIRED_FOR_DUPLICATE_SLUG.
curl --fail-with-body --get \
  "https://build.lit.page/api/v2/sites/${SITE_ID}/contents/by-slug/${CONTENT_SLUG}" \
  --header "Authorization: ApiKey ${LITPAGE_WORKSPACE_KEY}" \
  --data-urlencode 'type=DOC' \
  --data-urlencode 'language=EN'

Set SITE_ID from site discovery and CONTENT_SLUG to a document on your site. Use the quickstart to run a list request if you need a slug.

Interpret a successful response

This example is an illustrative excerpt for a by-ID or by-slug read of a published document with pending edits.

{
  "success": true,
  "data": {
    "type": "DOC",
    "language": "EN",
    "status": "PUBLISHED",
    "slug": "getting-started",
    "currentRevisionId": "c7c9356a-59d4-4ea1-a72c-db5a8e1f5e29",
    "hasUnpublishedChanges": true,
    "draft": {
      "revisionId": "c7c9356a-59d4-4ea1-a72c-db5a8e1f5e29",
      "content": "Updated draft"
    },
    "published": {
      "revisionId": "c7c9356a-59d4-4ea1-a72c-db5a8e1f5e20",
      "content": "Public version"
    }
  },
  "meta": {
    "requestId": "example-request-id",
    "timestamp": "2026-11-18T12:00:00.000Z",
    "version": "v2"
  }
}
  • data is a resource object for a detail read and an array for a list. Content items include string identifiers, a content type, language, status, title and slug. content is the draft body string when returned, and data inside a content item is type-specific metadata when present.
  • currentRevisionId and draft describe the current editable snapshot. published describes the public snapshot and is null when none is available. hasUnpublishedChanges is a boolean. A PUBLISHED item can have newer draft edits. Keep management responses out of public caches.
  • pagination appears at the top level on list responses. page, limit, total, and totalPages are numbers. hasNext and hasPrev are booleans.
  • meta carries string values for requestId, ISO timestamp, and API version.

Save and publish the revision you reviewed

For Markdown files, follow Publish Markdown with the LitPage CLI. The CLI handles portable document metadata and revision selection. For direct HTTP, this is the existing-draft update and publish sequence.

  1. Read the item by ID. Save data.currentRevisionId for the write.
  2. PATCH /sites/{siteId}/contents/{contentId} with a JSON object containing the fields you want to change. For a body-only edit, send a non-empty Markdown string in content and the pulled revision UUID in expectedRevisionId. HTTP 200 returns the updated item in data. The editable revision can change while the public snapshot stays in place.
  3. Review data.draft and store the new data.currentRevisionId.
  4. POST /sites/{siteId}/contents/{contentId}/publish with the reviewed revision UUID in JSON field expectedRevisionId. HTTP 201 returns the item with the published snapshot. Check data.published.revisionId and confirm the public article in a signed-out window.
curl --fail-with-body --request PATCH \
  "https://build.lit.page/api/v2/sites/${SITE_ID}/contents/${CONTENT_ID}" \
  --header "Authorization: ApiKey ${LITPAGE_WORKSPACE_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"content":"Updated Markdown","expectedRevisionId":"c7c9356a-59d4-4ea1-a72c-db5a8e1f5e29"}'
curl --fail-with-body --request POST \
  "https://build.lit.page/api/v2/sites/${SITE_ID}/contents/${CONTENT_ID}/publish" \
  --header "Authorization: ApiKey ${LITPAGE_WORKSPACE_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"expectedRevisionId":"b6e70733-c2ee-487c-82ba-5562eaaa371e"}'

PATCH also accepts optional title, slug, excerpt and updateReason strings, a language code, a content type enum, an author object, featuredImage or cover metadata, and a type-specific data object. DOC placement uses the optional root string and parent folder path or null. Keep the item's existing type and language for a normal edit and use the CLI workflow for document placement.

Use actual revision IDs from your own reads. Both routes take the same two string IDs in the path and no query options. The revision field is optional in the transport schema. Always supply it to bind the request to the version you read. On HTTP 409, fetch the latest version, compare, and reconcile before retrying.

Handle management errors

Check the HTTP status before reading data. API v2 failure responses carry success: false, error.code, error.message, statusCode, and meta.requestId. The error message can be a string or a validation message array. Log the request ID for troubleshooting while keeping keys and draft text private.

  • 400 Check input types, JSON, and content validation messages.
  • 401 AUTHORIZATION_REQUIRED, INVALID_API_KEY_FORMAT, or INVALID_API_KEY. Verify your header and the full active key.
  • 403 API_KEY_PERMISSION_DENIED or SITE_ACCESS_DENIED. Check read/write access and select a site in the key's workspace.
  • 404 SITE_NOT_FOUND or CONTENT_NOT_FOUND. Verify IDs, slug, type, and language.
  • 409 Preserve concurrent edits by rereading before a retry. If CONTENT_SLUG_CONFLICT is returned, check for an existing item with the same slug, type, and language.