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.

GET/api/api-keysJWT Required

List all API keys for the authenticated user.

200Key list
{
  "success": true,
  "data": [
    { "id": "key_01j9", "name": "CI Pipeline", "permissions": ["view", "add"], "lastUsed": "2025-05-28T10:00:00Z" }
  ]
}
GET/api/api-keys/:idJWT Required

Get details for a single API key.

POST/api/api-keysJWT Required

Create a new API key with specified permissions.

Request Body

NameTypeDescription
name*stringHuman-readable key name
permissions*string[]Array of: view, add, edit, delete
201Key created
{
  "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.

PATCH/api/api-keys/:idJWT Required

Update an API key's name or permissions.

DELETE/api/api-keys/:idJWT Required

Permanently delete an API key.

POST/api/api-keys/:id/revokeJWT Required

Revoke an API key immediately. The key will no longer authenticate.


Buckets#

GET/api/bucketsJWT or API Key

List all buckets.

POST/api/bucketsJWT or API Key

Create a new bucket.

Request Body

NameTypeDescription
name*stringBucket name (unique per tenant)
PATCH/api/buckets/:idJWT or API Key

Rename a bucket.

Request Body

NameTypeDescription
name*stringNew bucket name
DELETE/api/buckets/:idJWT or API Key

Delete a bucket and all its contents.


Objects#

GET/api/buckets/:bucketId/objectsJWT or API Key

List objects in a bucket. Supports prefix filter and pagination.

Query Parameters

NameTypeDescription
prefixstringPath prefix filter
pagenumberPage number (default: 1)
limitnumberItems per page (default: 20)
POST/api/buckets/:bucketId/objects/directoryJWT or API Key

Create an empty directory.

Request Body

NameTypeDescription
path*stringDirectory path
POST/api/buckets/:bucketId/objects/uploadJWT or API Key

Direct file upload (multipart/form-data). For large files use the session-based Upload API.

Form Data

NameTypeDescription
file*FileFile binary
pathstringTarget path within bucket
PATCH/api/buckets/:bucketId/objectsJWT or API Key

Rename a file or directory.

PATCH/api/buckets/:bucketId/objects/moveJWT or API Key

Move an object to a new path.

POST/api/buckets/:bucketId/objects/copyJWT or API Key

Copy an object to a new key.

DELETE/api/buckets/:bucketId/objectsJWT or API Key

Move object to trash.

GET/api/buckets/:bucketId/objects/presignedJWT or API Key

Generate a presigned download URL.

GET/api/buckets/:bucketId/objects/downloadJWT or API Key

Direct file download.

DELETE/api/buckets/:bucketId/objects/bulkJWT or API Key

Bulk delete objects.

PATCH/api/buckets/:bucketId/objects/bulk-moveJWT or API Key

Bulk move objects.

POST/api/buckets/:bucketId/objects/bulk-copyJWT or API Key

Bulk copy objects.


Upload Sessions#

POST/api/user/upload/initJWT Required

Initiate a new upload session. Requires an active subscription.

Request Body

NameTypeDescription
files*object[]Array of {name, size, mimeType}
GET/api/user/upload/activeJWT Required

Get the current active upload session.

GET/api/user/upload/:sessionIdJWT Required

Get session status and per-file progress.

GET/api/user/upload/:sessionId/eventsJWT Required

Get session event log.

POST/api/user/upload/:sessionId/fileJWT Required

Upload a file to a session (multipart/form-data).

POST/api/user/upload/:sessionId/cancelJWT Required

Cancel a session and revert all uploaded files.


User Files#

GET/api/user/filesJWT Required

List files owned by the authenticated user.

DELETE/api/user/files/:idJWT Required

Delete a user-owned file.

GET/api/user/files/:id/downloadJWT Required

Download a user-owned file.

GET/api/user/files/:id/presignedJWT Required

Get a presigned URL for a user-owned file.


User Settings#

GET/api/user/settingsJWT Required

Get the user's storage usage and settings.

PATCH/api/user/settingsJWT Required

Update user settings.


Trash#

GET/api/trashJWT Required

List items in trash.

PATCH/api/trash/:id/restoreJWT Required

Restore an item from trash.

DELETE/api/trash/emptyJWT Required

Permanently delete all trash items.

DELETE/api/trash/:id/permanentJWT Required

Permanently delete a single trash item.


File Serving#

GET/api/serve

Serve a file via HMAC presigned token. Public endpoint — accessible without authentication.

Query Parameters

NameTypeDescription
token*stringHMAC-signed presigned token