​
SDK & API

SparkDB exposes a REST API for managing buckets programmatically. Authenticate with your API key and use any HTTP client.

​
Authentication

All SDK endpoints require an API key passed via the x-api-key header or Authorization: Bearer spk_* header. Get your API key from the SDK page in the dashboard.

​
Base URL

https://api.sparkdb.pro/api/v1/buckets

​
Common Examples

​
cURL

curl
# Create a bucket
curl -X POST https://api.sparkdb.pro/api/v1/buckets \
  -H "x-api-key: spk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"developer-assets","visibility":"public"}'

# List buckets
curl https://api.sparkdb.pro/api/v1/buckets \
  -H "x-api-key: spk_your_api_key"

# Upload a file
curl -X POST https://api.sparkdb.pro/api/v1/buckets/1/files \
  -H "x-api-key: spk_your_api_key" \
  -F "file=@./avatar.png"

# Download a private file
curl -O https://api.sparkdb.pro/api/v1/buckets/1/files/avatar.png \
  -H "x-api-key: spk_your_api_key"

​
JavaScript

JavaScript
async function uploadFile(bucketId, file) {
  const formData = new FormData();
  formData.append("file", file);

  const res = await fetch(
    `https://api.sparkdb.pro/api/v1/buckets/${bucketId}/files`,
    {
      method: "POST",
      headers: { "x-api-key": "spk_your_api_key" },
      body: formData,
    }
  );

  return res.json();
}

// List all buckets
async function listBuckets() {
  const res = await fetch("https://api.sparkdb.pro/api/v1/buckets", {
    headers: { "x-api-key": "spk_your_api_key" },
  });
  return res.json();
}

​
Python

Python
import requests

API_KEY = "spk_your_api_key"
BASE_URL = "https://api.sparkdb.pro/api/v1/buckets"

headers = {"x-api-key": API_KEY}

# Create a bucket
res = requests.post(
    BASE_URL,
    headers=headers,
    json={"name": "my-bucket", "visibility": "private"},
)
print(res.json())

# List buckets
res = requests.get(BASE_URL, headers=headers)
print(res.json())

# Upload a file
with open("photo.jpg", "rb") as f:
    res = requests.post(
        f"{BASE_URL}/1/files",
        headers=headers,
        files={"file": f},
    )
print(res.json())

​
Endpoint Summary

MethodPathDescription
GET/List all buckets
POST/Create a bucket
GET/:idGet bucket metadata
DELETE/:idDelete a bucket
POST/:id/visibilityToggle public/private
GET/:id/filesList files in a bucket
POST/:id/filesUpload a file
GET/:id/files/:filenameDownload a file
DELETE/:id/files/:filenameDelete a file
All SDK endpoints are available under both /api/v1/buckets and /api/v1/bucket. The API responds to both singular and plural forms.

​
Visibility Toggle

Change a bucket’s visibility after creation:
curl
curl -X POST https://api.sparkdb.pro/api/v1/buckets/1/visibility \
  -H "x-api-key: spk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"visibility":"public"}'

​
Rate Limits

PlanRate Limit
Free100 req/min
Plus200 req/min
Pro500 req/min
Max1500 req/min

​
Error Responses

StatusErrorDescription
400Validation errorInvalid bucket name or missing fields
401UnauthorizedMissing or invalid API key
404Not foundBucket doesn’t exist or was deleted
409Storage limit exceededUpload would exceed plan storage limit