For the complete documentation index, see llms.txt. This page is also available as Markdown.

Reserve signed uploads in bulk

Reserve signed uploads in bulk with the FLORA API: POST /assets/reserve.

Reserves up to 25 signed uploads in one request — the batch counterpart of POST /assets with source="signed-url", counted once against the workspace's rate limit instead of once per file. workspace_id, project_id and folder apply to every upload; an upload's own folder overrides the shared one. Each entry in assets echoes its index and carries either the single reservation's fields (asset_id, upload, upload_url, expires_at, url) or ok false with an error; a failed entry, such as an unsupported content_type, never stops the rest. A workspace this credential cannot write, or a project_id outside the workspace, fails the whole request. Upload each file's bytes with its upload descriptor, then finish them in one call with POST /assets/complete. As on the single reservation, project_id places each asset on the canvas when it completes. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate, and a batch whose every entry was rejected releases its key (see the Idempotency guide).

POST https://app.flora.ai/api/v1/assets/reserve
  • Auth: API key as a bearer token, Authorization: Bearer $FLORA_API_KEY. See Authentication.

  • TypeScript SDK: client.assets.reserveUploads().

  • Idempotency: optional Idempotency-Key header. See Idempotency.

  • Operation ID: reserveAssetUploads.

Example

curl -X POST 'https://app.flora.ai/api/v1/assets/reserve' \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "workspace_id": "ws_abc123",
  "uploads": [
    {
      "file_name": "hero.png",
      "content_type": "image/png",
      "folder": "campaign-assets"
    }
  ]
}'
import { FloraClient } from '@flora-ai/flora';

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

const asset = await client.assets.reserveUploads({
  workspace_id: 'ws_abc123',
  uploads: [
    {
      file_name: 'hero.png',
      content_type: 'image/png',
      folder: 'campaign-assets',
    },
  ],
});
console.log(asset);

Request body

Required.

Field
Type
Required
Description

workspace_id

string

Yes

Workspace identifier. Use the public API ID returned by list workspaces; it must start with ws_. Pattern: ^ws_\S+$. Example: ws_abc123.

project_id

string

No

Project identifier. Use the public API ID returned by list projects; it must start with prj_. Every upload is reserved against this project and lands on its canvas once completed. Pattern: ^prj_\S+$. Example: prj_abc123.

folder

string

No

Destination folder for uploads that set none. Example: campaign-assets.

uploads

array of objects

Yes

Uploads to reserve, 1 to 25 per call. 1 to 25 items.

uploads[].file_name

string

No

Asset file name. Example: hero.png.

uploads[].content_type

string

No

Asset content type, pinned in this upload's policy. Example: image/png.

uploads[].folder

string

No

Destination folder for this upload. Example: campaign-assets.

Responses

200: Uploads reserved; each entry reports its own outcome.

Field
Type
Required
Description

assets

array of objects

Yes

One entry per requested upload, in request order: ok true with the single reservation's fields, or ok false with error. At most 25 items. See the assets[] shapes below.

assets[] shapes

Field paths in this block are relative to assets[].

assets[] takes one of 2 shapes, set by ok.

Shape 1: ok is true.

Field
Type
Required
Description

asset_id

string

Yes

Asset identifier. Pattern: ^asset_\S+$. Example: asset_abc123.

uploaded_via

string

Yes

Always signed_url.

url

string (uri)

Yes

Asset URL

workspace_id

string

Yes

Workspace identifier. Pattern: ^ws_\S+$. Example: ws_abc123.

visibility

string

Yes

Always workspace.

status

string

Yes

One of: pending_upload, ready, failed.

upload

object

Yes

upload.url

string (uri)

Yes

Upload URL

upload.method

string

Yes

Always POST.

upload.content_type

string

Yes

Always multipart/form-data.

upload.file_field

string

Yes

Always file.

upload.form_fields

map of string

Yes

Upload form fields

upload_url

string

Yes

Upload URL (serialized). Example: https://storage.googleapis.com/flora-user-assets.

expires_at

string (date-time)

Yes

Expiration time for the upload URL

index

integer

Yes

Position of this entry in the request's list. At least 0.

ok

boolean

Yes

This upload was reserved. Always true.

Shape 2: ok is false.

Field
Type
Required
Description

index

integer

Yes

Position of this entry in the request's list. At least 0.

ok

boolean

Yes

This entry failed; error says why. Always false.

error

object

Yes

Why this entry failed

error.code

string

Yes

Stable public API error code, as the single-asset operation would return it. Example: input_validation_error.

error.message

string

Yes

Human-readable reason this entry failed

Errors

Every error has the same body: error.code, error.message, and error.fields on validation errors. See Errors for how to recover from each code.

Status
Code
Meaning

400

invalid_json, input_validation_error

The body isn't valid JSON, or an input failed validation (fields lists each one).

401

unauthorized, invalid_api_key

The API key is missing, invalid or revoked.

402

insufficient_credits

The workspace balance is too low for this request.

403

forbidden, paid_plan_required

The key can't do this, or the workspace plan doesn't include it.

404

not_found

The resource doesn't exist or isn't visible to this key.

409

idempotency_duplicate, revision_conflict

Duplicate Idempotency-Key or a stale base_revision.

429

rate_limited

Too many requests. Back off and retry.

500

unknown_error, internal_error

Something failed on FLORA's side. Retry with backoff.

503

temporarily_unavailable

Authorization is temporarily unavailable. Retry later.

Last updated

Was this helpful?