Skip to main content

Create an asset (managed upload or BYO URL)

POST 
/program/api/v2/projects/:projectID/assets
warning

This endpoint is available in private cloud only. Use your global host URL if self-hosted.

Creates a new project-scoped asset row. Two modes:

storageMode=managed — bytes are uploaded server-side to Backblaze (program receives the multipart body and streams it to B2). On first managed asset per project, this request also lazy-provisions the project's B2 storage account (D10b), adding ~1-3s to the response time. Subsequent uploads skip provisioning. Upload ceiling is configurable per deployment (default 10 MiB per design.md C8).

storageMode=byo — caller supplies publicUrl in the metadata JSON; program issues an opportunistic HEAD against the URL to seed contentType and sizeBytes (per Q7). The file part is ignored for BYO mode. HEAD failures (404, timeout, HEAD-disallowed CDNs) do NOT block the create.

Request body is multipart/form-data with two parts:

  • metadata: JSON-encoded CreateAssetMetadata
  • file: the asset bytes (managed mode only)
Generate JWT

Request​

Responses​

Asset created

Validation failure (invalid id charset, missing field, bad URL, etc.)

Forbidden — no project access

Asset id already exists in this project

Upload exceeds max_upload_bytes

Internal Server Error

Managed storage not configured / not ready for this deployment