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 identifiers, 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:

POST /api/v1/space/{spaceId}/storage/{pathId}/upload
Content-Type: image/png

[binary file data]

http

Multipart Form Upload

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

POST /api/v1/space/space_abc123/storage/cGhvdG9zL3Byb2ZpbGUucG5n/upload
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

------WebKitFormBoundary
Content-Disposition: form-data; name="file"; filename="profile.png"
Content-Type: image/png

[binary file data]
------WebKitFormBoundary--

http

Upload via HTTP URL

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

POST /api/v1/space/space_abc123/storage/cGhvdG9zL3Byb2ZpbGUucG5n/upload
Content-Type: application/json

{
  "file": "https://example.com/images/profile.png"
}

http

Upload via Data URL

For small files or inline data, use data URLs:

POST /api/v1/space/space_abc123/storage/cGhvdG9zL3Byb2ZpbGUucG5n/upload
Content-Type: application/json

{
  "file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
}

http

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:

POST /api/v1/space/space_abc123/storage/cGhvdG9zL3Byb2ZpbGUucG5n/upload
Content-Type: application/json

{
  "file": {
    "type": "image/png",
    "size": 1024000,
    "meta": {
      "description": "User profile photo"
    }
  }
}

http

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

{
  "id": "cGhvdG9zL3Byb2ZpbGUucG5n",
  "path": "photos/profile.png",
  "uploadRequest": {
    "method": "PUT",
    "url": "https://storage.example.com/upload/...",
    "headers": {
      "Content-Type": "image/png",
      "Content-Length": "1024000"
    }
  }
}

json

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

Path Encoding

File paths must be base64-encoded to ensure safe URL transmission. The pathId parameter is the base64-encoded version of the desired file path.

For example, to upload a file to photos/profile.png:

  • Original path: photos/profile.png
  • Base64 encoded: cGhvdG9zL3Byb2ZpbGUucG5n
  • Upload URL: /api/v1/space/{spaceId}/storage/cGhvdG9zL3Byb2ZpbGUucG5n/upload

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.

Go to cbk.ai