A product, an entry, a page or a body lists the files it shows. Each one comes with what you need to show it:
- a public file has a lasting
url: use it as it is. An image’s ends in#v=<version>once its smaller sizes are made, which names the version of its bytes and changes when they do, so compare files byid, never byurl; - a private file has
url: nulland anattachment_id: ask for a short-lived URL to it when you show it.
A file the reader may not open at all has neither, and a file still being prepared is status: "pending".
Responsive images
A public image lists its smaller copies as resized once they’re made, narrowest first: each one’s width in pixels and a lasting URL to it as AVIF and as WebP. The last is the image at its own width, or at 1920 pixels for a wider one. An image without them (a private one, one just uploaded or not yet measured, an SVG, one the store couldn’t convert, such as an animated one) has no resized: show its url.
{
"id": "<file id>",
"kind": "image",
"width": 1000,
"height": 500,
"url": "https://assets.sherpo.io/stores/<store>/assets/<file id>#v=<version>",
"resized": [
{ "width": 320, "avif": "https://assets.sherpo.io/stores/<store>/widths/<file id>/<version>/320.avif", "webp": "…/320.webp" },
{ "width": 640, "avif": "…/640.avif", "webp": "…/640.webp" },
{ "width": 960, "avif": "…/960.avif", "webp": "…/960.webp" },
{ "width": 1000, "avif": "…/1280.avif", "webp": "…/1280.webp" }
]
}Offer each format as a <source> with a sizes saying how wide the image shows, so the browser loads the smallest copy that fills it, AVIF where it can, WebP next, and the original where it takes neither:
<picture>
<source type="image/avif" srcset="…/320.avif 320w, …/640.avif 640w, …/960.avif 960w, …/1280.avif 1000w" sizes="(min-width: 48rem) 46rem, 100vw" />
<source type="image/webp" srcset="…/320.webp 320w, …/640.webp 640w, …/960.webp 960w, …/1280.webp 1000w" sizes="(min-width: 48rem) 46rem, 100vw" />
<img src="…/<file id>#v=<version>" width="1000" height="500" alt="" />
</picture>The copies’ URLs change with the image’s bytes, as its url does. An image kept as it is before the store told such images apart may still list copies holding its original’s bytes, which show as the original does.
Get a file’s URL
POST /v1/stores/{store}/attachments/url, with the attachment_id:
curl --request POST 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/attachments/url' \
--header 'Authorization: Bearer ctk_...' \
--header 'Content-Type: application/json' \
--data '{ "attachment": "<attachment id>" }'{
"url": "https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/files/<capability>/lesson-1.mp4",
"expires_at": "2026-11-03T10:15:00.000Z",
"intent": "stream"
}intentis what the URL is for:view(shown in place),download(saved),stream(played), ornullfor a link or a public file, which opens as it is.expires_atis when the URL stops working, each range of it included;nullfor a URL that doesn’t expire.renew: trueasks again for a video still playing, so it stays one play (below).intentin the request picks, for a lesson’s slides,view(shown in the player as uploaded) ordownload(saved, at their protection, where the customer may), and for a PDF a text shows, as a slideshow block’s,viewalone.tracknames one of a video’s subtitletracks, served inline to whoever may play the video.
The URL is on this API: GET /v1/stores/{store}/files/{capability} answers the bytes. How you fetch it depends on the credential that asked for it and the kind of file.
With a publishable key
A free lesson’s own video or audio, open to anyone, and each of its tracks, comes back as a lasting public URL (expires_at and intent null) that works for anyone, whoever asks for it; it changes when the file does or once the lesson stops being free, so ask again when one stops working. Any other file open to the store’s visitors (an image a page shows, a video a lesson’s text embeds) comes back the same way, and its URL already carries the key as publishable_key. The key is public, so the URL can go as it is in a <video src> or <img src>, with no script, and works for anyone holding it until expires_at. Sending the same key in the header too is fine. A video asked for with a key holds 4 hours, so a bare <video src> plays a lesson shorter than that through.
A video or audio file, with a token
A paid lesson’s video needs no header: its URL alone plays it, so it goes as it is in a <video src> or <audio src>, with no script.
<video src="https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/files/<capability>/lesson-1.mp4" controls></video>Its first play pins it to the network it plays from (the same IPv4 /24, or IPv6 /48): it then plays there alone until expires_at. Played from anywhere else, it answers 401, as a file fetched with no credential does, while the same URL with the token in the header still plays from anywhere. Only a play pins it, so your server may ask for the URL for the page that plays it.
It stops sooner once the token is revoked or refreshed, or the customer’s access to the file ends. So treat it as you would the token for that time, and never log it.
A player whose network changes as it plays (from Wi-Fi to a mobile network, or between IPv4 and IPv6) meets the same 401: ask again with renew: true, whose URL plays from wherever it plays next, and the old one then plays only there too.
Any other file, with a token
An image, a document or a download asked for with a token is fetched with the token in the Authorization header, so your page fetches it rather than naming it in a src:
import { API, problemOf, sherpo } from './sherpo';
const { url } = await sherpo<{ url: string }>('/attachments/url', {
token,
method: 'POST',
body: { attachment: attachmentId },
});
// Only this API's own file URLs take the token; a public file's URL is fetched as it is.
const at = new URL(url);
const own = at.origin === new URL(API).origin && /\/v1\/stores\/[^/]+\/files\//.test(at.pathname);
const file = await fetch(url, own ? { headers: { Authorization: `Bearer ${token}` } } : {});
if (!file.ok) throw await problemOf(file);
const image = URL.createObjectURL(await file.blob());Fetch it at once: the URL is bound to the token that asked for it, and a refresh ends it. Fetched with no credential, it answers 401 with WWW-Authenticate: Bearer, as does a file asked for with a publishable key whose URL lost its key. A token never goes in a URL: access_token in the query is refused.
Ranges and downloads
A file shown in place (a video, an image, a document) answers a Range naming one bytes range with 206 and just those bytes, so a player can seek in a long video without loading it whole, as a video element does on its own. A range outside the file, or several ranges, answers 416 range_not_satisfiable. If-Range with an earlier ETag answers the whole file once it changed.
A download is answered whole, marked with the customer’s name when the merchant protects the file. It works once, so the route takes no HEAD. A lesson’s slides viewed in place are served as uploaded, whatever their protection, as is a PDF a slideshow block shows.
When a URL ends
The URL serves until expires_at: a video’s holds longer than other files’. Past it, or with a token after a refresh, ask again, with renew: true for a token’s video still playing, and keep its ETag for If-Range. A video element playing past it needs a script to set the new URL and its currentTime back.
A 403 means the file is held back from the customer (not_entitled), or its URL is another token’s or key’s, or no longer valid (not_permitted with the reason principal): ask for a new URL, and with a token, sign the customer in again if that’s refused too.
A video’s or audio file’s chapters, summary and transcript
Where the merchant published them, GET /v1/stores/{store}/media_outputs reads a video’s or audio file’s chapters, summary and transcript, for whoever may play it. A video or audio file in a read’s attachments lists the ones it has as outputs, and its subtitles as tracks; a body’s resolved file carries them under video, or audio beside its waveform.
curl 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/media_outputs?attachment=<attachment id>&kinds=chapters&kinds=summary' \
--header 'Authorization: Bearer ctk_...'{
"unreadable": [],
"chapters": [
{ "start": 0, "title": "Welcome" },
{ "start": 95, "title": "Setting up" }
],
"summary": {
"summary": "How to set up your first project, step by step.",
"key_points": ["Create the project", "Invite your team"]
},
"transcript": null
}An output asked for and not published is null. One that couldn’t be read right now is listed in unreadable: ask again later.
In a browser
A page on another origin may call the API: a preflight is answered for any origin, since the credential is a header, never a cookie. A success is readable only from the store’s own origins (https://{store}, the store’s primary hostname, and the site set as Your website in its settings) and from the Allowed origins of the app that issued the token, or of the publishable key sent. A video fetched by its URL alone, with no credential, is readable from https://{store} only, and plays in a media element on any page. A refusal is readable from any origin, so a page can sign the customer in again.
Allowed origins are read again every 5 minutes, so one added or removed takes effect within that time; while they can’t be read, those read in the last 10 minutes still stand. A preflight is kept 10 minutes per URL.