Getting Started

✓

Quick start

You'll be making your first authenticated API call in under 5 minutes.

What is Stashly?#

Stashly is a multi-tenant file storage platform with a REST API. It handles:

—Secure file uploads via resumable upload sessions
—Bucket and object management
—Scoped API key access control
—Per-tenant storage quotas and billing
—Webhooks for real-time integrations

The API is split across three services: Auth (port 5002), Storage (port 4000), and Billing (port 4001).

Quick Start#

Create an account

Sign up at the public web portal. You'll receive an OTP via email — verify it to receive your JWT token and session cookie.

Generate an API key

Log in to your dashboard and navigate to Settings → API Keys. Click Create key, select the permissions you need (view, add, edit, delete), and copy the key — it's only shown once.

sk_live_01j9xk2m...

Make your first request

Use your API key in the X-API-Key header:

curl -X GET https://api.stashly.io/api/buckets \
  -H "X-API-Key: sk_live_01j9xk2m..."

A successful response looks like:

{
  "success": true,
  "data": [
    { "id": "bkt_01j9xk2m", "name": "my-assets", "fileCount": 12 }
  ]
}

Upload your first file

Uploads use a session-based flow. First initiate a session, then upload files to it:

# 1. Create a session
curl -X POST https://api.stashly.io/api/user/upload/init \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"files": [{"name": "photo.jpg", "size": 2048000, "mimeType": "image/jpeg"}]}'

# 2. Upload the file to the session
curl -X POST https://api.stashly.io/api/user/upload/<sessionId>/file \
  -H "Authorization: Bearer <jwt>" \
  -F "file=@/path/to/photo.jpg"

Authentication Overview#

There are two ways to authenticate with the API:

Method	Header	Use case
JWT	`Authorization: Bearer <token>`	User sessions, dashboard access
API Key	`X-API-Key: sk_live_...`	Programmatic / server-to-server

See the Authentication guide for full details.

NextAuth Overview