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
| TypeScript | Python | Rust | What it does |
|---|---|---|---|
get(path) | get(path), get_optional(path) | get, get_range, get_opts | Read an object. |
put(path, data, options?) | put(path, data, *, condition=None) | put, put_opts | Write an object. |
delete(path) | delete(path) | delete | Delete an object. |
list(prefix?) | list(prefix=None) | list, list_with_delimiter | List objects under a prefix. |
head(path) | head | Read metadata and attributes without the body. | |
copy(from, to) | copy, copy_if_not_exists, rename | Copy an object inside the bucket. | |
signedUrl(options) | signed_url(method, path, expires_in) | presigned_get, presigned_put, presigned_delete | Create 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)| Parameter | Type | Description |
|---|---|---|
path | string | Object 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" })| Parameter | Type | Description |
|---|---|---|
path | string | Object key. At most 1,024 bytes. |
data | Buffer | Uint8Array | Object bytes. Encode strings and JSON yourself. |
options.condition | "absent" | Write only when no object exists at path. The only accepted value. |
options.attributes | StoragePutAttributes | Content 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_EXISTSwhencondition: "absent"finds an existing object.OPERATION_NOT_SUPPORTEDwhen the backend can't store a requested attribute: the local backend rejects all attributes, and Cloud Storage rejectscontentEncoding: "gzip". The write fails before any bytes are sent. See Behavior and limits.INVALID_INPUTfor aconditionother 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)
}| Parameter | Type | Description |
|---|---|---|
prefix | string (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.
head
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 deletecopy 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 }| Field | Type | Description |
|---|---|---|
method | "GET" | "PUT" | "DELETE" | The operation the request authorizes. Anything else fails with INVALID_INPUT. |
path | string | Object key. |
expiresIn | number | Validity 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, andrename_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
| Code | Retryable | When |
|---|---|---|
STORAGE_OBJECT_NOT_FOUND | No | get or head on a missing object, or delete on the local backend. |
STORAGE_OBJECT_ALREADY_EXISTS | No | put with condition: "absent" found an object. |
STORAGE_ACCESS_DENIED | No | The workload's identity lacks permission. Check the permission profile. |
STORAGE_OPERATION_FAILED | Yes | Any other backend failure. |
OPERATION_NOT_SUPPORTED | No | The backend can't store a requested attribute. |
INVALID_INPUT | No | Invalid path, condition, or signed URL method. |
BINDING_NOT_CONFIGURED | No | The 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.