Storage API

Heimdall provides file storage for uploads, downloads, and management via two backends: S3-compatible object storage (default) or a local filesystem backend. It supports any S3-compatible provider including AWS S3, MinIO, Cloudflare R2, and DigitalOcean Spaces.

Overview

The Storage API allows users to upload, download, and manage files with configurable validation rules per category. It supports presigned URLs for direct browser uploads/downloads and includes full audit logging.

Key Features

Dual backend - S3-compatible object storage or a local filesystem backend (see Backends below)
Presigned URLs - Generate upload/download URLs for direct browser access (S3 backend only for uploads)
Category-based limits - Configurable file size and MIME type restrictions per category
Permission-based access - RBAC permissions for fine-grained control
Audit logging - All file operations are logged with user and request context

Backends

Storage is dispatched over a backend config value: "s3" (default) or "local". Both backends implement the same REST/GraphQL surface for upload, download, delete, metadata, listing, copy, and rename.

Operation	S3 backend	Local backend
Upload (`POST /v1/storage/upload`)	Supported	Supported (writes under `local_path`)
Download (`GET /v1/storage/download/{key}`)	Supported	Supported
Presigned download URL	Supported (signed S3 URL)	Supported — returns the direct `GET /v1/storage/download/{key}` URL (no signature; access control is via the download endpoint's own auth)
Presigned upload URL (`POST /v1/storage/upload/presigned`)	Supported	Not supported — returns an error wrapping `Operation not supported by this storage backend: presigned upload URLs (use the direct upload endpoint with local backend)`. Use the direct upload endpoint instead.
Multipart upload (initiate/part/complete/abort)	Supported (internal `StorageClient` API; not currently exposed via REST/GraphQL for either backend)	Not supported — `StorageError::Unsupported`
Delete / exists / metadata / list / copy / rename	Supported	Supported

Files on the local backend are always served through the existing GET /v1/storage/download/{key} handler — there is no separate static file server.

Required Permissions

Storage operations require specific RBAC permissions:

Permission	Description
`storage:read`	View storage files, metadata, and list files
`storage:write`	Upload files and get presigned upload URLs
`storage:edit`	Reserved — defined but not currently enforced (no metadata-edit endpoint yet)
`storage:download`	Download files and get presigned download URLs
`storage:delete`	Delete files from storage

Upload Categories

Files are organized into categories with configurable limits:

Category	Default Max Size	Default Allowed Types
`images`	5 MB	image/jpeg, image/png, image/webp, image/gif, image/svg+xml
`documents`	25 MB	application/pdf, text/plain, text/markdown, application/json, application/xml
`videos`	500 MB	video/mp4, video/webm, video/quicktime, video/x-msvideo, video/x-matroska
`general`	100 MB	/ (all types)

These limits are configurable in the API configuration.

REST API Endpoints

Get Storage Limits

Get the upload limits for all categories.

GET /v1/storage/limits
Authorization: Bearer YOUR_TOKEN

Response:

{
  "enabled": true,
  "bucket": "heimdall",
  "limits": {
    "images": {
      "maxSizeMb": 5,
      "maxSizeBytes": 5242880,
      "allowedTypes": ["image/jpeg", "image/png", "image/webp", "image/gif", "image/svg+xml"]
    },
    "documents": {
      "maxSizeMb": 25,
      "maxSizeBytes": 26214400,
      "allowedTypes": ["application/pdf", "text/plain", "text/markdown", "application/json", "application/xml"]
    },
    "videos": {
      "maxSizeMb": 500,
      "maxSizeBytes": 524288000,
      "allowedTypes": ["video/mp4", "video/webm", "video/quicktime", "video/x-msvideo", "video/x-matroska"]
    },
    "general": {
      "maxSizeMb": 100,
      "maxSizeBytes": 104857600,
      "allowedTypes": ["*/*"]
    }
  },
  "presignedExpirySeconds": 3600,
  "_links": {
    "self": "https://api.example.com/v1/storage/limits"
  }
}

Upload File

Upload a file directly to storage.

POST /v1/storage/upload
Authorization: Bearer YOUR_TOKEN
Content-Type: multipart/form-data

Form Fields:

Field	Type	Required	Description
`file`	file	Yes	The file to upload
`category`	string	Yes	Category: "images", "documents", "videos", or "general"
`key`	string	No	Custom storage key (auto-generated if not provided)

Response:

{
  "key": "images/user123/profile.jpg",
  "url": "https://storage.example.com/images/user123/profile.jpg",
  "contentType": "image/jpeg",
  "sizeBytes": 245632,
  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
  "bucket": "heimdall",
  "_links": {
    "self": "https://api.example.com/v1/storage/upload",
    "download": "https://api.example.com/v1/storage/download/images/user123/profile.jpg"
  }
}

Get Presigned Upload URL

Get a presigned URL for direct browser upload.

POST /v1/storage/upload/presigned
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Request Body:

{
  "filename": "profile.jpg",
  "contentType": "image/jpeg",
  "category": "images"
}

Optional fields: customKey (custom storage key) and expirySeconds (URL expiry, default 3600).

Response:

{
  "url": "https://storage.example.com/images/user123/abc123.jpg?X-Amz-Signature=...",
  "key": "images/user123/abc123.jpg",
  "method": "PUT",
  "expiresAt": "2026-01-24T12:00:00Z",
  "_links": {
    "self": "https://api.example.com/v1/storage/upload/presigned"
  }
}

Download File

Download a file from storage.

GET /v1/storage/download/{key}
Authorization: Bearer YOUR_TOKEN

Path Parameters:

Parameter	Type	Description
`key`	string	The storage key (URL-encoded if contains special characters)

Response: The file content with appropriate Content-Type header.

Get Presigned Download URL

Get a presigned URL for direct browser download.

GET /v1/storage/download/{key}/presigned
Authorization: Bearer YOUR_TOKEN

Query Parameters:

Parameter	Type	Default	Description
`expirySeconds`	integer	3600	URL expiration time in seconds. Falls back to the configured `presigned_expiry_seconds` when omitted.

Response:

{
  "url": "https://storage.example.com/images/user123/profile.jpg?X-Amz-Signature=...",
  "key": "images/user123/profile.jpg",
  "method": "GET",
  "expiresAt": "2026-01-24T13:00:00Z",
  "_links": {
    "self": "https://api.example.com/v1/storage/download/images/user123/profile.jpg/presigned"
  }
}

Get File Metadata

Get metadata for a stored file.

GET /v1/storage/{key}/metadata
Authorization: Bearer YOUR_TOKEN

Response:

{
  "key": "images/user123/profile.jpg",
  "sizeBytes": 245632,
  "contentType": "image/jpeg",
  "lastModified": "2026-01-24T10:30:00Z",
  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
  "bucket": "heimdall",
  "_links": {
    "self": "https://api.example.com/v1/storage/images/user123/profile.jpg/metadata",
    "download": "https://api.example.com/v1/storage/download/images/user123/profile.jpg"
  }
}

List Files

List files with optional prefix filtering.

GET /v1/storage/list
Authorization: Bearer YOUR_TOKEN

Query Parameters:

Parameter	Type	Default	Description
`prefix`	string	-	Filter by key prefix (e.g., "images/user123/")
`delimiter`	string	-	Delimiter for hierarchical listing (usually "/")
`maxKeys`	integer	1000	Maximum number of results (S3 default when omitted)
`continuationToken`	string	-	Token for pagination

Response:

{
  "files": [
    {
      "key": "images/user123/profile.jpg",
      "sizeBytes": 245632,
      "lastModified": "2026-01-24T10:30:00Z",
      "etag": "\"d41d8cd98f00b204e9800998ecf8427e\""
    }
  ],
  "prefixes": [],
  "isTruncated": false,
  "continuationToken": null,
  "bucket": "heimdall",
  "prefix": "images/user123/",
  "_links": {
    "self": "https://api.example.com/v1/storage/list"
  }
}

Delete File

Delete a file from storage. This endpoint:

Verifies the file exists before deletion
Deletes the file from S3 storage
Removes the file metadata from the database
Logs an audit event (file_deleted)

Requires storage:delete permission.

DELETE /v1/storage/{key}
Authorization: Bearer YOUR_TOKEN

Path Parameters:

Parameter	Type	Description
`key`	string	The storage key (URL-encoded if contains special characters)

Response (200 OK):

{
  "message": "File deleted successfully"
}

Error Responses:

Status	Description
401	Unauthorized - invalid or missing token
403	Forbidden - missing `storage:delete` permission
404	File not found
500	Storage operation failed

GraphQL API

Queries

storageLimits

Get upload limits for all categories.

query {
  storageLimits {
    images {
      maxSizeMb
      allowedTypes
    }
    documents {
      maxSizeMb
      allowedTypes
    }
    videos {
      maxSizeMb
      allowedTypes
    }
    general {
      maxSizeMb
      allowedTypes
    }
  }
}

presignedDownloadUrl

Get a presigned download URL.

query {
  presignedDownloadUrl(key: "images/user123/profile.jpg", expirySeconds: 3600) {
    url
    key
    expiresAt
  }
}

fileMetadata

Get file metadata.

query {
  fileMetadata(key: "images/user123/profile.jpg") {
    key
    sizeBytes
    contentType
    lastModified
    etag
  }
}

listFiles

List files with pagination.

query {
  listFiles(input: { prefix: "images/user123/", maxKeys: 100 }) {
    files {
      key
      sizeBytes
      lastModified
      etag
    }
    prefixes
    isTruncated
    continuationToken
    bucket
    prefix
  }
}

Mutations

getPresignedUploadUrl

Get a presigned URL for uploading.

mutation {
  getPresignedUploadUrl(input: {
    filename: "profile.jpg"
    contentType: "image/jpeg"
    category: "images"
  }) {
    url
    key
    expiresAt
  }
}

deleteFile

Delete a file from storage. This mutation:

Verifies the file exists before deletion
Deletes the file from S3 storage
Removes the file metadata from the database
Logs an audit event (file_deleted)

Requires storage:delete permission.

mutation {
  deleteFile(key: "images/user123/profile.jpg")
}

Response: Returns true on success.

Errors:

"Authentication required" - No valid auth token
"File not found" - The specified key doesn't exist
"Failed to delete file: ..." - S3 deletion failed

Audit Events

All storage operations are logged:

Event	Description
`file_created`	File uploaded to storage
`file_downloaded`	Reserved — constant defined but not currently emitted
`file_edited`	Reserved — constant defined but not currently emitted
`file_deleted`	File deleted from storage

Configuration

Storage is configured in the API configuration file:

[storage]
enabled = true
backend = "s3"                       # "s3" (default) or "local"
local_path = "./uploads"             # only used when backend = "local"
endpoint = "http://localhost:9000"  # S3-compatible endpoint
region = "us-east-1"
access_key = "your-access-key"
secret_key = "your-secret-key"
bucket = "heimdall"
path_style = true  # Required for MinIO
public_url = ""    # Optional CDN URL

[storage.upload_limits.images]
max_size_mb = 5
allowed_types = ["image/jpeg", "image/png", "image/webp", "image/gif"]

[storage.upload_limits.documents]
max_size_mb = 25
allowed_types = ["application/pdf", "text/plain", "application/json"]

[storage.upload_limits.videos]
max_size_mb = 500
allowed_types = ["video/mp4", "video/webm", "video/quicktime", "video/x-msvideo"]

[storage.upload_limits.general]
max_size_mb = 100
allowed_types = ["*/*"]

Key	Type	Default	Description	Env override
`backend`	string	`"s3"`	Storage backend: `"s3"` (S3/MinIO/R2/Spaces) or `"local"` (filesystem)	`HEIMDALL__STORAGE__BACKEND`
`local_path`	string?	none	Local filesystem base path; only used when `backend = "local"`	`HEIMDALL__STORAGE__LOCAL_PATH`

note

The shipped platform/api/config/default.toml sets backend = "local" and local_path = "./uploads" for local/dev deployment. The Rust struct default (used if the key is omitted entirely) is backend = "s3" with local_path = None.

Local Filesystem Backend

For simple deployments without an S3-compatible provider, point backend at "local":

[storage]
enabled = true
backend = "local"
local_path = "./uploads"

Uploaded files are written under local_path and served back via the standard GET /v1/storage/download/{key} endpoint — no additional static file server or reverse-proxy config is required. See Backends above for the operations the local backend does not support (multipart, presigned upload URLs).

Provider-Specific Configuration

MinIO (Local Development)

[storage]
endpoint = "http://localhost:9000"
region = "us-east-1"
path_style = true

Cloudflare R2

[storage]
endpoint = "https://<account_id>.r2.cloudflarestorage.com"
region = "auto"
path_style = false
public_url = "https://pub-xxx.r2.dev"

DigitalOcean Spaces

[storage]
endpoint = "https://<region>.digitaloceanspaces.com"
region = "<region>"
path_style = false
public_url = "https://<space>.<region>.cdn.digitaloceanspaces.com"

AWS S3

[storage]
endpoint = "https://s3.<region>.amazonaws.com"
region = "<region>"
path_style = false

Storage File Metadata

Track who uploaded what files and when with file metadata queries.

REST API

List Storage Files (Admin)

List all storage files with optional filtering. Requires storage:read permission.

GET /v1/storage/files
Authorization: Bearer YOUR_TOKEN

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-indexed)
`limit`	integer	20	Items per page (max 100)
`user_id`	string	-	Filter by user ID
`category`	string	-	Filter by category (images, documents, videos, general)
`content_type`	string	-	Filter by MIME type
`key_prefix`	string	-	Filter by key prefix
`filename_search`	string	-	Search by filename (partial match)
`start_date`	string	-	Filter by start date (ISO 8601)
`end_date`	string	-	Filter by end date (ISO 8601)
`sort_field`	string	created_at	Sort by: created_at, size_bytes, original_filename
`sort_direction`	string	desc	Sort direction: asc or desc

