Assets

Assets represent media files available to FLORA workflows. For user-supplied images or videos, create an asset, upload the bytes to the returned signed upload URL, then mark the asset complete. The source field must always be a string: either "signed-url" for direct upload, or an allowlisted HTTPS URL for server-side fetch.

Reserve a signed upload

curl -X POST https://app.flora.ai/api/v1/assets \
  -H "Authorization: Bearer sk_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "signed-url",
    "workspace_id": "ws_XXXX",
    "file_name": "product.png",
    "content_type": "image/png",
    "folder": "api-uploads"
  }'

Response:

{
  "asset_id": "asset_...",
  "url": "https://ik.imagekit.io/flora/...",
  "status": "pending_upload",
  "upload": {
    "url": "https://...",
    "formFields": {},
    "fileField": "file"
  }
}

Create from an allowlisted URL

If your source file is already available at an allowlisted HTTPS URL, pass that URL as source:

curl -X POST https://app.flora.ai/api/v1/assets \
  -H "Authorization: Bearer sk_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "https://media.flora.ai/example.png",
    "workspace_id": "ws_XXXX"
  }'

Do not pass objects such as { "url": "..." }, local file paths, data: URLs, or placeholder strings such as "upload", "file", or "local" as source.

Upload the file bytes

Submit the returned upload.formFields and file to upload.url as multipart form data. The upload target is external to the FLORA API, so do not include your FLORA authorization header in that request unless the returned upload instructions say to.

Complete the asset

After uploading bytes, complete the asset:

curl -X POST https://app.flora.ai/api/v1/assets/asset_XXXX/complete \
  -H "Authorization: Bearer sk_live_XXXX"

A completed asset has status: "ready" and can be passed to technique inputs or attached to projects.

List assets

curl "https://app.flora.ai/api/v1/assets?workspace_id=ws_XXXX&limit=10" \
  -H "Authorization: Bearer sk_live_XXXX"

Retrieve an asset

curl https://app.flora.ai/api/v1/assets/asset_XXXX \
  -H "Authorization: Bearer sk_live_XXXX"

Retry an upload

If a pending upload expires or fails, request fresh upload instructions:

curl -X POST https://app.flora.ai/api/v1/assets/asset_XXXX/retry \
  -H "Authorization: Bearer sk_live_XXXX"

Retry is only valid for supported asset lifecycle states. If the asset cannot be retried, the API returns a validation or lifecycle error.

Common endpoints

Method	Path	Description
POST	/api/v1/assets	Create an asset or reserve a signed upload
POST	/api/v1/assets/{asset_id}/complete	Mark an uploaded asset complete
GET	/api/v1/assets?workspace_id={workspace_id}&limit=10	List assets
GET	/api/v1/assets/{asset_id}	Retrieve an asset
POST	/api/v1/assets/{asset_id}/retry	Request new upload instructions
POST	/api/v1/projects/{project_id}/assets/{asset_id}/attach	Attach an asset to a project

Common validation issues

• source is required and must be a string.
• Use "signed-url" when you need FLORA to reserve upload instructions for bytes you will upload yourself.
• Server-side URL fetch only accepts HTTPS URLs from allowlisted hosts. If the host is not allowlisted, either use the signed upload flow or send feedback with kind: "missing_capability".
• workspace_id is required and must start with ws_.

Notes

• Technique input URLs must be HTTPS.
• Wait for status: "ready" before using a newly uploaded asset as a workflow input.
• Keep the final url if you need to pass the asset directly to an imageUrl or videoUrl input.