Storage

The storage service is a stateless proxy that manages binary data across multiple providers (AWS, IPFS, Filecoin) supporting both location-addressed and content-addressed storage. It supports both small direct uploads via MCP and large-file streaming via session initialization.

Prerequiste

You must provision required storage container in My Vault  before making any requests.

Types

StorageContext

Storage context sets the context for the request

export interface StorageContext {
  tenant_id?: string;           // the userID
  provider: string;             // the storage provider such as 'aws-s3', 'filecoin'
}

It must be sent as _meta - As mentioned in request payload for every method below

As it stands today, we support AWS-S3 and Filecoin. Make sure you pass aws-s3 for AWS-S3 and filecoin for Filecoin as the values in provider under StorageContext

FileID

Syntax: zttp://storage:<provider>/<containerID>/<file_identifier>

file_identifier

• would be absolutePath in case of location-addressed providers like AWS, Cloudflare R2
• would be CID incase of content-addressed providers like IPFS, filecoin

write_blob

Description: Write small blobs (typically < 2MB) directly

Input Schema: (Method Params)

• data (string): Base64 encoded file content.
• file_key (string): Absolute path of the file. This method is highly customized for smaller payloads from client such as AI Agents and IOT devices.

Recommended size of base64 string = 2MB

read_blob

Description: Fetches small file in given encoding

Input Schema:

• file_key (string): The unique key of the file received at the time of write_blob .
• encoding (string): Choose utf-8 for text or base64 for images/binary

init_upload

Description: Initiates a handshake for large file uploads. Returns a session ID and a dedicated presigned URL for the HTTP upload.

Input Schema:

• file_key (string): Absolute path of the file.

• Response: Returns an object containing a expiresAt and a uri for binary streaming.

init_download

Description: Initiates a handshake for large file downloads. Returns a session ID and a dedicated presigned URL for the HTTP download.

Input Schema:

• file_key (string): The standard URI received after init_upload.

• Response: Returns an DownloadSession containing a sessionID and a downloadUrl for binary streaming.