---
title: "Files and media"
description: "Show images, offer downloads and play videos, in a browser or a player."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Files and media

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 by `id`, never by `url`;
- a **private** file has `url: null` and an `attachment_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`.

```json
{
  "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:

```html
<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`](/customer-api/reference/get-attachment-url), with the `attachment_id`:

```bash
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>" }'
```

```json title="getAttachmentUrl 200"
{
  "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"
}
```

- `intent` is what the URL is for: `view` (shown in place), `download` (saved), `stream` (played), or `null` for a link or a public file, which opens as it is.
- `expires_at` is when the URL stops working, each range of it included; `null` for a URL that doesn't expire.
- `renew: true` asks again for a video still playing, so it stays one play (below).
- `intent` in the request picks, for a lesson's slides, `view` (shown in the player as uploaded) or `download` (saved, at their protection, where the customer may), and for a PDF a text shows, as a slideshow block's, `view` alone.
- `track` names one of a video's subtitle `tracks`, served inline to whoever may play the video.

The URL is on this API: [`GET /v1/stores/{store}/files/{capability}`](/customer-api/reference/get-file) 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.

```html
<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`:

```ts
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`](/customer-api/errors#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`](/customer-api/errors#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`](/customer-api/reference/get-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.

```bash
curl 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/media_outputs?attachment=<attachment id>&kinds=chapters&kinds=summary' \
  --header 'Authorization: Bearer ctk_...'
```

```json title="getMediaOutputs 200"
{
  "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.

Source: https://docs.sherpo.io/customer-api/files/index.mdx
