# Upload files and images

> How to upload files for your customers and images for sales pages, courses, emails and landing pages through the Tentary API.

Source: https://tentary.com/en/help/api/file-uploads/
Last updated: 2026-10-27

---

You upload files and images in three steps: create the upload, send the bytes with PUT, finish the upload.

## Files or images?

- **Files** are what your customers get: for example a PDF, a ZIP, a video or an audio file in the content of a product or a lesson. Use [`POST /v1/files`](https://tentary.com/en/help/api/upload-file/) for them.
- **Images** show on a sales page, in a course, a module, an email or a landing page. Use [`POST /v1/images`](https://tentary.com/en/help/api/upload-image/) for them. If an image is already at a public URL, you need no upload: put the URL in directly.

## Upload a file

1. Create the upload:

   ```bash
   curl -X POST "https://api.tentary.com/v1/files" \
     -H "Authorization: Bearer $TENTARY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"file_name": "Workbook.pdf", "size_bytes": 123456}'
   ```

   The answer has a `file_id` and an `upload_url`. The `upload_url` is valid for 20 minutes.

2. Send the bytes with HTTP PUT to the `upload_url`, without extra headers:

   ```bash
   curl -T Workbook.pdf "<upload_url>"
   ```

3. Finish the upload with [`POST /v1/files/{file_id}/finish`](https://tentary.com/en/help/api/finish-upload/).

Then use the `file_id` in a content block of a product or a lesson, for example `{"type": "file", "file_id": 601}`.

This way works for files up to 5 GB.

### Short way for small files

A public file of at most 10 MB can also go in one step. Send only the `url` instead of `file_name` and `size_bytes`:

```bash
curl -X POST "https://api.tentary.com/v1/files" \
  -H "Authorization: Bearer $TENTARY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://..."}'
```

Tentary copies the file at once. No finish step is needed.

## Upload an image

1. Create the upload with [`POST /v1/images`](https://tentary.com/en/help/api/upload-image/), with `file_name` and `size_bytes`. PNG, JPG, GIF and WebP up to 10 MB are allowed.
2. Send the bytes with HTTP PUT to the `upload_url`.
3. Finish the upload with [`POST /v1/images/{upload_id}/finish`](https://tentary.com/en/help/api/finish-image/).

The answer has the `image_url`. Use it for example in `images` of a product, as `cover_image_url` of a course or module, or as `img src` in the HTML of an email or a landing page.

> **Note:** An image block in the content of a product or a lesson needs a `file_id` from `POST /v1/files`, not an `image_url`.