Storage API

The Storage API provides bucket-based file storage with support for both local and S3 backends, including presigned URLs for direct uploads/downloads.

Base URL

All storage endpoints are prefixed with /api/storage

Bucket Management

List All Buckets

curl https://your-app.region.insforge.app/api/storage/buckets \
  -H "x-api-key: YOUR_API_KEY"

Retrieve list of all bucket names (admin only). Response

{
  "buckets": ["avatars", "documents", "uploads", "public", "private"]
}

Create Bucket

curl -X POST https://your-app.region.insforge.app/api/storage/buckets \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketName": "avatars",
    "isPublic": true
  }'

Create a new storage bucket (admin only). Body Parameters

bucketName

string

required

Bucket name (alphanumeric, underscore, and hyphen only)

isPublic

boolean

default:"true"

Whether bucket is publicly accessible

Response

{
  "message": "Bucket created successfully",
  "bucket": "avatars"
}

Update Bucket Visibility

curl -X PATCH https://your-app.region.insforge.app/api/storage/buckets/avatars \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "isPublic": false
  }'

Update bucket visibility settings (admin only). Path Parameters

bucketName

string

required

Name of the bucket

Body Parameters

isPublic

boolean

required

Whether bucket should be publicly accessible

Response

{
  "message": "Bucket visibility updated",
  "bucket": "avatars",
  "isPublic": false
}

Delete Bucket

curl -X DELETE https://your-app.region.insforge.app/api/storage/buckets/avatars \
  -H "x-api-key: YOUR_API_KEY"

Delete bucket and all its objects (admin only). Path Parameters

bucketName

string

required

Name of the bucket to delete

Response

{
  "message": "Bucket deleted successfully",
  "nextActions": "You can use POST /api/storage/buckets to create a new bucket"
}

File Operations

List Objects in Bucket

curl "https://your-app.region.insforge.app/api/storage/buckets/avatars/objects?prefix=users/&limit=100&search=profile" \
  -H "x-api-key: YOUR_API_KEY"

List all objects in a bucket with filtering (admin only). Path Parameters

bucketName

string

required

Name of the bucket

Query Parameters

prefix

string

Filter by key prefix (e.g., “users/”)

limit

integer

default:"100"

Maximum objects to return (1-1000)

offset

integer

default:"0"

Number of objects to skip

string

Search objects by key (partial match)

Response

{
  "data": [
    {
      "bucket": "avatars",
      "key": "users/user123.jpg",
      "size": 102400,
      "mimeType": "image/jpeg",
      "uploadedAt": "2024-01-15T10:30:00Z",
      "url": "/api/storage/buckets/avatars/objects/users/user123.jpg"
    },
    {
      "bucket": "avatars",
      "key": "users/user456.png",
      "size": 204800,
      "mimeType": "image/png",
      "uploadedAt": "2024-01-16T11:00:00Z",
      "url": "/api/storage/buckets/avatars/objects/users/user456.png"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 100,
    "total": 2
  }
}

Get Upload Strategy

curl -X POST https://your-app.region.insforge.app/api/storage/buckets/avatars/upload-strategy \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "profile-photo.jpg",
    "contentType": "image/jpeg",
    "size": 102400
  }'

Get upload strategy and presigned URLs (S3) or direct endpoint (local). Path Parameters

bucketName

string

required

Name of the bucket

Body Parameters

filename

string

required

Original filename

contentType

string

MIME type of the file

size

integer

File size in bytes

Response

S3 Backend
Local Storage

{
  "method": "presigned",
  "uploadUrl": "https://s3-bucket.amazonaws.com/",
  "fields": {
    "bucket": "my-s3-bucket",
    "key": "app-key/avatars/profile-photo-1234567890-abc123.jpg",
    "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
    "X-Amz-Credential": "AKIA.../20250905/us-east-2/s3/aws4_request",
    "X-Amz-Date": "20250905T000000Z",
    "Policy": "eyJ...",
    "X-Amz-Signature": "abc123..."
  },
  "key": "profile-photo-1234567890-abc123.jpg",
  "confirmRequired": true,
  "confirmUrl": "/api/storage/buckets/avatars/objects/profile-photo-1234567890-abc123.jpg/confirm-upload",
  "expiresAt": "2025-09-05T01:00:00Z"
}

{
  "method": "direct",
  "uploadUrl": "/api/storage/buckets/avatars/objects/profile-photo-1234567890-abc123.jpg",
  "key": "profile-photo-1234567890-abc123.jpg",
  "confirmRequired": false
}

Upload Object with Specific Key

curl -X PUT https://your-app.region.insforge.app/api/storage/buckets/avatars/objects/user123.jpg \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg"

Upload a file with a specified key (path). Path Parameters

bucketName

string

