Docs

Storage API reference

The Storage API is the set of methods your code calls on a linked Storage bucket, in the TypeScript, Python, and Rust SDKs. A binding is the connection details Alien injects into each workload linked to the resource, which the SDK client reads.

A handle comes from storage(name) in @alienplatform/sdk (TypeScript) or alienplatform (Python), or Bindings::from_env()?.storage(name).await? in alien-sdk (Rust). name is the resource ID from alien.ts.

Creating the TypeScript or Python handle does no I/O. The binding resolves on the first call and is cached. If the workload isn't linked to the resource, the first call throws BINDING_NOT_CONFIGURED.

Methods at a glance

TypeScriptPythonRustWhat it does
get(path)get(path), get_optional(path)get, get_range, get_optsRead an object.
put(path, data, options?)put(path, data, *, condition=None)put, put_optsWrite an object.
delete(path)delete(path)deleteDelete an object.
list(prefix?)list(prefix=None)list, list_with_delimiterList objects under a prefix.
head(path)headRead metadata and attributes without the body.
copy(from, to)copy, copy_if_not_exists, renameCopy an object inside the bucket.
signedUrl(options)signed_url(method, path, expires_in)presigned_get, presigned_put, presigned_deleteCreate a time-limited request a client can send without credentials.

Paths are /-separated keys such as reports/2026-10.json. A path that isn't valid (empty segments, . or .. segments, control characters) fails with INVALID_INPUT before any request.

get

Reads the object at path.

const { data, meta, attributes } = await files.get("reports/2026-10.json")

const report = JSON.parse(data.toString("utf8")) // data is a Buffer
console.log(meta.size, meta.eTag, attributes.contentType)
ParameterTypeDescription
pathstringObject key. At most 1,024 bytes.

Returns StorageGetResult: the bytes, the object's ObjectMeta, and its stored StorageObjectAttributes. Python returns only the bytes.

Errors: STORAGE_OBJECT_NOT_FOUND when nothing exists at path.

put

Writes data to path, replacing any object already there unless you pass a condition.

const { eTag, version } = await files.put("config.json", Buffer.from(JSON.stringify(config)))

// Store attributes with the bytes
await files.put("reports/q1.pdf", pdfBytes, {
  attributes: {
    contentType: "application/pdf",
    contentDisposition: 'attachment; filename="q1.pdf"',
    cacheControl: "public, max-age=3600",
    metadata: { quarter: "q1" },
  },
})

// Create only if absent
await files.put("locks/nightly", Buffer.from(runId), { condition: "absent" })
ParameterTypeDescription
pathstringObject key. At most 1,024 bytes.
dataBuffer | Uint8ArrayObject bytes. Encode strings and JSON yourself.
options.condition"absent"Write only when no object exists at path. The only accepted value.
options.attributesStoragePutAttributesContent type, disposition, encoding, language, cache control, and custom metadata to store with the object.

Returns StoragePutResult: the provider's ETag and version for the written object, when the backend reports them. Python returns None.

Errors:

  • STORAGE_OBJECT_ALREADY_EXISTS when condition: "absent" finds an existing object.
  • OPERATION_NOT_SUPPORTED when the backend can't store a requested attribute: the local backend rejects all attributes, and Cloud Storage rejects contentEncoding: "gzip". The write fails before any bytes are sent. See Behavior and limits.
  • INVALID_INPUT for a condition other than "absent".

delete

Deletes the object at path.

await files.delete("reports/old.json")
await files.delete("reports/old.json")
files.delete(&path).await?;

On S3, Cloud Storage, and Blob Storage, deleting a missing object succeeds. The local backend returns STORAGE_OBJECT_NOT_FOUND.

list

Lists objects whose key starts with prefix, or every object when you omit it.

for (const object of await files.list("reports/")) {
  console.log(object.location, object.size, object.lastModified)
}
ParameterTypeDescription
prefixstring (optional)Only objects under this prefix. Matching is by path segment.

Returns ObjectMeta[] in TypeScript and list[ObjectInfo] in Python. TypeScript and Python read the whole listing into memory; Rust streams it.

list returns metadata only, because cloud list APIs don't return object attributes. Use head for one object's attributes. Order isn't guaranteed.

