Skip to content
FLORA FLORA API

Create an asset upload

POST
/assets
 
import { FloraClient } from '@flora-ai/flora';


const client = new FloraClient({ apiKey: process.env['FLORA_API_KEY'] });


const asset = await client.assets.create({
  source: 'signed-url',
  workspace_id: 'ws_abc123',
});
console.log(asset);

Creates an asset via one of three paths. (1) Direct bytes: send multipart/form-data with a file part (≤4 MB) plus workspace_id — FLORA stores the bytes and returns a ready asset in one call. (2) Server-side fetch: send JSON with source set to any public HTTPS URL (≤50 MB) — FLORA fetches the bytes with SSRF protection (private/loopback/metadata IPs and redirects to them are blocked) and stores them. (3) Signed upload: send JSON with source=“signed-url” to reserve a presigned upload URL for files larger than 4 MB; upload the bytes, then call the complete endpoint. Allowed types: images (jpeg, png, webp, gif, avif, heic, heif), video (mp4, webm, quicktime), audio (mpeg, wav, ogg), and pdf; images are capped at 150 MP. Pass project_id on any path to also surface the asset on that project’s canvas. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.

Error responses use the standard error body.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
object
source
required

Asset source as a string: either “signed-url” to reserve a direct upload URL, or an allowlisted HTTPS URL for server-side fetch.

string
workspace_id
required

Workspace identifier. Use the public API ID returned by list workspaces; it must start with ws_.

string
project_id

Project identifier. Use the public API ID returned by list projects; it must start with prj_. When provided, the uploaded asset is also surfaced on the project’s canvas.

string
folder

Destination folder

string
content_type

Asset content type

string
file_name

Asset file name

string

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Asset upload created.

Media type application/json
object
asset_id
required

Asset identifier

string
/^asset_\S+$/
uploaded_via
required

Asset source: “url” (server-side fetch), “signed_url” (presigned upload reservation), or “direct” (multipart bytes streamed in this request).

string
Allowed values: url signed_url direct
url
required

Asset URL

string format: uri
workspace_id
required

Workspace identifier

string
/^ws_\S+$/
visibility
required
Allowed value: workspace
status
required
string
Allowed values: pending_upload ready failed
upload
object
url
required

Upload URL

string format: uri
method
required
Allowed value: POST
content_type
required
Allowed value: multipart/form-data
file_field
required
Allowed value: file
form_fields
required

Upload form fields

object
key
additional properties
string
upload_url

Upload URL (serialized)

string
expires_at

Expiration time for the upload URL

string format: date-time
Example 
{
  "asset_id": "asset_abc123",
  "uploaded_via": "url",
  "workspace_id": "ws_abc123",
  "visibility": "workspace",
  "status": "pending_upload",
  "upload": {
    "method": "POST",
    "content_type": "multipart/form-data",
    "file_field": "file"
  },
  "upload_url": "https://storage.googleapis.com/flora-user-assets"
}