Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Give users reliable upload feedback and a library that remains searchable and safe to operate as it grows.

​
Prerequisites

  • A browser or backend client
  • An authenticated API session for management actions
  • A policy for key prefixes, visibility, retention, and content types

​
Workflow

1
Use normal upload for small server-side files and a single or chunked upload session for browser or unreliable-network uploads.
2
Resume a chunked upload by reading the session’s received parts, retry only missing parts, and complete it once every required part is present.
3
Attach key prefixes, visibility, cache control, and metadata at upload time; use revision-checked mutations for later edits.
4
Drive library views with keyset cursors and filters such as status, scan state, moderation state, folder, tag, MIME type, and checksum.
5
Use collections, saved searches, lifecycle rules, and webhooks to turn the library into an operational workflow.

​
Chunked upload flow

The SDK’s uploadWithProgress uses a 5 MiB default part size above the single-upload threshold, four workers by default (bounded to 1–8), and four attempts with backoff (bounded to 1–8). Pass an AbortSignal to cancel in-flight work; the SDK then attempts to cancel the server session.

​
List and filter the library

The list endpoint returns assets, total, and an optional next_cursor. Sorting is limited to created_at, updated_at, size, key, original_name, or mime_type; use the cursor rather than offset pagination for a stable walk through a changing library.

​
Revision-safe management

Asset, bucket, and AI-policy mutations are optimistic-concurrency checked. Read the current object, send its revision as If-Match (the SDK does this for you), and reload after a 412 conflict. Deletes return an asynchronous job submission; purge is a separate immediate hard-delete operation and should be reserved for an intentional retention decision.

​
Buckets, retention, and organization

  • Virtual folders are key prefixes such as users/42/avatars/; there is no separate folder object.
  • Buckets carry default visibility, versioning, retention days, per-object limits, allowed MIME types, CORS/allowed origins, cache control, and the global-3 replication policy. That policy does not create extra deployment servers; actual replica health is reported by each asset’s replication_status.
  • Lifecycle rules can delete objects or expire_versions after an age, optionally scoped by prefix.
  • Collections are explicit asset ID sets; saved searches persist a name plus filter object for reusable views.
  • Tags are normalized; checksum groups power duplicate hints and the usage summary.

​
Bulk operations, events, and webhooks

Bulk actions accept revisioned items and support delete, visibility, and add_tags; the response is a job submission with job_id, status, and status_url. Usage is available through usageSummary, while events returns the audit stream. A webhook created with createWebhook returns its signing secret once—store it immediately—and delivery failures can be listed and retried.

​
Expected result

Users see honest progress and readiness states, can recover interrupted uploads, and can manage a searchable asset library without race-prone overwrites.

Direct browser uploads

Upload browser files directly with short-lived sessions, per-part checksums, progress callbacks, retries, resume, and cancellation.

AI DAM and versioning

Use configured asset AI jobs, moderation, transcripts, derived images, collections, saved searches, and branching versions with explicit readiness and spend controls.