Reads an object's metadata and attributes without downloading the body. TypeScript and Rust only.

const { meta, attributes } = await files.head("reports/q1.pdf")
console.log(meta.size, meta.eTag, attributes.contentType)
let meta = files.head(&path).await?;

Returns StorageHeadResult. Rust's head returns ObjectMeta; use get_opts with head: true to also get attributes.

Errors: STORAGE_OBJECT_NOT_FOUND when nothing exists at path.

copy

Copies an object to another key in the same bucket. TypeScript and Rust only.

await files.copy("reports/q1.json", "archive/q1.json")
files.copy(&from, &to).await?;
files.copy_if_not_exists(&from, &to).await?;
files.rename(&from, &to).await?; // copy, then delete

copy overwrites the destination. Rust's rename is a copy followed by a delete, and isn't atomic.

signedUrl

Creates a request that a client can send directly to the backend, without credentials, until it expires.

const request = await files.signedUrl({
  method: "GET",         // "GET" | "PUT" | "DELETE"
  path: "reports/q1.json",
  expiresIn: 3600,       // seconds
})
// { url, method, headers }
FieldTypeDescription
method"GET" | "PUT" | "DELETE"The operation the request authorizes. Anything else fails with INVALID_INPUT.
pathstringObject key.
expiresInnumberValidity in seconds.

Returns PresignedRequest. Send the request with the returned method and every returned header. On the local backend the URL uses a local:// scheme and is only meaningful to Alien's local tooling.

Rust-only operations

The Rust Storage handle implements the object_store ObjectStore trait, so it also has:

  • range reads and conditional writes
  • multipart uploads
  • streaming and delimiter listing
  • rename, copy_if_not_exists, and rename_if_not_exists

get_base_dir() and get_url() return the binding's base path and URL.

Types

ObjectMeta

interface ObjectMeta {
  location: string      // Object key
  size: number          // Size in bytes
  lastModified: string  // RFC 3339 timestamp
  eTag?: string         // Provider entity tag, when available
  version?: string      // Provider object version, when available
}

Python's ObjectInfo has the same fields in snake case: location, size, last_modified, e_tag, version.

StorageObjectAttributes

Returned by get and head.

interface StorageObjectAttributes {
  contentType?: string
  contentDisposition?: string
  contentEncoding?: string
  contentLanguage?: string
  cacheControl?: string
  storageClass?: string               // Provider storage class, when reported
  metadata: Record<string, string>    // User-defined metadata
}

StoragePutAttributes

Accepted by put under options.attributes. The writable subset of StorageObjectAttributes; storageClass is read-only.

interface StoragePutAttributes {
  contentType?: string
  contentDisposition?: string
  contentEncoding?: string            // Cloud Storage rejects "gzip"
  contentLanguage?: string
  cacheControl?: string
  metadata?: Record<string, string>
}

StoragePutOptions

interface StoragePutOptions {
  condition?: "absent"
  attributes?: StoragePutAttributes
}

StorageGetResult

interface StorageGetResult {
  data: Buffer
  meta: ObjectMeta
  attributes: StorageObjectAttributes
}

StorageHeadResult

interface StorageHeadResult {
  meta: ObjectMeta
  attributes: StorageObjectAttributes
}

StoragePutResult

interface StoragePutResult {
  eTag?: string
  version?: string
}

PresignedRequest

interface PresignedRequest {
  url: string
  method: string
  headers: Record<string, string>
}

Python's SignedRequest has the same fields.

Errors

CodeRetryableWhen
STORAGE_OBJECT_NOT_FOUNDNoget or head on a missing object, or delete on the local backend.
STORAGE_OBJECT_ALREADY_EXISTSNoput with condition: "absent" found an object.
STORAGE_ACCESS_DENIEDNoThe workload's identity lacks permission. Check the permission profile.
STORAGE_OPERATION_FAILEDYesAny other backend failure.
OPERATION_NOT_SUPPORTEDNoThe backend can't store a requested attribute.
INVALID_INPUTNoInvalid path, condition, or signed URL method.
BINDING_NOT_CONFIGUREDNoThe workload isn't linked to this resource.

Errors are AlienError instances with code, retryable, and context. Error messages and context never include the object key or provider URLs.

On this page