Mentra API Documentation

A structure node's own title, description and cover image are now published rather than live, on every publishedOnly=true read. This closes the one case the earlier release today deliberately left open. Where a node carries content, its title, summary and coverImageUrl already came from the published translation. Where it does not — a Knowledge Base category, a course or group root, any node created but not yet given a body — those three fields were read from the node document itself, and that document is rewritten the instant an editor saves, with no publish step in between. So renaming a category made the new name public immediately, while renaming an article did not, and nothing in the response told the two apart. The same field behaved differently depending on whether a body happened to be attached. Publishing a node now also freezes its own title, description and cover image, and a published read serves that frozen copy: GET /v1/sections/{key}/tree, GET /v1/sections/{key}/nodes/{id} (including its breadcrumbs and children), the node teasers in GET /v1/surfaces/{key}, GET /v1/content/by-slug/{slug} and GET /v1/export all resolve it the same way, so no two of them can disagree about a node. Renaming a node after publishing it therefore keeps serving the previously published name until you publish again — which is what publishing already meant for every other kind of edit on this API. Three things do not change, and are worth stating because each is the question integrators ask first. Nothing goes blank: a node that has never been published serves its current values, so navigation labels cannot disappear, and existing content was seeded with the values it was already serving, making this release a no-op for every node until its next edit. Preview reads are untouched — publishedOnly=false with a key holding read:preview still shows the working values, which is what that scope is for. And structural edits are still immediate: reordering, creating and deleting nodes take effect without a publish, because navigation housekeeping is not published copy. No request or response field was added, removed or renamed, and no field's type changed. If you cache tree or node responses keyed on title, expect one invalidation as the values settle to their published form; the tree's ETag already covers its resolved titles.

GET /v1/export now serves published bodies on a publishedOnly=true read, not working ones. Earlier today's release gated the export at item level: an item appears only when it is published, publicly visible and reachable. The body inside each item was left alone, so every item still carried its working translation — a published article whose editor had rewritten it and not republished exported the unreleased content, contentJson, contentHtml, summary, keywords and seoMetadata to a key holding only read:content, while GET /v1/standalone/{id} returned the published text to that same key at the same moment. Two reads of one item at one instant disagreed, which is the boundary the read:preview scope exists to draw and the one already closed for by-slug and surface teasers (title, summary, coverImageUrl) and for standalone SEO. All three builders are now scoped — standalone, level1..4 on either content platform, and Section-native node items — and none of them falls back: a published read reads the published revision or nothing. That covers title as well as the body. title, summary and coverImageUrl were additionally resolved from the item's own document when the translation had no value, and that document is mutable — renaming a node or a standalone item writes it immediately, with no publish step — so the same read could disclose an unpublished rename, description or cover. For any item that can hold a body those three now come from the published translation only — standalone, the Curriculum ladder on either content platform, and Section-native node items alike. The one exception is a structural container that holds no body of its own: a category or group root legitimately stores its title and coverImageUrl on the node itself, there is no translation that could ever carry them, and those still return as before. If you call GET /v1/export to mirror what your site shows, this is what you wanted and there is nothing to do. Two consequences to plan for. First, an item whose ORIGINAL locale has no published revision now exports empty editorial fields — content, contentHtml, summary, keywords, seoMetadata and coverImageUrl come back null, and title comes back an empty string — instead of the draft's values. Note the asymmetry, because it is easy to miss: an item is admitted when any of its locales is published, but its body and metadata are read from the original locale only. So an article authored in en and published solely in nb is listed, correctly, and still comes back with those fields empty. That is a normal multilingual situation rather than a defect, and it has the same shape as an interrupted publish or as content marked live through the publishedLocales index with nothing under the published revision. The item is still listed and still addressable — id, slug, visibilityTags, isPublished and the timestamps are unchanged — so do not treat an empty body as a missing item. Identify items by id, which every item carries: externalId is optional and is commonly null on standalone and level1..4 records, which are the ones most likely to hit this, and only node items are guaranteed one because the export synthesises it. One consequence worth checking against your restore tooling: an item in that state will not re-import from a default export, because import requires a non-blank title. Take it with publishedOnly=false, or publish the item's original locale. Second, an export taken at the default no longer round-trips in-progress edits — re-importing it reconstructs the published text and drops the unreleased revision. That default already omitted unpublished items wholesale, so it was not a faithful backup before this change; the bodies now agree with the items. For a backup that restores exactly what the CMS holds, use publishedOnly=false with a key holding read:preview: that path still returns the working translation for every item, drafts included. One backup payload did change, and it changed by gaining content: level1..4 items belonging to tenants still on the pre-Sections content platform, whose bodies were authored in the CMS, previously exported with an empty body on both settings, because the export looked for the body beneath the level record while that content is stored alongside it instead. It is now found, so those items carry content, contentHtml, summary and the rest where they used to be blank. Nothing was removed or renamed, but a backup taken after this release can be materially larger than one taken before it, and a diff against an older backup will show those fields appearing — worth checking if your restore tooling treats an item gaining a body as a conflict. Every other item type is untouched on that setting. Holding read:preview does not change the default — the parameter does, so a preview-scoped key still reads like production, bodies included, unless it asks for drafts. One field's contents narrowed, on every setting: seoMetadata on standalone and level1..4 items is now limited to the keys the write API accepts (metaTitle, metaDescription, focusKeyword, focusKeywords, slug, canonicalUrl, readingTime), matching what node items have done since the Section export shipped. CMS-authored content also stores generated derivatives — suggestedSlug, structuredData, openGraph, twitterCard — and emitting those verbatim made POST /v1/import reject the entire request, so an export containing one such item could not be restored at all. If you read seoMetadata off an export for something other than re-import, those four keys are no longer present on those item types; the delivery reads still expose them. No request or response field was added, removed or renamed, and the item shape, pagination and type filter are unchanged.

