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/reserveAuth: API key as a bearer token,
Authorization: Bearer $FLORA_API_KEY. See Authentication.TypeScript SDK:
client.assets.reserveUploads().Idempotency: optional
Idempotency-Keyheader. 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.
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.
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.
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.
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?