Work with objects

Listings return object metadata, immediate child prefixes, an opaque cursor, and a truncated flag. Pass a page cursor unchanged to fetch the next page. Use iterateObjects() when you want an async iterator over all pages.

const firstPage = await storage.listObjects({ prefix: 'avatars/', limit: 50 })
const allAvatars = storage.iterateObjects({ prefix: 'avatars/', limit: 100 })

const avatar = await storage.getMetadata('avatars/user-42.png')
const exists = await storage.exists('avatars/user-42.png')

exists() returns false only when the object is missing. Authorization and network errors still reject.

DownloadCopy Anchor Link

createDownloadUrl() returns a signed URL and its required request headers. downloadObject() fetches the object and returns a native Response.

const response = await storage.downloadObject('avatars/user-42.png')
const image = await response.blob()

Signed URLs are bearer links until they expire. Choose a short expiry when sharing a URL, and do not log or persist it beyond its intended use. The expiry option is limited to seven days.

Metadata and object operationsCopy Anchor Link

Use updateMetadata(key, patch) for HTTP metadata and custom metadata. Use deleteObject() for one key or deleteObjects() for up to 100 unique keys. A delete result includes successful keys and per key errors.

await storage.updateMetadata('avatars/user-42.png', {
  cacheControl: 'public, max-age=3600',
  customMetadata: { source: 'profile' },
})

await storage.copyObject('avatars/user-42.png', 'archive/user-42.png')
await storage.moveObject('temporary/new.png', 'avatars/new.png', { overwrite: true })

Copies and moves stay within the configured bucket. Object keys are relative paths. The client rejects leading slashes, path traversal segments, control characters, backslashes, and Carpo's reserved internal prefix.

Bucket policy remains authoritative. The SDK does not expose bucket configuration, policy editing, or admin usage controls.