Space Storage

Space storage extends the spaces feature by providing dedicated file storage capabilities for each workspace. This allows teams to store, organize, and manage files directly within their spaces, creating a complete collaborative environment that includes both conversational data and file assets.

Understanding Space Storage

Each space has its own isolated storage area, ensuring that files remain organized and secure within their respective workspace contexts. Files are addressed using path-based URLs, providing a familiar hierarchical structure similar to traditional file systems.

The storage system supports various file types and sizes, with limits determined by your account configuration. Files can be uploaded through multiple methods including direct binary uploads, multipart form data, HTTP URLs, and data URLs, providing flexibility for different integration scenarios.

Uploading Files

Uploading files to space storage is flexible and supports multiple input methods to accommodate different use cases and integration patterns. The system automatically handles file validation, size checks, and secure storage placement.

Direct Binary Upload

For direct binary uploads, send the file content as the request body with the appropriate content type and the file path in the URL:

Multipart Form Upload

For traditional form-based uploads, use multipart/form-data encoding:

Upload via HTTP URL

To upload a file from an existing HTTP URL, provide the URL in a JSON request body:

Upload via Data URL

For small files or inline data, use data URLs:

Two-Stage Upload for Large Files

For large files or when you need more control over the upload process, use the two-stage upload approach:

This returns an uploadRequest object with the URL and headers needed to complete the upload:

Then complete the upload by sending the file to the provided URL.

File Size Limits

Upload size limits are determined by your account configuration and are enforced during the upload process. If a file exceeds your limit, the upload will be rejected with a limits reached error. Check your account settings to view your current file size limits.

Important Considerations

• Path Conflicts: Uploading to an existing file path will overwrite the previous file. Ensure unique paths to preserve existing files.

• Directory Validation: You cannot upload to a path that already exists as a directory. The system validates this to maintain storage integrity.

• Content Type Detection: For direct binary uploads, provide accurate Content-Type headers to ensure proper file handling and future retrieval.

Listing Files in Space Storage

To browse and organize files in your space's storage, you can list all files and directories within a specific path. This operation supports both flat (immediate children only) and recursive (all descendants) listing modes, making it easy to navigate complex directory structures.

The listing operation returns detailed information about each file and directory, including file sizes, timestamps, and directory indicators. This makes it possible to build file browsers, backup systems, or content management interfaces.

Basic Listing

To list files in the root directory, send a GET request:

To list files in a subdirectory, include the path in the URL:

Recursive Listing

To list all files recursively within a directory and its subdirectories, add the recursive query parameter:

Or for a specific subdirectory:

The response includes an array of items, where each item contains the path (human-readable path), size in bytes, updatedAt timestamp, and an isDirectory flag.

Note: Directory entries will have a size of 0 bytes. Use the isDirectory property to distinguish between files and directories when building navigation interfaces.

Downloading Files from Space Storage

Once files are uploaded to space storage, you can retrieve them either as direct file downloads or as presigned URLs for deferred downloading. This flexibility allows you to choose between immediate file access and generating shareable download links.

The download operation supports content negotiation, meaning you can control the response format by setting the appropriate Accept header. This is useful when integrating with different types of clients or when building file management interfaces.

Direct File Download

To download a file directly, specify the path in the URL:

Presigned URL Download

To get a presigned download URL instead of the file content, set the Accept header to application/json: