What a product, an entry (a lesson or an article), a custom page or the store’s home shows is its body: a layout of blocks, some of which hold rich text. You read a body with GET /v1/stores/{store}/body, or with include=body on the product, entry or page read. Without a body of its own, a page still shows a default layout, which the read answers in its place.
Bodies
curl --globoff 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/body?target[kind]=entry&target[id]=<entry id>' \
--header 'Authorization: Bearer ctk_...'target names whose body: { "kind": "store" } for the store’s home, or a product, entry or page with its id.
{
"id": "<body id>",
"role": "body",
"access": "unlocked",
"requires": { "kind": "tier", "rank": 1, "product_id": "<product id>" },
"words": 412,
"content": "{\"blocks\":[{\"id\":\"intro\",\"type\":\"markdown\",\"content\":\"<rich-text version=\\\"1\\\"><h2>Welcome</h2><p>Start here.</p></rich-text>\"},{\"id\":\"lesson-video\",\"type\":\"video\",\"fileId\":\"<file id>\"}]}",
"files": {
"<file id>": {
"id": "<file id>",
"kind": "video",
"mime": "video/mp4",
"name": "lesson-1.mp4",
"bytes": 48213900,
"width": 1920,
"height": 1080,
"duration": 754,
"pages": null,
"status": "ready",
"url": null,
"attachment_id": "<attachment id>",
"unlocks": null
}
}
}defaultisnullfor the page’s own body.contentis a JSON string. Parse it: it’s an object whoseblocksis the layout, each block an object with itsid, itstypeand its props. Containers hold more blocks.accessisunlocked, orlockedwhen the customer may not read it yet. A locked body answers itsrequiresandwords, but nocontent: show what unlocks it instead (A customer’s library).fileslists every file the layout names, by thefileIda block holds. A public file has its lastingurl, and a public image its smaller copies asresized, for a responsive image; a private one hasurl: nulland anattachment_idyou open when you show it. A file kept back by its own rules lists whatunlocksit.- A body still being prepared answers
409conflictonstatus(pending): ask again shortly.
Default layouts
A page with no body of its own, or with one it can’t show, shows a default layout instead, and the body read answers that default. A body it can’t show is a layout that doesn’t read, or a body of another type; a lesson’s text and an article’s HTML show as their text.
{
"default": { "template": "page" },
"attachment": null,
"mime": "application/vnd.sherpo.blocks+json",
"access": "unlocked",
"requires": { "kind": "everyone" },
"content": "{\"blocks\":[{\"id\":\"default-hero\",\"type\":\"hero\",\"title\":\"About us\",\"alignment\":\"center\",\"highlights\":[],\"additionalContent\":[],\"lineProducts\":{\"id\":\"default-line\",\"type\":\"line-products\",\"hidden\":true},\"hidden\":false}]}",
"words": null,
"files": {}
}default.templatenames the default:home: a hero with the line of products, a rule and the product grid;page: a centered hero with the page’s title and description;lessonandarticle: empty, since an entry’s title, media and header come from its own fields;- a product’s, by category:
series,blog,podcast,portfolio, orproductfor every other category.
attachmentnames the body the page shows the default for, or isnullwithout one.- The store’s home and a product’s page also show their default to a customer their own body is kept from.
- A product’s default shows its poster when its settings show it as the background. Its cover is the product’s own pictures and videos the customer may open, all listed in
files. - A default has no gate of its own. It is
locked, withcontent: null, only when the page itself is kept from the customer, and itswordsarenull. - A front-end that can show none of a page’s own blocks asks for its default instead with
fallback=true: the body read then answers the default whatever the page’s body,attachmentnaming that body.
Blocks
Every block type a body holds, its props and their JSON Schema are in the block reference, with where each one sits: a lesson’s body takes fewer types than an article’s, a page’s or the store’s home (though one may still hold a page’s block it held before), and a product’s page has its own. A block with hidden: true isn’t shown, and a markdown block holds a rich text in its content.
A formula block holds a display formula’s TeX in tex: render it with a TeX renderer such as KaTeX, or show its source.
A diagram block holds a diagram’s Mermaid source in source, a type the store’s page draws (a flowchart, sequence, state, class, ER or XY chart diagram): render it with a Mermaid renderer, or show its source.
An audio block plays the file its fileId names, in an <audio> or a player of your own. Where the customer may play it, its file in files carries audio.waveform: the recording’s loudness from start to end as 256 levels from 0 to 255, in base64, to draw as bars the customer seeks on. It’s null until the wave is drawn after upload, so show a plain bar until then. A private recording streams through its attachment_id as a video does (Files and media): ask for its URL on the first play rather than when the page shows, as each URL asked for counts as a play, then with renew: true as it nears expires_at, which keeps it one play. Its audio also lists the chapters, summary and transcript the merchant published as outputs, read through audio.attachment_id (A video’s or audio file’s chapters, summary and transcript), and their subtitles as tracks.
A slideshow block shows the PDF its fileId names a page at a time, as a lesson’s slides are shown, with no download. Its file in files carries an attachment_id even when it is public, and pages: ask for its URL with intent: "view" when it shows, then read it whole, as a PDF viewer does (Files and media). A public PDF’s url is readable from any origin too.
A map block shows a place: latitude and longitude, an optional venue and address, and openInMaps, which shows a link to the seller’s mapUrl, or to OpenStreetMap at the point when it has none. The store draws the map itself, so it is listed in the read’s maps beside files, one entry per point the body names, matched by latitude and longitude (both rounded to 6 decimals, as the block stores them): a light and a dark picture of the place, each a public url with its width, height and smaller copies as resized (responsive images), and the attribution to show over it, linking to attribution_url. Show the picture for the page’s theme, the place’s pin at its centre. A point is missing from maps until its map is drawn, shortly after the body is saved: show the venue and address alone until then.
Render a block type you don’t know as nothing: new types may be added.
Rich text
Every rich text field (a product’s description, an entry’s teaser, the texts a body’s blocks hold, a quiz’s text) comes back as HTML in one closed format, as stored when it was written, so you can render it as it is or map each element to a component of your own. It’s wrapped in <rich-text version="1">.
<rich-text version="1"><h1>Welcome</h1><p style="text-align: center">Start with <strong>the intro</strong>, then <a href="https://example.com/notes" target="_blank">read the notes</a>.</p><ul><li data-checked="true"><p>Watch the intro</p></li><li data-checked="false"><p>Take the <span style="color: #047857">quiz</span></p></li></ul><details><summary>Why it works</summary><p>Short lessons stick.</p></details></rich-text>What it holds
- Text:
p,h1(Title),h2(Heading),h3(Subheading),br. - Marks:
strong,em,u,s,sup,sub,code(a text written withb,i,delorstrikeis stored asstrong,emands); links (a) tohttp,https,mailto,tel,ftp,ftps,callto,sms,cid,xmpp,irc,ircsor a relative path, optionally withtarget="_blank". A link’srel(noopener,noreferrer,nofollow) is read when written but never stored, so add your own. - Style:
colorandbackground-coloron aspan, as#rgbor#rrggbb;text-align(left,center,right,justify) on a paragraph or heading. - Structure:
ul,ol(start),li(data-checked="true"or"false"for a task list), tables (table,thead,tbody,tr,th,td, withcolspanandrowspan), code blocks (preholding onecode,class="language-<id>"with an id amongbash,c,cpp,csharp,css,go,xml,java,javascript,json,kotlin,markdown,php,python,ruby,rust,sql,swift,typescript,yaml),blockquote,hr,details(open) with itssummaryfirst. - Figures: a
figureholds any of the above, with at most onefigcaption, first or last. - Blocks: images, videos, audio, slideshows, formulas, diagrams, maps, downloads and the other blocks sit in a text as
<block type="…" props="…"></block>elements, their props a JSON object with its quotes escaped, the same props a body’s block has (block reference). There is no rawimg,videooriframe.
<block type="image" props="{"id":"cover","fileId":"FILE_ID","alt":"The cover"}"></block>A <block>’s fileId is listed in the same read’s files, as a body’s are.
The stored form
Texts come back in a canonical form: attributes in a fixed order, entities and spacing normalized, loose inline content in a paragraph, an empty list item, cell, quote, details or figure holding an empty paragraph, an empty list holding one empty item, tables made rectangular, and each block’s props as its type reads them (defaults filled in). A text holds at most 1 MiB, nests at most 32 elements deep, and its tables cover at most 10000 cells in all.