---
title: "Files"
description: "Upload files, attach them, fetch their bytes, and the storage your plan allows."
---

> 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

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. <a href="/merchant-api/reference/create-upload/">`POST /uploads`</a> 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. <a href="/merchant-api/reference/complete-upload/">`POST /assets/{asset}/complete`</a> marks it done once its bytes are in place: the file becomes `ready`, with its size as uploaded.

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

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

```json
{
  "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. <a href="/merchant-api/reference/move-asset/">`POST /assets/{asset}/move`</a> 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`](/merchant-api/errors#conflict).

### A small file in one call

A file up to 2 MiB can go in the request itself: <a href="/merchant-api/reference/create-inline-upload/">`POST /uploads/inline`</a> 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`](/merchant-api/errors#invalid).

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

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

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

<a href="/merchant-api/reference/cancel-upload/">`POST /assets/{asset}/cancel`</a> drops an upload you won't complete. To link a file hosted elsewhere, such as an external video, use <a href="/merchant-api/reference/create-asset/">`POST /assets`</a> instead. The [upload guide](/merchant-api/guides/upload-a-file) has the whole flow in code.

## Attach it

A file shows nowhere until it is attached. <a href="/merchant-api/reference/attach-asset/">`POST /{kind}/{id}/attachments`</a> 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. <a href="/merchant-api/reference/set-product-poster/">`PUT /products/{product}/poster`</a> 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. <a href="/merchant-api/reference/get-asset/">`GET /assets/{asset}`</a> 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. <a href="/merchant-api/reference/update-attachment/">`PATCH /attachments/{attachment}`</a>, <a href="/merchant-api/reference/reorder-attachments/">`POST /{kind}/{id}/attachments/reorder`</a> and <a href="/merchant-api/reference/detach-attachment/">`POST /attachments/{attachment}/detach`</a> change, reorder and detach them, keeping the file. Images and videos inside a text are blocks in its [rich text](/merchant-api/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 <a href="/merchant-api/reference/delete-asset/">`DELETE /assets/{asset}`</a>; <a href="/merchant-api/reference/list-asset-uses/">`GET /asset_uses`</a> lists where a file is used, within its `filter[asset_id]`. <a href="/merchant-api/reference/replace-asset/">`POST /assets/{asset}/replace`</a> 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

<a href="/merchant-api/reference/get-asset-url/">`POST /assets/{asset}/url`</a> answers where a file's bytes are, with `expires_at`:

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

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

```json
{
  "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`](/merchant-api/errors#invalid).

```js
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`](/merchant-api/errors#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.

- <a href="/merchant-api/reference/generate-media-output/">`POST /assets/{asset}/outputs/generate`</a> 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.
- <a href="/merchant-api/reference/list-media-outputs/">`GET /assets/{asset}/outputs`</a> lists them and where each one's generation stands; <a href="/merchant-api/reference/get-media-output/">`GET /assets/{asset}/output`</a> reads one with its content, and <a href="/merchant-api/reference/update-media-output/">`PATCH /assets/{asset}/output`</a> 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.
- <a href="/merchant-api/reference/publish-media-output/">`POST /assets/{asset}/outputs/publish`</a> 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

<a href="/merchant-api/reference/get-quota/">`GET /quota`</a> 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. <a href="/merchant-api/reference/get-plan-usage/">`GET /plan_usage`</a> 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`).

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