---
title: "Initialize an asset upload"
method: POST
path: "/assets"
tags: ["Assets"]
---

# Initialize an asset upload

`POST /assets`

Creates a pending asset and returns presigned upload URL(s). Files at or below the single-PUT threshold get one PUT URL; larger files get multipart part URLs. If a ready asset with the same checksum already exists, the existing asset is returned (deduplicated).

## Request body

- object
  - `filename` string, required — Original filename
  - `size` integer, required — File size in bytes
  - `contentType` string — MIME content type
  - `checksum` string — Client-declared sha256 (enables dedup)
  - `lifecycle` 'ephemeral' | 'persisted' — Storage lifecycle (defaults to ephemeral)

## Response `200`

Deduplicated — a ready asset with this checksum already exists

- object
  - `status` string, required — presigned | multipart | deduplicated
  - `data` object, required
    - `id` string, required — Asset ID (e.g., asset_abc123def456)
    - `url` string, required — Stable content URL — pass this as a job input; resolves to a presigned GET at dispatch
    - `orgId` string, required — Organization ID that owns this asset
    - `createdBy` string, nullable, required — User ID that created the asset
    - `lifecycle` string, required — ephemeral | persisted
    - `status` string, required — pending | uploading | ready | failed | expired
    - `source` string, required — upload | url | job_output
    - `kind` string, required — media | psd_template | font | other
    - `scope` string, required — org | system
    - `region` string, required — auto | eu
    - `etag` string, nullable, required — R2 etag recorded at finalize
    - `checksum` string, nullable, required — Client-declared sha256
    - `declaredSize` integer, nullable, required — Client-declared size at init
    - `sizeBytes` integer, nullable, required — Measured size at finalize
    - `contentType` string, nullable, required — MIME content type
    - `mediaType` string, nullable, required — video | image | audio | font | other
    - `filename` string, nullable, required — Sanitized display filename
    - `expiresAt` integer, nullable, required — Ephemeral TTL (Unix ms)
    - `metadata` string, nullable, required — JSON probe results
    - `createdAt` integer, required — Creation timestamp (Unix ms)
    - `updatedAt` integer, required — Last update timestamp (Unix ms)
  - `upload` unknown

## Other responses

- `201` — Pending asset created with presigned upload URL(s)
- `401` — Unauthorized
- `413` — File exceeds the plan's upload size limit
- `429` — Too many uploads in progress

## Changes

> 7 revisions in range; 5 could not be searched.

- **2026-08-29** `4d10ec4266ee` — 1 info
  - api operation id `createAsset` was added

[Change history](https://skmtc.dev/rendobar/apis/rendobar-api/changes/assets/post.md)

---

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