GET /v1/export now accepts publishedOnly and defaults it to true, so an export returns published, publicly-visible content only — the same contract every other read on this API already has. Until now the export was the one read with no publish filter, no visibility filter and no preview gate: a key holding read:content alone received every draft in the tenant in full — bodies, summaries, keywords and SEO metadata — including items whose visibilityTags is empty and are therefore hidden from everyone, and items never published in any locale, while that same key got 403 Missing scope read:preview for preview access from GET /v1/standalone?publishedOnly=false. isPublished was computed per item and reported, but it filtered nothing. This is a behaviour change for anyone already calling /v1/export. If you export to mirror what your site shows, the new default is what you wanted and there is nothing to do. If you export to take a backup or migrate a tenant, add publishedOnly=false and make sure the key holds read:preview — otherwise the backup silently loses every unpublished item. publishedOnly=false without read:preview is a 403 carrying the same message the standalone and Section reads return; the split is per key, so a tenant can hand its public website a read:content key that cannot see unreleased work and its backup job a read:content + read:preview key that can. Holding read:preview does not change the default: the parameter does, so a preview-scoped key still reads like production unless it asks for drafts. All three item shapes obey the flag — standalone, level1..4 on either content platform, and the Section-native node items. Under publishedOnly=true an item is included only when at least one of its locales is published and it passes the visibility filter — its visibilityTags contains public, or the field is absent entirely, which legacy content predating visibility tagging relies on and which every read on this API treats as public. Only an explicit list without public — including an empty one — is excluded, so do not treat a returned item as invalid because it carries no visibilityTags. And, for level1..4 and node items, it is included only only when every ancestor passes that same test, because a published article under a draft category is not publicly reachable and the Section tree does not serve it either. A consequence worth planning for: pruning an ancestor prunes its whole subtree, so a published item can disappear from the export because something above it was unpublished. totalItems plus the pagination counts describe what you receive rather than what was filtered out. Pruning never leaves a parentExternalId pointing at nothing: across a complete export — every page, no type filter, imported in page order — every parentExternalId resolves to an item the export contains, so a pruned backup still restores cleanly. That guarantee is about pruning only, and it is not page-local. A type-filtered export names parents it does not contain, because you asked for a slice: type=level2 has always referenced the level1 items it omits. Pagination can likewise separate a parent from its child: the export does emit parents before children — standalone, then level1 through level4, then node items in parent-first order — but a page boundary can still fall between the two, so a single page taken on its own may carry a child whose parent arrived on an earlier one. Import the pages in order and that resolves. Both limits were true before this change and are unchanged by it. One operational consequence of guaranteeing that: if a datastore read fails part-way through enumerating your content, the request now returns an error instead of a 200 carrying whatever had loaded. That applies on both publishedOnly settings. A partial export is indistinguishable from a tenant that genuinely holds less, and restoring from one loses content silently, so a backup job that previously recorded a success it should not have will now see a failure it can retry. Under publishedOnly=false nothing is filtered — drafts and hidden items are both included, exactly as the export behaved before — so a preview-scoped key takes the same full backup it always did, and that payload still POSTs back to /v1/import verbatim. One thing the flag did not change, at this release: the exported body was the item's working translation, so a published item edited since it was last published exported the edited text. That was superseded the same day — see the entry above, which scopes bodies to the published revision on publishedOnly=true and describes what changes for backup consumers. The type, page and pageSize parameters and the item shape are unchanged.

