Assets platform API, SDK, CLI, and operations

​

Goal

​

Prerequisites

• A StackShift API token with the narrowest required Assets scope
• The current JavaScript SDK or StackShift CLI when not calling REST directly
• Access to Assets Operations in the dashboard for visual connection, migration, relocation, and OCR workflows

​

Workflow

​

Authentication, response rules, and scopes

• assets:read: list/get connections, S2 buckets, migrations and reports, text results, buckets, assets, usage, and events.
• assets:write: create browser upload capabilities and change bucket storage configuration. Existing upload and library-write routes also use this scope.
• assets:process: start/cancel migrations, start relocation, retry migration items, start/retry OCR, and invoke other transform/AI processing routes.
• assets:generate: create net-new private images through the governed generation job.
• assets:publish: publish/activate governed workflow versions and decide publication-bearing approvals.
• assets:admin: create/update/verify/delete provider connections, create an owned S2 bucket, and perform destructive or credential administration.
• An assets:admin token permits all Assets routes. Read methods are also permitted by assets:write and assets:process; prefer including assets:read explicitly when minting purpose-specific automation tokens.

​

Connection and storage REST routes

• POST /assets/connections (assets:admin, 201): create a tenant-scoped external, S2, or Cloudinary connection.
• GET /assets/connections and GET /assets/connections/{connectionID} (assets:read, 200): return redacted configuration and verification state.
• PATCH /assets/connections/{connectionID} (assets:admin, 200): change display/configuration fields or replace a secret without returning it.
• POST /assets/connections/{connectionID}/verify (assets:admin, 200): perform the provider probe and persist the result.
• DELETE /assets/connections/{connectionID} (assets:admin, 200): revoke/delete only when no protected reference remains.
• GET /assets/s2-buckets (assets:read, 200) and POST /assets/s2-buckets (assets:admin, 201): list or create user-owned S2 buckets for Assets.
• PUT /assets/buckets/{bucketID}/storage (assets:write, 200): set storage_mode, backend reference, prefixes, auto_extract_text, and expected revision. Send the revision in If-Match or expected_revision.
• POST /assets/buckets/{bucketID}/relocations (assets:process, 202): create a relocation inventory with optional dry_run.

​

Migration, OCR, and capability REST routes

• POST /assets/migrations (assets:process, 202): start import or relocate with source connection, destination bucket, prefix, conflict policy, and dry-run mode.
• GET /assets/migrations?limit=N and GET /assets/migrations/{migrationID} (assets:read, 200): read persisted summaries and progress.
• POST /assets/migrations/{migrationID}/cancel (assets:process, 200): request cooperative cancellation.
• POST /assets/migrations/{migrationID}/items/{itemID}/retry (assets:process, 202): requeue one terminal failed item.
• GET /assets/migrations/{migrationID}/report?format=json|csv (assets:read, 200): download the complete JSON report or CSV projection.
• POST /assets/{assetID}/text-extraction (assets:process, 202): start or link a cached extraction with language and options.
• GET /assets/{assetID}/text-extraction (assets:read, 200) and POST /assets/text-extractions/{extractionID}/retry (assets:process, 202): read or retry OCR.
• POST /assets/upload-capabilities (assets:write, 201): create the one-time browser capability. The token is returned only in this response.

​

Capability-only widget routes

• POST /assets/widget/sessions: create one chunked session from the capability; request fields are key, file_name, file_size, mime_type, optional checksum_sha256, part_size, and metadata.
• GET /assets/widget/sessions/current: reconcile the capability-bound session and its received parts.
• PUT /assets/widget/uploads/{sessionToken}/parts/{partNumber}: stream one part with X-Content-SHA256.
• POST /assets/widget/sessions/current/complete: verify and commit the asset, then revoke the capability.
• DELETE /assets/widget/sessions/current: cancel temporary upload state and revoke the capability.
• POST /assets/widget/remote-url: ingest { url, key } only when the capability explicitly permits remote URLs.
• CORS allows only the normalized origin carried by the request and the capability. Allowed headers are Authorization, Content-Type, and X-Content-SHA256; the exposed response header is ETag.

​

JavaScript SDK clients

• assets.connections: create, list, get, update, verify, and delete.
• assets.storage: configure, listS2Buckets, createS2Bucket, and relocate.
• assets.migrations: start, list, get, cancel, retryItem, report, and downloadReport. Use downloadReport for raw JSON/CSV Blob data.
• assets.text: start, get, and retry.
• assets.uploadCapabilities: create for trusted backend code only.
• assets.workflows: catalog, draft CRUD, validation, publish/activate, versions, runs, approvals, restricted HTTP connections, credential rotation, and inbound-hook rotation.
• assets.materializeTransform, derivatives, generate, and automation cover durable v2 transforms, generated images, and governed MCP discovery.
• ChunkedUploadController is the framework-neutral upload engine shared by the SDK and widget; it owns per-part SHA-256, bounded concurrency, retries, cancellation, persistence, fingerprint validation, and server-part reconciliation.

