Skip to content

Files

Upload files, attach them, fetch their bytes, and the storage your plan allows.

Updated

A file is an asset in the store: a video, an image, a PDF, a download, or a link to a file elsewhere. Files are uploaded once and attached wherever they are used, as a product’s download or poster, an entry’s video, a page’s image.

Upload a file

An upload takes three calls: reserve the file, send its bytes, then complete it.

  1. POST /uploads reserves the file and answers where to send its bytes: upload.url, upload.method (PUT), upload.headers and upload.expires_at.
  2. Send the bytes to upload.url with that method and those headers, before expires_at. The body must be exactly bytes long. This request goes to the upload URL as it is, without your token. Any other header you send, like a Cache-Control, is dropped when the upload completes.
  3. POST /assets/{asset}/complete marks it done once its bytes are in place: the file becomes ready, with its size as uploaded.
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/uploads' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "enforcement": "signed",
  "name": "watercolor-workbook",
  "title": "Workbook",
  "mime": "application/pdf",
  "bytes": 2481152
}'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/uploads', {
  body: {
    "enforcement": "signed",
    "name": "watercolor-workbook",
    "title": "Workbook",
    "mime": "application/pdf",
    "bytes": 2481152
  },
});

Answers 201, abridged:

{
  "asset": {
    "id": "d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
    "name": "watercolor-workbook",
    "title": "Workbook",
    "mime": "application/pdf",
    "bytes": 2481152,
    "enforcement": "signed",
    "status": "pending"
  },
  "upload": {
    "method": "PUT",
    "expires_at": "2026-11-03T11:00:00.000Z"
  }
}

What a reservation takes:

  • enforcement decides who may reach the bytes: signed, the default, for a file served only through links that expire, the one for anything you sell; public for a file anyone with its link may load, such as images on your pages, which takes images (not SVG), video, audio and PDFs alone. POST /assets/{asset}/move with the other enforcement changes it later.
  • name is a short name in lowercase letters, digits and hyphens; title is what people see. mime is its type and bytes its size, up to 5,115 MiB. ext is its extension, the type’s usual one when left out.
  • A file that would take the store past its plan’s storage allowance is refused as 409 conflict.

A small file in one call

A file up to 2 MiB can go in the request itself: POST /uploads/inline takes what a reservation takes, with the bytes as data in place of bytes, base64 with padding, and answers the file, already ready. Use it when your code can’t send a request to the upload URL; for anything larger, or to send bytes as they are read, reserve and send them as above. A larger data is refused as 422 invalid.

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/uploads/inline' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "price-list",
  "title": "Price list",
  "mime": "text/csv",
  "data": "cGxhbixwcmljZQpCYXNpYywxMAo="
}'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/uploads/inline', {
  body: {
    "name": "price-list",
    "title": "Price list",
    "mime": "text/csv",
    "data": "cGxhbixwcmljZQpCYXNpYywxMAo="
  },
});

Answers 201, abridged:

{
  "id": "d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
  "name": "price-list",
  "title": "Price list",
  "mime": "text/csv",
  "bytes": 20,
  "enforcement": "signed",
  "status": "ready"
}

POST /assets/{asset}/cancel drops an upload you won’t complete. To link a file hosted elsewhere, such as an external video, use POST /assets instead. The upload guide has the whole flow in code.

Attach it

A file shows nowhere until it is attached. POST /{kind}/{id}/attachments attaches it to a product, an entry, a page, a quiz, a certificate, a holding or the store (the stores kind with the store’s own id), in a role:

  • deliverable: what a buyer gets, with delivery set to download, inline (viewed in place) or stream (a video or audio played in place).
  • poster: a product’s or an entry’s image. It takes an image only: any other file, a video included, is refused conflict on mime with the reason, and so is a replace or a type change that would make a poster’s file something else. PUT /products/{product}/poster sets a product’s thumbnail, held to a JPEG or PNG image within the limits its reference lists and refused invalid on asset otherwise. A podcast episode’s poster is its artwork: a ready JPEG or PNG whose pixels, measured from its uploaded bytes, are square and at least 1400 by 1400. Attaching or swapping in another file there, a pending upload or one whose pixels couldn’t be measured included, is refused invalid on asset (on role when moving a file into the poster), and so are a replace whose upload doesn’t fit (on upload), a type change to another type (on mime) and the completion of an upload already bound there whose bytes don’t fit (on asset, the upload staying pending). The product’s own thumbnail keeps its rules.
  • embed: media shown beside a target’s text. An entry’s own video or PDF, as a lesson’s video or slides, and a podcast episode’s own audio keep their kind: a replace or a type change to a file of another kind is refused conflict on mime with the reason. GET /assets/{asset} names the kind a file keeps in kept_kind (video, pdf or audio, null when none holds one), so a client can ask for that kind before it uploads.
  • stylesheet and logo: a page’s CSS and a certificate’s image. Attaching, swapping in, replacing or setting a file of another type is refused conflict on mime with the reason.
  • teaser, prompt and the others the reference lists, each where its target takes it.