required

Name of the bucket

objectKey

string

required

Object key (can include slashes for pseudo-folders)

Body Multipart form data with file field. Response

{
  "bucket": "avatars",
  "key": "user123.jpg",
  "size": 102400,
  "mimeType": "image/jpeg",
  "uploadedAt": "2024-01-21T10:30:00Z",
  "url": "/api/storage/buckets/avatars/objects/user123.jpg"
}

Upload Object with Auto-Generated Key

curl -X POST https://your-app.region.insforge.app/api/storage/buckets/avatars/objects \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg"

Upload file with automatically generated unique key. Path Parameters

bucketName

string

required

Name of the bucket

Body Multipart form data with file field. Response

{
  "bucket": "avatars",
  "key": "image-1737546841234-a3f2b1.jpg",
  "size": 102400,
  "mimeType": "image/jpeg",
  "uploadedAt": "2024-01-21T10:30:00Z",
  "url": "/api/storage/buckets/avatars/objects/image-1737546841234-a3f2b1.jpg"
}

Confirm Presigned Upload

curl -X POST https://your-app.region.insforge.app/api/storage/buckets/avatars/objects/profile-photo-123.jpg/confirm-upload \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 102400,
    "contentType": "image/jpeg",
    "etag": "9bb58f26192e4ba00f01e2e7b136bbd8"
  }'

Confirm successful S3 presigned upload. Path Parameters

bucketName

string

required

Name of the bucket

objectKey

string

required

Object key from upload strategy

Body Parameters

size

integer

required

File size in bytes

contentType

string

MIME type

etag

string

S3 ETag of uploaded object

Response

{
  "bucket": "avatars",
  "key": "profile-photo-123.jpg",
  "size": 102400,
  "mimeType": "image/jpeg",
  "uploadedAt": "2024-01-21T10:30:00Z",
  "url": "/api/storage/buckets/avatars/objects/profile-photo-123.jpg"
}

Get Download Strategy

curl -X POST https://your-app.region.insforge.app/api/storage/buckets/avatars/objects/profile-photo.jpg/download-strategy \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expiresIn": 3600
  }'

Get download URL (direct for public buckets, presigned for private S3 buckets). Path Parameters

bucketName

string

required

Name of the bucket

objectKey

string

required

Object key

Body Parameters

expiresIn

integer

default:"3600"

URL expiration time in seconds

Response

S3 Public Bucket
S3 Private Bucket
Local Storage

{
  "method": "direct",
  "url": "https://s3-bucket.s3.us-east-2.amazonaws.com/app-key/public-assets/logo.png"
}

{
  "method": "presigned",
  "url": "https://s3-bucket.s3.us-east-2.amazonaws.com/app-key/avatars/profile.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...",
  "expiresAt": "2025-09-05T01:00:00Z"
}

{
  "method": "direct",
  "url": "/api/storage/buckets/avatars/objects/profile-photo.jpg"
}

Download Object

curl https://your-app.region.insforge.app/api/storage/buckets/avatars/objects/user123.jpg \
  -H "x-api-key: YOUR_API_KEY" \
  -o downloaded-image.jpg

Download file content. Path Parameters

bucketName

string

required

Name of the bucket

objectKey

string

required

Object key to download

Response Binary file content with appropriate Content-Type and Content-Length headers.

Delete Object

curl -X DELETE https://your-app.region.insforge.app/api/storage/buckets/avatars/objects/user123.jpg \
  -H "x-api-key: YOUR_API_KEY"

Delete an object from storage. Path Parameters

bucketName

string

required

Name of the bucket

objectKey

string

required

Object key to delete

Response

{
  "message": "Object deleted successfully"
}

Core APIs

Management APIs

Base URL

Bucket Management

List All Buckets

Create Bucket

Update Bucket Visibility

Delete Bucket

File Operations

List Objects in Bucket

Get Upload Strategy

Upload Object with Specific Key

Upload Object with Auto-Generated Key

Confirm Presigned Upload

Get Download Strategy

Download Object

Delete Object

Core APIs

Management APIs

Documentation Index

​Base URL

​Bucket Management

​List All Buckets

​Create Bucket

​Update Bucket Visibility

​Delete Bucket

​File Operations

​List Objects in Bucket

​Get Upload Strategy

​Upload Object with Specific Key

​Upload Object with Auto-Generated Key

​Confirm Presigned Upload

​Get Download Strategy

​Download Object

​Delete Object

Base URL

Bucket Management

List All Buckets

Create Bucket

Update Bucket Visibility

Delete Bucket

File Operations

List Objects in Bucket

Get Upload Strategy

Upload Object with Specific Key

Upload Object with Auto-Generated Key

Confirm Presigned Upload

Get Download Strategy

Download Object

Delete Object