---
title: "Upload an asset"
method: POST
path: "/assets"
---

# Upload an asset

`POST /assets`

Upload a file (max 5MB) to storage and get back a durable CDN URL. Send the raw file bytes as the request body with `Content-Type` set to one of the accepted mime types listed below.

Uploads are deduplicated per workspace by SHA-256 of the payload — pushing the same bytes twice returns the existing record (`200 OK`) rather than creating a duplicate. A fresh upload returns `201 Created`.

Trial accounts are limited to 20 uploaded assets. Dedupe hits don't count against the cap.

## Response `200`

Asset already existed (matched by content hash) — existing record returned

- object
  - `uid` string
  - `url` string, uri — CDN URL of the uploaded asset
  - `mime_type` string, nullable — Content-Type of the stored asset
  - `size` integer — File size in bytes
  - `created_at` string, date-time

## Other responses

- `201` — Asset uploaded
- `400` — Empty request body
- `402` — Trial cap hit — upgrade required
- `413` — Asset exceeds the size cap
- `415` — Unsupported Content-Type — see requestBody for the accepted list
- `502` — Upstream storage upload failed

---

[API](https://skmtc.dev/bannerbear/apis/bannerbear-v5-api.md) · [All operations](https://skmtc.dev/bannerbear/apis/bannerbear-v5-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bannerbear/bannerbear-v5-api/revisions/6aa425420a10/schema)