Skip to main content

Storage

The Storage Gateway provides per-user file storage with folders, metadata, tags, pre-signed URLs, and quota management.

Concepts​

ConceptDescription
FolderA directory container for files. Supports nesting. Auto-creates intermediate folders.
FileA stored object with content, metadata, tags, and a checksum
Pre-signed URLA time-limited URL for direct upload/download to the storage backend
QuotaPer-user storage limit tracked by the platform

All storage is scoped to the authenticated user. Each user has their own folder tree and quota.

Folders​

Create a Folder​

curl -X POST https://api.yocaso.dev/api/v1/storage/gateway/create-folder \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_path": "/documents/work"
  }'

Intermediate folders are created automatically — creating /documents/work also creates /documents if it doesn't exist.

Delete a Folder​

curl -X POST https://api.yocaso.dev/api/v1/storage/gateway/delete-folder \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_path": "/documents/work",
    "recursive": true
  }'

Set recursive to true to delete all files and subfolders inside. Without it, the folder must be empty.

Uploading Files​

Inline Upload (Small Files)​

For small files, include the content directly as base64:

curl -X POST https://api.yocaso.dev/api/v1/storage/gateway/upload-file \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_path": "/documents",
    "file_name": "notes.txt",
    "content": "SGVsbG8gV29ybGQ=",
    "content_type": "text/plain",
    "tags": ["notes", "work"],
    "metadata": {
      "source": "api-upload"
    }
  }'

Inline upload is deprecated — it ships the full bytes synchronously through the gateway, so it's slow for large files. Prefer the pre-signed flow below for all new integrations.

Pre-Signed Upload (Large Files)​

For anything larger than a couple of megabytes, use the 3-step pre-signed flow: get a URL, upload the bytes directly to the storage backend, then register the file.

Step 1: Get the upload URL (size_bytes is required — it is checked against your quota and enforced by the storage backend)

curl -X POST https://api.yocaso.dev/api/v1/storage/gateway/generate-upload-url \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_path": "/media",
    "file_name": "video.mp4",
    "content_type": "video/mp4",
    "size_bytes": 52428800,
    "expires_seconds": 3600
  }'

Response:

{
  "url": "https://storage.googleapis.com/bucket/...",
  "file_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "full_path": "/media/video.mp4",
  "required_headers": {
    "content-type": "video/mp4",
    "x-goog-content-length-range": "0,52428800"
  }
}

Step 2: Upload directly to the URL. Send every header from required_headers verbatim — they are part of the signature:

curl -X PUT "https://storage.googleapis.com/bucket/..." \
  -H "Content-Type: video/mp4" \
  -H "x-goog-content-length-range: 0,52428800" \
  --data-binary @video.mp4

Step 3: Register the file. This makes it visible to list-files, get-file-metadata, and generate-download-url:

curl -X POST https://api.yocaso.dev/api/v1/storage/gateway/register-uploaded-file \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "folder_path": "/media",
    "file_name": "video.mp4"
  }'

Registration is idempotent — retrying returns the already-registered file with "registered": false. Registering before the upload finished returns 404.

Downloading Files​

Generate a pre-signed download URL:

curl -X POST https://api.yocaso.dev/api/v1/storage/gateway/generate-download-url \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "/documents/notes.txt",
    "expires_seconds": 3600
  }'

Response:

{
  "url": "https://storage.googleapis.com/bucket/...",
  "file": {
    "name": "notes.txt",
    "path": "/documents/notes.txt",
    "size_bytes": 11,
    "content_type": "text/plain"
  }
}

Use response_content_disposition to force a download with a specific filename:

{
  "file_path": "/documents/notes.txt",
  "response_content_disposition": "attachment; filename=my-notes.txt"
}

Listing and Searching Files​

List Files in a Folder​

curl -X POST https://api.yocaso.dev/api/v1/storage/gateway/list-files \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_path": "/documents",
    "recursive": true,
    "page_size": 20
  }'

Use filter to narrow results:

{
  "folder_path": "/",
  "recursive": true,
  "filter": {
    "extensions": [".pdf", ".docx"],
    "tags": ["work"],
    "min_size_bytes": 1024,
    "uploaded_after": "2025-01-01T00:00:00Z",
    "name_contains": "report"
  }
}

Search Files​

Search across all files by name, tags, and metadata:

curl -X POST https://api.yocaso.dev/api/v1/storage/gateway/search-files \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly report",
    "max_results": 10
  }'

File Metadata​

Get Metadata​

curl -X POST https://api.yocaso.dev/api/v1/storage/gateway/get-file-metadata \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "/documents/notes.txt"
  }'

Update Metadata​

Update custom metadata, tags, and description. Metadata keys are merged (existing keys not in the request are preserved):

curl -X POST https://api.yocaso.dev/api/v1/storage/gateway/update-file-metadata \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "/documents/notes.txt",
    "metadata": {
      "reviewed": "true",
      "category": "internal"
    },
    "tags": ["notes", "reviewed"],
    "description": "Meeting notes from Q1 planning"
  }'
note

Setting tags replaces all existing tags. To add a tag, include all existing tags plus the new one.

File Operations​

Move / Rename a File​

curl -X POST https://api.yocaso.dev/api/v1/storage/gateway/move-file \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "source_path": "/documents/notes.txt",
    "destination_folder": "/archive",
    "new_name": "notes-2025-q1.txt"
  }'

Delete a File​

curl -X POST https://api.yocaso.dev/api/v1/storage/gateway/delete-file \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "/documents/notes.txt"
  }'

Quota​

Check storage usage and limits:

curl -X POST https://api.yocaso.dev/api/v1/storage/gateway/get-storage-quota \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "used_bytes": 1048576,
  "quota_bytes": 1073741824,
  "file_count": 15,
  "folder_count": 4,
  "usage_percentage": 0.098
}