GET /v1/content/by-slug/{slug} and the node teasers in GET /v1/surfaces/{key} now serve published metadata on a publishedOnly read. Both read title, summary and coverImageUrl straight off the mutable content document, which every write updates regardless of publish state — so an item renamed but not republished returned its unpublished title (and summary/cover) while GET /v1/sections/{key}/tree and GET /v1/sections/{key}/nodes/{id} returned the published one for the same item at the same moment. All three fields now come from the same publish-scoped translation those Section routes already use, and they move together: a published translation that carries no summary or cover now returns null rather than falling back to the draft value, and an item whose content has no published translation at all (an interrupted publish, or legacy data) returns null rather than the draft. Preview reads (publishedOnly=false with the read:preview scope) are unchanged and still show drafts. Two related changes: updatedAt on both routes now reports the newer of the item's own timestamp and its content's, so a title-only republish — which touches neither the item document nor the surface — is visible instead of looking unmodified; and for the same reason the surface ETag now covers the resolved teaser metadata, so cached surface ETags are invalidated once by this release and a revalidating client no longer 304s past a republished title. Node teasers also now carry summary, populated from the published translation; the field was already part of the surface item shape and was previously always null for node entries. No request or response field was added, removed or renamed.

Standalone content SEO is now scoped to publish state and tenant. GET /v1/standalone/{id} (and its /posts and /standalone-content aliases) previously fell back to the draft translation's stored seoMetadata when the requested locale had no published translation — so a publishedOnly=true request made with a key holding only read:content could receive unpublished metaDescription, focusKeywords, suggestedSlug and structuredData. A published read now reads only published translations. The integrator-visible effect: for content published in a locale that has no published translation document (a legacy shape), seoMetadata on a publishedOnly=true response now carries generated values derived from the item's title and summary instead of the draft's authored values; the field is still present and its shape is unchanged. To keep receiving authored draft SEO, request publishedOnly=false with a key holding read:preview, or publish the locale's translation. Preview reads are unchanged.

Structured content is served from the section/node model for every tenant; the legacy four-level storage behind it is retired. Nothing about the API changes with this: request and response shapes, the level1..4 write routes, bulk import/export, slug lookup, menus and Sections all behave exactly as before, because the last tenants moved to the new model at the 2026-07-17 cutover and this removes the code path none of them was taking. Two clarifications that were previously ambiguous. Re-parenting an item through an update returns 400 on every write surface — the level1..4 routes, the Section node routes, and bulk import alike — and there is no endpoint that moves an item to a different parent; an earlier note here pointed at "the dedicated node routes" for moves, which were never built. To place an item under a different parent: a leaf can be re-created in the new position and the original deleted, but an item with children or attached content must have those moved or removed first, because the delete is refused while they exist — so moving a subtree means rebuilding it bottom-up and deleting the old one leaf-first. And a non-cascade delete of an item that still has children returns 409 rather than orphaning them, which is now the behaviour everywhere rather than only on the new platform.

GET /v1/export now returns a content body that POST /v1/import can actually read back, for standalone and level1..4 items. Those items paired contentFormat "json" with the plain-text rendering of the body, so re-importing a content-bearing item failed conversion on that row with "Invalid JSON content" — the documented round trip worked only for items with no body, and for the node items added on 2026-07-26. The content field now carries the serialized document that contentFormat describes, so a restore reconstructs it byte-for-byte. If you read the export rather than restore it, nothing you were using has moved: contentJson and contentHtml still carry the structured and rendered forms exactly as before, and every other field is unchanged. If you parsed content expecting prose, read contentHtml (rendered) or keep using the plain text you were reading there before by rendering contentJson — content is the field the import consumes, and it is now labelled honestly. Publication state is still not restored by an import: everything arrives as a draft, so plan a republish step into any migration.

PUT /v1/level1..4 now enforces externalId uniqueness on update: assigning an externalId already held by another item at the same level returns 409 external_id_conflict and writes nothing, matching the upsert-key contract those routes already advertise. Previously only the create path checked this — an update could silently assign a duplicate externalId, after which the next create-by-externalId upsert picked between the two items arbitrarily. Re-sending an item's own unchanged externalId is unaffected and still succeeds. This mirrors the same 409 the Section node routes (POST/PUT /v1/sections/{key}/nodes) already return for the identical case.

