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

​
Goal

Choose the right Assets workflow, understand when an asset is deliverable, and know which API or SDK method owns each operation.

​
Prerequisites

  • A StackShift API key kept on a server or trusted worker
  • A backend HTTP client or an official SDK

​
Workflow

1
Create or let the API create a bucket. A bucket supplies defaults for visibility, cache control, versioning, size, MIME policy, and replication.
2
Keep managed storage or attach a verified S3-compatible or native S2 destination. Changing storage affects new writes; use relocation for historical objects.
3
Upload a file with a bucket and key, or create a short-lived upload session for browser and resumable flows.
4
Import provider libraries through a dry run and durable migration, or enable OCR for searchable PDF and image text.
5
Wait for the asset to become ready. Public URLs and signed URLs fail closed while scan, moderation, or replica gates are not satisfied.
6
Deliver the current version with the returned public URL, a signed URL, a named transform, a signed transform, or a version/branch URL.
7
Use revision-aware mutations for rename, visibility, metadata, tags, replace, and delete. Treat delete and AI/media processing as asynchronous where the API returns a job.
8
Use list filters, collections, saved searches, events, webhooks, usage summaries, and lifecycle rules to operate the library at scale.

​
The product model

Assets is account-scoped by the API key. A deployed StackShift project ID is not required. The public control-plane API defaults to https://api.stackshift.cloud/api/v1; the CDN URL returned by the SDK defaults to https://cdn.stackshift.cloud. A logical asset is addressed by a bucket and key, but the API returns an opaque asset ID and a revision. Keep the asset ID in your application database. Treat the key as a human-facing namespace, not as a filesystem path.
  • Buckets are policy containers. Uploading to a new bucket name creates it with private visibility and versioning enabled unless an existing bucket says otherwise. The global-3 replication policy is the storage target, not a claim that three deployment servers are currently connected; replication_status reports what is actually available in this installation.
  • Keys are slash-separated names such as users/user_123/avatar.png. The service rejects traversal, empty path segments, NUL bytes, and keys longer than 1,024 characters.
  • Metadata is valid JSON. Tags, metadata, cache control, visibility, original name, and key can be changed after upload, subject to the current revision.
  • Cloudflare can provide the edge and cache layer, but persistent asset bytes remain behind the StackShift Assets origin.

​
Asset readiness and delivery gates

An upload response identifies the asset; it is not a promise that the bytes are immediately public. The service moves the asset through processing, ready, quarantined, failed, deleting, and deleted. Delivery requires status=ready, an available current version, a usable replica, and any configured scan or moderation gates.
  • scan_status: pending, clean, infected, failed, or skipped.
  • replication_status: pending, replicated, degraded, or failed.
  • quarantine_status: none, infected, or policy.
  • video_status: none, pending, processing, ready, failed, or skipped.
  • ai_status: pending, processing, ready, failed, or skipped; moderation has its own pending, processing, clean, flagged, quarantined, and failed states.
  • When a public asset is replaced, its generation and current version change. Version-qualified URLs prevent an old cached byte from being mistaken for the new version.

​
Choose a workflow

  • Small server-side file: assets.upload / Assets.Upload / assets.upload with multipart form data.
  • Browser or unreliable network: create a single or chunked upload session, then PUT to the signed URL. Chunked sessions carry a part size, per-part SHA-256, resume state, completion, and cancellation.
  • Public image: use asset.url for the current original, a named transform URL for a reusable preset, or a signed transform URL for a server-selected spec.
  • Private file: upload with visibility=private, mint a short-lived signed URL on the server, and pass only the URL to the browser.
  • Media intelligence: enqueue analyze, moderation, transcript, smart-crop, or background-removal work and poll the returned status_url.
  • Provider migration: verify a Cloudinary, S3-compatible, or native S2 source, run inventory first, then import with checksum deduplication and a retained report.
  • Customer storage: attach AWS S3, R2, Wasabi, MinIO, generic S3, or native S2 while keeping the StackShift CDN URL.
  • Embeddable uploads: issue one-session browser capabilities from your backend and render @stackshift-cloud/assets-widget for local, camera, URL, crop, preview, and resumable flows.
  • Document search: run OCR manually or enable it per bucket; ready extracted text joins the existing Assets query search.
  • Deterministic media: use an ordered v2 definition for image/video transforms, audio extraction, timestamp thumbnails, overlays, and eager named presets.
  • Automation: build an editable media workflow, use governed Stackie/MCP asset tools, invoke native StackShift actions, and reserve the restricted HTTP node for approved external integrations.
  • Content operations: use buckets, list filters, revision-aware patches, bulk jobs, collections, saved searches, webhooks, and lifecycle rules rather than rebuilding those controls in the client.

​
What the API returns

  • Identity and bytes: id, bucket, key, original_name, mime_type, size, and checksum_sha256.
  • Policy and state: visibility, cache_control, status, replication_status, scan/quarantine/video/AI statuses, and delivery_revoking when a visibility change is being applied.
  • Organization: metadata, tags, generation, revision, created_at, updated_at, and the current version/branch identifiers.
  • Delivery: url only when a public asset is ready; video and AI objects are present when their asynchronous jobs have produced results.
  • The API deliberately omits storage node IDs, replica paths, local disk paths, and internal asset-space identifiers.

​
Expected result

You can implement an end-to-end upload and delivery flow without guessing at URL formats, lifecycle states, concurrency rules, or which features are asynchronous.

Assets REST API reference

The routes, wire fields, response states, and concurrency rules shared by every official Assets SDK.

Assets SDK quick start

Install the official SDKs, upload a first asset, and handle the readiness state before you publish its URL.

Image optimization

Use the current transform grammar, named presets, and signed dynamic transforms for predictable image delivery.

Upload UX and DAM

Build a durable upload and digital-asset-management workflow with resumable sessions, revision-safe mutations, search, collections, webhooks, and usage summaries.

Video, scanning, and governance

Process video asynchronously, deliver HLS and posters, expose scan gates, quarantine unsafe assets, and enforce account policies.

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.

Storage connections, BYOB, and StackShift S2

Configure AWS S3, Cloudflare R2, Wasabi, MinIO, generic S3, or native StackShift S2 without exposing customer storage credentials or changing delivery URLs.

Cloudinary, S3, R2, and S2 migrations

Inventory, dry-run, import, deduplicate, retry, cancel, and report durable migrations from Cloudinary or S3-compatible storage into StackShift Assets.

Embeddable Assets upload widget

Install @stackshift-cloud/assets-widget for React or vanilla JavaScript with constrained backend-issued capabilities, resumable chunks, camera and URL input, cropping, previews, progress, retry, and cancellation.

OCR, document intelligence, and DAM search

Extract embedded PDF text or OCR PDF and image pages asynchronously, inspect normalized word geometry, cache by content identity, and search extracted text in the DAM.

Deterministic image, video, and audio transforms

Define ordered v2 transforms for images, video renditions, audio extraction, and timestamp thumbnails; store eager presets or materialize durable derivatives.

Stackie asset tools and MCP

Use the same governed asset actions from Stackie, workflow Stackie nodes, and stateless Streamable HTTP MCP clients.

Media Workflows visual builder and API

Author editable templates or blank typed DAGs that coordinate asset gates, native StackShift services, bounded Stackie reasoning, and approved external integrations.

Media Workflow authority, integrations, and recovery

Operate workflow grants, execution principals, durable waits, restricted HTTP connections, signed inbound hooks, retries, cancellation, and post-publish warnings.