Response:

{
  "files": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "user123",
      "key": "images/user123/profile.jpg",
      "originalFilename": "profile.jpg",
      "contentType": "image/jpeg",
      "category": "images",
      "sizeBytes": 245632,
      "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
      "bucket": "heimdall",
      "createdAt": "2026-01-24T10:30:00Z"
    }
  ],
  "totalCount": 150,
  "page": 1,
  "limit": 20,
  "totalPages": 8
}

Get File Info by Key

Get metadata for a specific file by its storage key.

GET /v1/storage/files/{key}/info
Authorization: Bearer YOUR_TOKEN

List My Files

List storage files uploaded by the current authenticated user.

GET /v1/storage/files/me
Authorization: Bearer YOUR_TOKEN

GraphQL API

Query: storageFiles

List all storage files with filters (admin, requires storage:read).

query {
  storageFiles(input: {
    category: "images"
    filenameSearch: "profile"
    limit: 20
    sortField: "created_at"
    sortDirection: "desc"
  }) {
    files {
      id
      key
      originalFilename
      contentType
      sizeBytes
      userId
      createdAt
    }
    totalCount
    totalPages
  }
}

Query: storageFileByKey

Get file metadata by storage key.

query {
  storageFileByKey(key: "images/user123/profile.jpg") {
    id
    userId
    originalFilename
    sizeBytes
    createdAt
  }
}