preview_only: true makes an attachment part of the preview anyone may see. PATCH /attachments/{attachment}, POST /{kind}/{id}/attachments/reorder and POST /attachments/{attachment}/detach change, reorder and detach them, keeping the file. Images and videos inside a text are blocks in its rich text instead.

A target holds up to 500 attachments, refused conflict on items past that. A software product’s release files (release_file: true) hang on the product without counting toward it: a product’s attachment list leaves them out, and its release lists and orders them: moving one to another role, off download delivery, into the preview or to another position is refused conflict on event, naming the release, as is attaching its file as another of the product’s downloads.

A file nothing uses can be deleted with DELETE /assets/{asset}; GET /asset_uses lists where a file is used, within its filter[asset_id]. POST /assets/{asset}/replace swaps a file’s bytes for another upload’s, keeping every place it is used. A file a page or a text shows as an image takes new bytes, or a type that stops it playing, of at most 15 MB, as does a poster or a picture a product attaches as its own.

Fetch a file’s bytes

POST /assets/{asset}/url answers where a file’s bytes are, with expires_at:

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/assets/d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a/url' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "disposition": "attachment",
  "expires_in": 300
}'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/assets/d3c2b1a0-9f8e-4d7c-8b6a-5f4e3d2c1b0a/url', {
  body: {
    "disposition": "attachment",
    "expires_in": 300
  },
});

Answers 200, abridged:

{
  "url": "https://api.sherpo.io/merchant/v1/stores/STORE_ID/files/CAPABILITY",
  "expires_at": "2026-11-03T10:05:00.000Z"
}
  • A link comes back as it is, and a public file viewed in place as its public URL.
  • A private file, or any file asked for as a download (disposition: "attachment"), comes back as a URL on this API, /v1/stores/{store}/files/.... Fetch it with a GET and the same token in the Authorization header: the URL is bound to that token, so another token, or none, can’t fetch it. A token in its query string (access_token) is refused as invalid.
const { url } = await sherpo('POST', '/v1/stores/STORE_ID/assets/ASSET_ID/url', {
  body: { disposition: 'attachment' },
});
// A linked file's URL is elsewhere, so only this API's own URLs get the token.
const headers = url.startsWith(`${BASE}/`) ? { Authorization: `Bearer ${TOKEN}` } : {};
const file = await fetch(url, { headers });
if (!file.ok) throw new Error(`The file answered ${file.status}.`);
const bytes = new Uint8Array(await file.arrayBuffer());

The URL serves until expires_at (set it with expires_in, in seconds), or until the file changes; then ask for a new one. A file shown in place answers a Range header naming one bytes range with 206 and those bytes, and If-Range with an earlier ETag answers the whole file once it changed; a range outside the file, or several ranges, answers 416 range_not_satisfiable. A download is answered whole and works once, so its URL takes no HEAD. A 403 means the URL is another token’s or no longer valid; a 401, that the token itself is no longer honored.

Videos and audio

A video plays as soon as its upload completes. A video or an audio file can also have subtitles, a transcript, a summary and chapters, generated from its audio; the API calls them its outputs.

  • POST /assets/{asset}/outputs/generate generates one, or generates it again; subtitles come first, and the others are made from them. Each lands as a draft. Subtitles of audio longer than 10 hours (limits.subtitles_max_seconds) are refused with conflict on status, too_long, as is any other output that would wait on them, subtitles that would hold more than an edit saves land as their leading cues, and a transcript that would hold more than an edit saves or a run holds lands as its leading paragraphs, which takes about 800,000 characters, or 500,000 in scripts such as Chinese, Hindi or Thai.
  • GET /assets/{asset}/outputs lists them and where each one’s generation stands; GET /assets/{asset}/output reads one with its content, and PATCH /assets/{asset}/output edits it. An output an edit couldn’t save at all, such as subtitles with no cue left, reads as content: null with unreadable: true: edit it again, or generate it again. Subtitles hold at most 36,000 cues of 500 characters and limits.subtitles_max_bytes bytes of their cues’ JSON; longer ones read as what an edit saves, each text cut at 500 characters and the leading cues that fit, with truncated: true, and saving those drops the rest.
  • POST /assets/{asset}/outputs/publish shows one to customers, or takes it back to a draft.

Generating subtitles uses the store’s AI media minutes, which its plan allows each period, for videos and audio files alike.

Storage and allowances

GET /quota answers the storage the store’s files use against its plan’s allowance (used_bytes, allowance_bytes, available_bytes), by type, by who may reach them and by where they are used, as the merchant app’s storage page shows it. GET /plan_usage answers every allowance of the plan with what the store uses of it: storage, transcription minutes, customers, pages, menu items and redirects, and the features it includes, with the add-on blocks of storage and AI media minutes the store holds on top (add_ons).

Type to search…

↑↓ navigate↵ selectEsc close