Export any Section shape — GET /v1/export now emits Section-native content as items typed "node", carrying sectionKey plus nodeTypeKey, alongside the existing standalone and level1..4 items. Until now the export enumerated only the four-level Curriculum ladder, so a category, an article, or any tenant-authored node type had no slot in the schema and was omitted silently with a 200: a tenant using a branching, flat, deeper-than-four, or tenant-authored Section had no backup path, and the import generalization shipped earlier today was one-way. The type filter gains node; omitting type returns everything, and the standalone and level1..4 items are unchanged. Node items are emitted parents-before-children, because parentExternalId resolves against nodes created earlier in the same import request, and each node appears exactly once — an export naming one node twice would be refused wholesale with 400 duplicate_item_address. parentId is deliberately null on a node item: it out-ranks parentExternalId on import and the exported value is a source-tenant id that names nothing in the target, so parentExternalId is the portable linkage. Two long-standing defects that made the advertised round trip fail for every item type are fixed with it: an export item can now be POSTed to /v1/import verbatim (the response-only fields id, contentJson, contentHtml, isPublished, createdAt and updatedAt are ignored on input instead of rejecting the request), and a node item's content is the serialized document matching its contentFormat, so re-import reconstructs the body rather than failing to parse it. Unknown fields are still rejected, so a misspelled field name is still an error. A node item also carries parentNodeTypeKey, naming the parent's node type: when a template lets two node types hold the same child, one externalId can name a node of each — both legal, since identity is per node type — and a bare parentExternalId would be ambiguous, so the child would fail to import. You may send it on your own node items; omitting it leaves resolution exactly as before. Every node item carries an externalId: it is optional when you create a node and CMS-authored content has none, but import requires one, so a node without one falls back to its Mentra document id, used consistently for its own externalId and its children's parentExternalId — restoring into an empty or different tenant works as intended and repeats idempotently, though re-importing into the tenant you exported from creates a second node rather than updating the original, which never carried that id. Exported seoMetadata is limited to the fields the write API accepts (metaTitle, metaDescription, focusKeyword, focusKeywords, slug, canonicalUrl, readingTime); SEO derivatives generated in the CMS (suggestedSlug, structuredData, openGraph, twitterCard) are omitted because the write API rejects them and including them would fail the whole import request. If two nodes in one Section and node type share a stored externalId, which older data allows because that uniqueness is not enforced by the datastore, both are still exported and the second is given a distinct -2 address so the backup stays importable. Three limitations to plan around: a node item carries one locale, so a multi-locale node exports its original-locale body only; restoring into a new tenant needs the Section to exist first, since a node item addresses a Section by key rather than creating one; and publication state is not restored — the export reports isPublished, but the write API has no publish capability, so everything imports as a draft (true of standalone and level1..4 imports too, and always has been). Because Section delivery defaults to publishedOnly, restored content stays off the public tree until it is republished in the CMS, so plan a republish step into any migration. Note also that the verbatim round trip currently applies to node items: standalone and level1..4 exports still pair contentFormat json with the plain-text rendering, so a content-bearing item of those types fails conversion on re-import until that pairing is corrected.

Bulk-import into any Section shape. POST /v1/import items may now be typed "node" and carry a sectionKey plus a nodeTypeKey from that Section's template, alongside the existing standalone and level1..4 types. Previously every structured item resolved onto the four-level Curriculum ladder, so a Section built on a branching, flat, deeper-than-four, or tenant-authored template could be read and written one item at a time but had no batch path in. Node items nest to whatever depth the template permits; parentExternalId resolves within the item's own Section, searching only the node types that template says may parent the child, so a placement the template forbids is reported as a per-item error before anything is written (dryRun reports the same verdicts a live run does). externalId remains the upsert key, scoped per Section and node type — the same externalId may name a node in two Sections without collision, and a result now echoes sectionKey and nodeTypeKey so it correlates back to its request item. Because that scope is the node's identity, two "node" items in one request sharing sectionKey, nodeTypeKey and externalId are rejected up front with 400 duplicate_item_address and nothing is written: under any onConflict strategy one of the two rows would otherwise be silently discarded, so a bad id mapping is reported rather than half-applied. Re-sending the same externalId in a later request is the intended idempotent path and is unaffected. sectionKey/nodeTypeKey are accepted only on a "node" item: sending them on a level1..4 item returns 400 rather than silently importing into the default Curriculum Section. The standalone and level1..4 request shapes are unchanged and keep working. (At the time this shipped GET /v1/export still mirrored only the level1..4 + standalone item shape, so a node from a non-Curriculum Section could not be round-tripped; export gained node items later the same day — see the entry above.)