Query: myStorageFiles

List current user's files.

query {
  myStorageFiles(
    category: "images"
    limit: 20
  ) {
    files {
      key
      originalFilename
      sizeBytes
      createdAt
    }
    totalCount
  }
}

Error Responses

Status	Code	Description
400	`NO_FILE` / `INVALID_CATEGORY`	No file provided, or unknown upload category
401	`UNAUTHORIZED`	Authentication required
403	`FORBIDDEN`	Insufficient permissions
404	`NOT_FOUND`	File not found
413	`FILE_TOO_LARGE`	File exceeds the category size limit
415	`INVALID_MIME_TYPE`	MIME type not allowed for the category
500	`INTERNAL_ERROR`	Storage operation failed
503	`STORAGE_DISABLED`	Storage service is not enabled

Overview​

Key Features​

Backends​

Required Permissions​

Upload Categories​

REST API Endpoints​

Get Storage Limits​

Upload File​

Get Presigned Upload URL​

Download File​

Get Presigned Download URL​

Get File Metadata​

List Files​

Delete File​

GraphQL API​

Queries​

storageLimits​

presignedDownloadUrl​

fileMetadata​

listFiles​

Mutations​

getPresignedUploadUrl​

deleteFile​

Audit Events​

Configuration​

Local Filesystem Backend​

Provider-Specific Configuration​

MinIO (Local Development)​

Cloudflare R2​

DigitalOcean Spaces​

AWS S3​

Storage File Metadata​

REST API​

List Storage Files (Admin)​

Get File Info by Key​

List My Files​

GraphQL API​

Query: storageFiles​

Query: storageFileByKey​

Query: myStorageFiles​

Error Responses​

Overview

Key Features

Backends

Required Permissions

Upload Categories

REST API Endpoints

Get Storage Limits

Upload File

Get Presigned Upload URL

Download File

Get Presigned Download URL

Get File Metadata

List Files

Delete File

GraphQL API

Queries

storageLimits

presignedDownloadUrl

fileMetadata

listFiles

Mutations

getPresignedUploadUrl

deleteFile

Audit Events

Configuration

Local Filesystem Backend

Provider-Specific Configuration

MinIO (Local Development)

Cloudflare R2

DigitalOcean Spaces

AWS S3

Storage File Metadata

REST API

List Storage Files (Admin)

Get File Info by Key

List My Files

GraphQL API

Query: storageFiles

Query: storageFileByKey

Query: myStorageFiles

Error Responses