​

CLI command patterns

• Connection commands: connection-create, connections, connection-get, connection-update, connection-verify, and connection-delete.
• Storage commands: s2-buckets, s2-bucket-create, bucket-storage-set, and relocate.
• Migration commands: migration-start, migrations, migration-get, migration-cancel, migration-item-retry, and migration-report.
• OCR and widget-backend commands: ocr-start, ocr-get, ocr-retry, and upload-capability-create.
• Media commands: transform-run, derivatives, generate, and automation.
• Workflow commands: catalog/list/create/get/draft-update/validate/publish/activate, versions/runs, run detail/cancel/retry, approvals, connections, credential rotation, and inbound-hook rotation.

stackshift asset connections --output json
stackshift asset connection-verify CONNECTION_UUID --output json
stackshift asset bucket-storage-set BUCKET_UUID --data '{"storage_mode":"managed","expected_revision":4}' --output json
stackshift asset relocate BUCKET_UUID --wait --data '{"dry_run":true}' --output json
stackshift asset migrations --query limit=50 --output json
stackshift asset migration-report MIGRATION_UUID --query format=csv --download ./migration.csv
stackshift asset ocr-start ASSET_UUID --wait --data '{"language":"eng"}' --output json
stackshift asset workflow-catalog --output json
stackshift asset workflow-run-get RUN_UUID --output json

​

Durability and concurrency guarantees

• Production runs a dedicated Assets worker with four durable-job slots. External provider work and OCR are separately bounded to two concurrent operations each by default.
• Job and migration-item claims use database leases, heartbeats, unique lease tokens, fencing, expired-lease recovery, bounded attempts, and monotonic persisted progress. A stale worker cannot checkpoint or complete work after losing its lease.
• Worker crashes and restarts recover expired work. Duplicate job delivery and repeated inventory are idempotent; migration source identities and checksum checks prevent duplicate assets.
• Streaming uses bounded temporary scratch rather than loading entire provider objects into memory. Completion, cancellation, timeout, and recovery clean scratch and abort incomplete multipart uploads.
• Cancellation races fail closed: a canceled operation cannot later be completed by a stale claimant.

​

Events, reports, and observable state

• Audit/event names include asset.connection.created, .updated, .verified, .deleted, asset.bucket.storage_changed, migration .started, .completed, .failed, .canceled, relocation .completed/.failed, and OCR .completed/.failed.
• Use GET /assets/events and existing Assets webhooks for customer-visible lifecycle evidence. Event payloads carry IDs and states, not stored secrets, signed URLs, or capability tokens.
• Migration reports remain available after completion, failure, or cancellation and are authoritative for item outcomes. source_identity is the provider-side correlation key.
• The dashboard Assets Operations area exposes Storage, Connections, Migrations, and OCR panels with verification results, live progress, report download, retry/cancel actions, relocation state, and geometry inspection.

​

Recovery playbooks

• Stalled queue or worker crash: confirm worker/database/provider health, allow the lease to expire, restart normally, and verify persisted counters resume. Never edit leases or delete operation rows.
• Static credential rotation: update the encrypted connection secret, verify the connection, then revoke the old provider key. AWS AssumeRole rotation should retain the connection external ID while the customer role policy/trust is updated.
• Provider outage: keep connection and migration records. Restore provider access first; managed objects remain independent while objects recorded on the unavailable backend can produce origin failures.
• checksum_mismatch: leave the source reference unchanged, remove/quarantine the bad destination object, investigate transport/provider integrity, and retry.
• source_delete_failed: the verified destination is already authoritative. Restore source-provider access and remove only the recorded old object; do not roll back the database storage reference.
• OCR provider_failed: verify the asset is readable and Poppler, Tesseract, requested language data, and scratch capacity are healthy, then retry the extraction ID.
• Multipart cleanup alert: restore the exact provider connection, identify incomplete uploads by the known StackShift prefix/session identity, and abort only those uploads. Never bulk-delete a customer bucket.

​

Security, deletion, and billing invariants

• Secrets are encrypted with connection-specific authenticated data, redacted from responses, and forbidden from logs, reports, events, and URLs. Browser capabilities are stored hashed and expire within one hour.
• Generic endpoints require public HTTPS, reject redirects and userinfo, validate DNS before use, and revalidate resolved addresses at connection time to block private/reserved targets and DNS rebinding.
• A connection or S2 bucket cannot be deleted while referenced by bucket storage, active uploads, migrations, relocations, or available storage objects. Remove references safely; do not bypass the check.
• Relocation never deletes the source before destination checksum verification and atomic reference commit. A failed relocation remains readable from the original backend.
• Managed, BYOB, and S2 assets all count toward logical Assets quota, ingress/egress, processing, OCR, and CDN usage. Only StackShift-managed Assets bytes accrue Assets managed physical-storage byte-hours; native S2 is accounted by the Object Store product.

​

Expected result

​

Common failures

​

Related guides