---
title: "Upload a media asset"
method: POST
path: "/api/v1/media"
tags: ["Media Library"]
---

# Upload a media asset

`POST /api/v1/media`

Upload a file into the library. Dedup by checksum returns the existing asset.

## Response `201`

Successful Response

- MediaAssetDTO
  - `id` string, uuid, required
  - `kind` 'image' | 'video', required
  - `filename` string, required
  - `url` string, required — Public URL of the original.
  - `contentType` string, nullable — Sniffed content type, not client-declared.
  - `sizeBytes` integer, required
  - `width` integer, nullable
  - `height` integer, nullable
  - `durationMs` integer, nullable — Video duration; null in v1 (no ffmpeg).
  - `lqip` string, nullable — ~20px blurred data-URI for next/image placeholder='blur'.
  - `folderId` string, uuid, nullable — null = library root.
  - `originContext` string, required — Full upload context, e.g. 'pwa.logo' or 'uncategorized'.
  - `section` string, required — Derived from originContext prefix; the picker's default facet.
  - `tags` string[]
  - `isArchived` boolean
  - `sourceAssetId` string, uuid, nullable — Root/source asset for a crop or slice; null for uploads.
  - `sourceOp` object, nullable — Transform provenance, e.g. {'type':'crop','rect':{...}}.
  - `variants` MediaAssetVariantDTO[]
    - `preset` string, required — Derivative name, e.g. 'pwa_logo_192', 'thumb_512'.
    - `url` string, required — Public URL of the variant object.
    - `width` integer, nullable
    - `height` integer, nullable
  - `usages` MediaAssetUsageDTO[]
    - `entityType` string, required — Consumer type: pwa | pwa_template | ...
    - `entityId` string, uuid, required
    - `field` string, required — Field on the consumer: logo | background | screenshot | ...
    - `position` integer, nullable — Ordering within a repeated field (screenshots).
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, nullable

## Other responses

- `413` — Request Entity Too Large
- `415` — Unsupported Media Type
- `422` — Unprocessable Entity

---

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