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.

Upload from the CLI

The Fluid CLI’s assets plugin sends the same request for you. Install it, sign in with fluid login, then upload a local file or a file at a URL:

npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-assets
fluid assets upload ./summer-hero.jpg --name "Summer hero" --tags summer,homepage
fluid assets upload --url https://cdn.example.com/catalog/spring-lookbook.pdf

Give either a file path or --url, not both. --description sets the description, and --create-media also creates a media item, published at once, as described in Create a media item. The command prints the response below. fluid dam is another name for fluid assets.

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.

Upload from the command line

The Fluid CLI’s assets plugin wraps this endpoint. Install it next to the CLI, and sign in:

npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-assets
fluid login

Upload a local file, or have the upload service fetch one from a URL:

fluid assets upload ./summer-hero.jpg --name "Summer hero" --tags summer,homepage
fluid assets upload --url https://cdn.acme-wellness.com/banners/summer-hero.jpg --name "Summer hero"

fluid dam upload is the same command. Pass a file path or --url, not both. The command prints the service’s JSON response.

Option	Effect
`--url <url>`	Fetch the file from this URL instead of uploading a local file
`--name <name>`	The asset’s display name
`--description <description>`	The asset’s description
`--tags <tags>`	Comma-separated tags
`--folder <folder>`	Store the file under this folder path on the CDN
`--no-unique-filename`	Keep the file name as it is. By default the CDN adds a short suffix to keep each file name unique
`--create-media`	Also create a media item. It’s active and published straight away, as described in Create a media item

The command uses the token from fluid login. To use another one, pass it before the subcommand: fluid assets --token <token> upload ./summer-hero.jpg. Compress large images and videos before you upload them, so the pages that show them load faster.

Authentication — company and partner tokens.
DAM picker — let people choose and upload files in your own UI.
Upload a private file — profile pictures, contact photos, and other files that shouldn’t appear in the DAM.

Overview

Storefront

Commerce

Checkout

Member API

Member Sites APIs

Messaging

Cowork

People

Payments

DAM

Website

Portal

Mobile app

Content and tools

Analytics

Sales channels

Settings

FairShare SDK

Droplets

Developers

Unsorted endpoints

Portal & Widgets

Upload a file to the DAM

Before you start

Upload a file

Upload from the CLI

Response

Create a media item

Errors

Upload from the command line

Before you start

Upload a file

Upload from the CLI

Response

Create a media item

Errors

Upload from the command line

Related