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:

Deleting Files and Directories

Space storage supports deleting both individual files and entire directories. The delete operation is permanent and cannot be undone, so use it carefully. The file or directory path is specified directly in the URL after the /delete/ segment.

Deleting a Single File

To delete a specific file, send a POST request with the file path in the URL:

If the file does not exist, the API will return a 404 error. The response includes the path of the deleted file for confirmation.

Deleting a Directory Recursively

To delete a directory and all of its contents, include the recursive flag in the request body:

When recursive is set to true, the system removes every file and subdirectory under the specified path. When recursive is false or omitted, the operation targets a single file and will fail if the path points to a directory.

Important Considerations

• Permanent deletion: Deleted files cannot be recovered. Consider implementing confirmation prompts in your application before calling this endpoint.

• Directory existence: When using recursive mode, the directory must exist. The API verifies the directory is present before attempting deletion.

• Partial paths: Ensure the path is correct and complete. Deleting a parent directory recursively removes all nested content.

Copying Files

The copy operation duplicates a file from one location to another within the same space storage. The original file remains unchanged, and a new copy is created at the destination path. This is useful for creating backups, duplicating templates, or organizing files without losing the original.

Basic Copy

To copy a file, send a POST request with the source path in the URL and the destination path in the request body:

The response confirms the operation by returning the destination path.

Important Considerations

• Source must exist: The source file must exist. The API returns a 404 error if the source path is not found.

• Overwrites allowed: If a file already exists at the destination path, it will be overwritten without warning.

• Files only: Directory copying is not currently supported. To duplicate a directory, copy each file individually.

• Same space: Both source and destination must be within the same space's storage. Cross-space copies are not supported.

Moving and Renaming Files

The move operation relocates a file from one path to another within the same space storage. This effectively renames or reorganizes the file. The original file is removed and a new file is created at the destination path.

Basic Move

To move a file, send a POST request with the source path in the URL and the destination path in the request body:

The response confirms the operation by returning the destination path.

Renaming Files

Renaming is just a move within the same directory:

Moving to a Different Directory

You can also move files between directories:

Important Considerations

• Source must exist: The source file must exist. The API returns a 404 error if the source path is not found.

• Overwrites allowed: If a file already exists at the destination path, it will be overwritten without warning.

• Files only: Directory moves are not currently supported. To move a directory, move each file individually.

• Same space: Both source and destination must be within the same space's storage. Cross-space moves are not supported.