Write structured content into any Section shape: POST /v1/sections/{key}/nodes plus PUT and DELETE on /v1/sections/{key}/nodes/{id} create, update, and remove a node by naming its Section key and its node type from that Section's template. Previously the only structured write path was POST /v1/level1..4, which maps onto the four-level Curriculum ladder and nothing else — so a Section built on a branching template (Knowledge Base), a flat one (Pages), or a tenant-authored template had no write path even though it could already be read via GET /v1/sections/{key}/tree. The new routes place nodes at whatever depth the template permits (no four-level cap), reject placements the template forbids before writing, and treat externalId as an upsert key per Section and node type (an update that would duplicate another node's key returns 409). Only node types flagged content_bearing accept a body: sending content, keywords, or seoMetadata to a container type returns 400 rather than silently dropping it, while title, summary, and coverImageUrl are always accepted so container nodes stay writable. The level1..4 routes are unchanged and keep working. (At the time this shipped GET /v1/export could not represent a node from a non-Curriculum Section and omitted those records, so there was no backup path for such a Section. That gap is now closed — GET /v1/export emits node items; see the 2026-07-26 export entry above.)

Read a structured node's full content body: GET /v1/sections/{key}/nodes/{id} returns the rendered content (HTML/JSON/plain text), SEO + schema.org metadata, ancestor breadcrumbs, and the same include= extras as the standalone detail (quiz, scenarios, mnemonics, video, sources) plus include=children for container nodes. Start from a sectionKey + node id or from a by-slug hit's sectionKey. Relatedly, by-slug on a tenant without structured content now resolves only readable (standalone) content instead of returning legacy level hits that had no read path.

Structured content now reads through a single surface. The legacy per-level and Memolife-named read endpoints (GET /v1/level1..4 and GET /v1/lifeskills, /v1/courses, /v1/journeys, /v1/steps) have been retired; fetch a tenant's structured content as a group via GET /v1/sections and GET /v1/sections/{key}/tree instead. Standalone-content endpoints and the hierarchy write endpoints are unaffected.

Placements can now teaser a structured entry node — a Course or Knowledge-Base Category — not only standalone articles. A resolved surface item (GET /v1/surfaces/{key}) carries a targetKind of "standalone" or "node"; a node teaser additionally carries a sectionKey so your site can deep-link into the Section the entry node belongs to. Existing standalone placements are unaffected (targetKind defaults to "standalone"); the item shape is otherwise unchanged.

Sections — fetch a named structured-content group as a group: GET /v1/sections lists a tenant's Sections by stable key with their template vocabulary (two same-template Sections are now distinguishable), and GET /v1/sections/{key}/tree returns the whole ordered node tree in one call, each node carrying its per-locale slug, filtered to the requested locale's published, public content. Both payloads echo the Section's advisory basePath "lives at" hint for display — never resolution truth; the key and node slugs stay authoritative.

Structured content now serves from the generalized section/node model for tenants on the new content platform. Request/response shapes are unchanged across the read, write, bulk-import, bulk-delete, slug-lookup, menus, and export endpoints — content is simply sourced from the new model, and read/slug/menus/export behavior is identical. Writes on the new platform add three stricter guards: re-parenting an item via update returns 400, a non-cascade delete of an item that still has children returns 409 rather than orphaning them, and slugs are unique per-tenant across all levels (a cross-level clash returns 409). Clients not on the new platform are unaffected.

Placements — render a curated content slot by key: GET /v1/surfaces/{key} returns the surface's currently-active placements as ordered content summaries (scheduling windows evaluated server-side), and GET /v1/surfaces lists the tenant's surface keys for discovery.

Curate by tag — standalone content now returns its editorial tags, and the list/summary endpoints accept a tag= filter (e.g. tag=page:forside) for surface curation.

Show your sources — the standalone detail endpoint can now return the research citations (title + URL) behind a piece via include=sources.

SEO-friendly content discovery — look up any content item by its human-readable slug instead of internal IDs.

Safer imports and full data portability — preview import results before committing, export your entire content library, and batch-delete content in bulk.

Cleaner content output — HTML responses are now pure semantic markup, giving you full control over styling in your own frontend.

Full read-write API and media management — create, update, and delete content programmatically. Upload and manage images with automatic CDN delivery and on-the-fly optimization.

Flexible hierarchy naming — access content using generic level-based paths that match your tenant's custom labels.

Smarter content queries — filter and selectively include fields to fetch exactly the data you need.