Storage Service API
Base URL: https://api.stashly.io
API Keys#
API keys cannot manage other API keys — JWT is required for all key management operations.
/api/api-keysJWT RequiredList all API keys for the authenticated user.
{
"success": true,
"data": [
{ "id": "key_01j9", "name": "CI Pipeline", "permissions": ["view", "add"], "lastUsed": "2025-05-28T10:00:00Z" }
]
}
/api/api-keys/:idJWT RequiredGet details for a single API key.
/api/api-keysJWT RequiredCreate a new API key with specified permissions.
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Human-readable key name |
permissions* | string[] | Array of: view, add, edit, delete |
{
"success": true,
"data": {
"id": "key_02k1",
"key": "sk_live_01j9xk2m...",
"name": "CI Pipeline",
"permissions": ["view", "add"]
}
}
Store your key now
The full API key is only returned once at creation. It cannot be retrieved again.
/api/api-keys/:idJWT RequiredUpdate an API key's name or permissions.
/api/api-keys/:idJWT RequiredPermanently delete an API key.
/api/api-keys/:id/revokeJWT RequiredRevoke an API key immediately. The key will no longer authenticate.
Buckets#
/api/bucketsJWT or API KeyList all buckets.
/api/bucketsJWT or API KeyCreate a new bucket.
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Bucket name (unique per tenant) |
/api/buckets/:idJWT or API KeyRename a bucket.
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | New bucket name |
/api/buckets/:idJWT or API KeyDelete a bucket and all its contents.
Objects#
/api/buckets/:bucketId/objectsJWT or API KeyList objects in a bucket. Supports prefix filter and pagination.
Query Parameters
| Name | Type | Description |
|---|---|---|
prefix | string | Path prefix filter |
page | number | Page number (default: 1) |
limit | number | Items per page (default: 20) |
/api/buckets/:bucketId/objects/directoryJWT or API KeyCreate an empty directory.
Request Body
| Name | Type | Description |
|---|---|---|
path* | string | Directory path |
/api/buckets/:bucketId/objects/uploadJWT or API KeyDirect file upload (multipart/form-data). For large files use the session-based Upload API.
Form Data
| Name | Type | Description |
|---|---|---|
file* | File | File binary |
path | string | Target path within bucket |
/api/buckets/:bucketId/objectsJWT or API KeyRename a file or directory.
/api/buckets/:bucketId/objects/moveJWT or API KeyMove an object to a new path.
/api/buckets/:bucketId/objects/copyJWT or API KeyCopy an object to a new key.
/api/buckets/:bucketId/objectsJWT or API KeyMove object to trash.
/api/buckets/:bucketId/objects/presignedJWT or API KeyGenerate a presigned download URL.
/api/buckets/:bucketId/objects/downloadJWT or API KeyDirect file download.
/api/buckets/:bucketId/objects/bulkJWT or API KeyBulk delete objects.
/api/buckets/:bucketId/objects/bulk-moveJWT or API KeyBulk move objects.
/api/buckets/:bucketId/objects/bulk-copyJWT or API KeyBulk copy objects.
Upload Sessions#
/api/user/upload/initJWT RequiredInitiate a new upload session. Requires an active subscription.
Request Body
| Name | Type | Description |
|---|---|---|
files* | object[] | Array of {name, size, mimeType} |
/api/user/upload/activeJWT RequiredGet the current active upload session.
/api/user/upload/:sessionIdJWT RequiredGet session status and per-file progress.
/api/user/upload/:sessionId/eventsJWT RequiredGet session event log.
/api/user/upload/:sessionId/fileJWT RequiredUpload a file to a session (multipart/form-data).
/api/user/upload/:sessionId/cancelJWT RequiredCancel a session and revert all uploaded files.
User Files#
/api/user/filesJWT RequiredList files owned by the authenticated user.
/api/user/files/:idJWT RequiredDelete a user-owned file.
/api/user/files/:id/downloadJWT RequiredDownload a user-owned file.
/api/user/files/:id/presignedJWT RequiredGet a presigned URL for a user-owned file.
User Settings#
/api/user/settingsJWT RequiredGet the user's storage usage and settings.
/api/user/settingsJWT RequiredUpdate user settings.
Trash#
/api/trashJWT RequiredList items in trash.
/api/trash/:id/restoreJWT RequiredRestore an item from trash.
/api/trash/emptyJWT RequiredPermanently delete all trash items.
/api/trash/:id/permanentJWT RequiredPermanently delete a single trash item.
File Serving#
/api/serveServe a file via HMAC presigned token. Public endpoint — accessible without authentication.
Query Parameters
| Name | Type | Description |
|---|---|---|
token* | string | HMAC-signed presigned token |