Upload a file to the DAM

POST https://upload.fluid.app/upload is the one supported way to add a file to your company’s DAM from your own code. It takes the file, stores it, and returns the new asset in one request.

Use this endpoint rather than Fluid’s lower-level asset endpoints. Those are internal steps of the upload flow and can change without notice.

Before you start

Call it from your server. Authenticate with a company token or a partner token whose role can update media. Never send either token to a browser.
The asset goes to the token’s company.
Use this host, not api.fluid.app. The upload service runs on upload.fluid.app.

Upload a file

Send the file as multipart/form-data:

curl -X POST "https://upload.fluid.app/upload" \
  -H "Authorization: Bearer <token>" \
  -F "file=@summer-hero.jpg" \
  -F "fileName=summer-hero.jpg" \
  -F "name=Summer hero" \
  -F "description=Homepage banner for the July sale" \
  -F "tags=summer,homepage"

Field	Required	Description
`file`	Yes	The file to upload.
`fileName`	Recommended	The file name, including its extension. Fluid uses the extension to work out the file type. If you leave it out, the file part’s own filename is used.
`name`	No	The asset’s display name. Defaults to the file name without its extension. Letters, digits, spaces, and hyphens are kept; other characters are replaced.
`description`	No	A description stored on the asset.
`tags`	No	Comma-separated tags, for example `summer,homepage`.
`create_media`	No	Send `true` to also create a storefront media item from the upload. See Create a media item.

For a file larger than 100 MB, put the other fields before file in the form. Large uploads are streamed, and fields that arrive after the file are ignored.

Response

A successful upload returns 200 with the new asset:

{
  "asset": {
    "id": 51774,
    "code": "RF4QES",
    "name": "Summer hero",
    "description": "Homepage banner for the July sale",
    "category": "images",
    "created_at": "2026-09-29T15:02:11Z",
    "updated_at": "2026-09-29T15:02:11Z",
    "default_variant_id": 90211,
    "company": "Acme Wellness",
    "default_variant_url": "https://ik.imagekit.io/fluid/1234/summer-hero_Ab12Cd.jpg"
  }
}

default_variant_url is the file’s CDN address. Store id or code to refer to the asset later.

Create a media item

Send create_media=true to also create a media item from the upload, so it can be used in the storefront and the media widget. This applies to images, videos, and PDFs; other file types are uploaded to the DAM without a media item.

A media item created this way is active and published immediately, and it appears in the public media list. Only use create_media for files you mean to show shoppers. To stage content, upload without it and create the media item yourself as a draft with the storefront media API.

When create_media succeeds, the response also carries a media object with the new media item under medium.

Errors

Status	Meaning
`400`	The request is malformed: the wrong content type, or no `file`. The body is `{ "error": "..." }`.
`401`	The `Authorization` header is missing or isn’t a Bearer token.
`500`	Anything else, including an invalid token, a token without permission to update media, or a file that couldn’t be stored. The body is `{ "error": "..." }`, and its message isn’t stable — don’t parse it.

A 500 can arrive after the asset was stored — for example, when the asset was created but the media item wasn’t. Before retrying, check the DAM for the asset so you don’t upload it twice.

Authentication — company and partner tokens.
DAM picker — let people choose and upload files in your own UI.

Overview

Storefront

Commerce

Checkout

Members

Messaging

People

Payments

DAM

Website

Portal

Content and tools

Analytics

Sales channels

Settings

FairShare SDK

Droplets

Developers

Portal & Widgets

Upload a file to the DAM

Before you start

Upload a file

Response

Create a media item

Errors

​Before you start

​Upload a file

​Response

​Create a media item

​Errors

​Related

Before you start

Upload a file

Response

Create a media item

Errors

Related