SimplyStack Documentation

Overview

The Storage API provides secure file upload, management, and serving capabilities. Upload files with metadata, generate public URLs, and organize your assets efficiently.

✨ Key Features

• Direct file upload with metadata
• Public URL generation
• MIME type validation
• Custom labeling and categorization
• File size and type restrictions

Upload File

POST/api/v1/storage/upload

Upload a file with optional metadata and labeling.

Example Request

curl -X POST \
     -H "x-api-key: your_api_key_here" \
     -F "file=@image.jpg" \
     -F "label=profile-picture" \
     -F "metadata={"userId":"123","category":"avatar"}" \
     "https://simplystack.dev/api/v1/storage/upload"

Response

{
  "data": {
    "id": "file_abc123",
    "filename": "image.jpg",
    "size": 102400,
    "mime_type": "image/jpeg",
    "label": "profile-picture",
    "metadata": {
      "userId": "123",
      "category": "avatar"
    },
    "url": "https://simplystack.dev/storage/file_abc123",
    "created_at": "2024-01-15T10:00:00Z"
  }
}

List Files

GET/api/v1/storage

Retrieve a list of uploaded files with optional filtering.

Query Parameters

Parameter	Type	Description
`mime_type`	string	Filter by MIME type (e.g., "image", "video")
`label`	string	Filter by label
`limit`	number	Number of files to return (default: 20, max: 100)

Get File Details

GET/api/v1/storage/{id}

Get detailed information about a specific file.

Delete File

DELETE/api/v1/storage/{id}

Permanently delete a file. This action cannot be undone.

SDK Usage

import { SimplyStackSDK } from "@simplystack-org/sdk";

const sdk = new SimplyStackSDK("your-api-key");

// Upload a file
const { data: file, error } = await sdk.uploadFile(fileData, {
  label: "profile-picture",
  metadata: { userId: "123" }
});

// List files
const { data: files } = await sdk.getStorageAssets({
  mime_type: "image"
});

// Delete file
const { error: deleteError } = await sdk.deleteStorageAsset("file_123");