API Reference

Complete reference for the SparkDB Buckets API. All endpoints, request formats, response types, and error codes.

Base URLs

Client API:  https://api.sparkdb.pro/api/buckets
Developer API: https://api.sparkdb.pro/api/v1/buckets

Authentication

API	Method
Client API	Session cookie / JWT (from dashboard login)
Developer API	`x-api-key: spk_your_api_key` or `Authorization: Bearer spk_your_api_key`

Endpoints

Create Bucket

curl

POST /api/v1/buckets
Content-Type: application/json
x-api-key: spk_your_api_key

{
  "name": "my-assets",
  "visibility": "public"
}

Request Body

Field	Type	Default	Description
`name`	`string`	required	Bucket name, 3–40 chars, `^[a-z0-9][a-z0-9_-]{1,38}[a-z0-9]$`
`visibility`	`string`	`"private"`	`"public"` or `"private"`
`public`	`boolean`	`false`	Alternative to `visibility`

Response `201`

{
  "data": {
    "id": 1,
    "name": "my-assets",
    "public": true,
    "object_count": 0,
    "total_bytes": 0,
    "created_at": "2025-06-15T10:30:00Z"
  }
}

List Buckets

curl

GET /api/v1/buckets
x-api-key: spk_your_api_key

Response `200`

{
  "data": [
    {
      "id": 1,
      "name": "my-assets",
      "public": true,
      "object_count": 15,
      "total_bytes": 2457600,
      "created_at": "2025-06-15T10:30:00Z"
    }
  ],
  "buckets": [
    // Same as data (redundant keys)
  ]
}

Get Bucket

curl

GET /api/v1/buckets/1
x-api-key: spk_your_api_key

Response `200`

{
  "data": {
    "id": 1,
    "name": "my-assets",
    "public": false,
    "object_count": 42,
    "total_bytes": 5242880,
    "created_at": "2025-06-15T10:30:00Z"
  }
}

Response `404`

{
  "error": "Bucket not found"
}

Delete Bucket

curl

DELETE /api/v1/buckets/1
x-api-key: spk_your_api_key

Deletes all S3 objects, then soft-deletes the bucket record.

Response `200`

{
  "message": "Bucket deleted successfully"
}

Update Visibility

curl

POST /api/v1/buckets/1/visibility
Content-Type: application/json
x-api-key: spk_your_api_key

{
  "visibility": "public"
}

Request Body

Field	Type	Description
`visibility`	`string`	`"public"` or `"private"`

Response `200`

{
  "message": "Visibility updated"
}

List Files

curl

GET /api/v1/buckets/1/files
x-api-key: spk_your_api_key

Response `200`

{
  "data": [
    {
      "id": "1/avatar.png",
      "bucket_id": 1,
      "storage_name": "avatar.png",
      "filename": "avatar.png",
      "size": 245760,
      "content_type": "image/png",
      "url": "https://bucket.sparkdb.pro/spark-42-my-assets-a1b2/avatar.png",
      "created_at": "2025-06-15T10:30:00Z"
    }
  ],
  "objects": [
    // Same as data (redundant keys)
  ]
}

Upload File

curl

POST /api/v1/buckets/1/files
Content-Type: multipart/form-data
x-api-key: spk_your_api_key

file: @avatar.png

Response `201`

{
  "data": {
    "filename": "avatar.png",
    "size": 245760,
    "updated": true
  }
}

Response `409`

{
  "error": "Storage limit exceeded. Your plan allows up to 1GB of storage."
}

Upload File (Raw Body)

curl

PUT /api/v1/buckets/1/files/avatar.png
Content-Type: image/png
x-api-key: spk_your_api_key

<binary file data>

Uploads the raw request body as the file content. The Content-Type header sets the file’s MIME type. Use this for programmatic uploads where multipart form data is not convenient.

Download File

curl

GET /api/v1/buckets/1/files/avatar.png
x-api-key: spk_your_api_key    # Required for private buckets, optional for public

Returns the raw file with the correct Content-Type and Content-Length headers.

Get File Metadata

curl

HEAD /api/v1/buckets/1/files/avatar.png
x-api-key: spk_your_api_key

Returns response headers with Content-Type, Content-Length, ETag, and Last-Modified. No response body.

Delete File

curl

DELETE /api/v1/buckets/1/files/avatar.png
x-api-key: spk_your_api_key

Response `200`

{
  "message": "File deleted successfully"
}

Client API Endpoints

The client API (session-based) mirrors the developer API but under /api/buckets:

Method	Path	Description
`GET`	`/api/buckets`	List buckets
`POST`	`/api/buckets`	Create bucket
`GET`	`/api/buckets/:id`	Get bucket
`DELETE`	`/api/buckets/:id`	Delete bucket
`POST` / `PATCH`	`/api/buckets/:id/visibility`	Update visibility
`GET`	`/api/buckets/:id/files`	List files
`GET`	`/api/buckets/:id/objects`	List files (alias)
`POST`	`/api/buckets/:id/files`	Upload file (multipart)
`POST`	`/api/buckets/:id/upload`	Upload file (alias)
`PUT`	`/api/buckets/:id/files/:filename`	Upload file (raw body)
`HEAD`	`/api/buckets/:id/files/:filename`	Get file metadata
`GET`	`/api/buckets/:id/files/:filename`	Download file
`DELETE`	`/api/buckets/:id/files/:filename`	Delete file

Developer API Endpoints

The developer API also supports these additional aliases under /api/v1/buckets:

Method	Path	Description
`GET`	`/api/v1/buckets/list`	List buckets (alias)
`POST`	`/api/v1/buckets/create`	Create bucket (alias)
`DELETE`	`/api/v1/buckets/:id/delete`	Delete bucket (alias)
`DELETE`	`/api/v1/buckets/:id/files/:filename/delete`	Delete file (alias)

Object Reference

StorageBucket

{
  "id": 1,
  "name": "my-assets",
  "public": true,
  "object_count": 42,
  "total_bytes": 5242880,
  "created_at": "2025-06-15T10:30:00Z"
}

Field	Type	Description
`id`	`number`	Unique bucket identifier
`name`	`string`	Human-readable bucket name
`public`	`boolean`	Whether files are publicly accessible
`object_count`	`number`	Number of files in the bucket
`total_bytes`	`number`	Total storage used by the bucket
`created_at`	`string`	ISO 8601 timestamp

BucketObject

{
  "id": "1/avatar.png",
  "bucket_id": 1,
  "storage_name": "avatar.png",
  "filename": "avatar.png",
  "size": 245760,
  "content_type": "image/png",
  "url": "https://bucket.sparkdb.pro/spark-42-my-assets-a1b2/avatar.png",
  "created_at": "2025-06-15T10:30:00Z"
}

Field	Type	Description
`id`	`string`	Object identifier (`{bucketId}/{filename}`)
`bucket_id`	`number`	Parent bucket ID
`storage_name`	`string`	S3 key name
`filename`	`string`	Original filename
`size`	`number`	File size in bytes
`content_type`	`string`	MIME type
`url`	`string`	Download URL
`created_at`	`string`	ISO 8601 timestamp

Error Codes

Code	HTTP Status	Description
`BucketNotFoundError`	404	Bucket doesn’t exist or was soft-deleted
`StorageLimitExceededError`	409	Upload exceeds plan storage limit. Error message includes plan limit.
Validation error	400	Invalid bucket name, missing fields
Unauthorized	401	Missing or invalid API key

​API Reference

​Base URLs

​Authentication

​Endpoints

​Create Bucket

​Request Body

​Response 201

​List Buckets

​Response 200

​Get Bucket

​Response 200

​Response 404

​Delete Bucket

​Response 200

​Update Visibility

​Request Body

​Response 200

​List Files

​Response 200

​Upload File

​Response 201

​Response 409

​Upload File (Raw Body)

​Download File

​Get File Metadata

​Delete File

​Response 200

​Client API Endpoints

​Developer API Endpoints

​Object Reference

​StorageBucket

​BucketObject

​Error Codes

API Reference

Base URLs

Authentication

Endpoints

Create Bucket

Request Body

Response `201`

List Buckets

Response `200`

Get Bucket

Response `200`

Response `404`

Delete Bucket

Response `200`

Update Visibility

Request Body

Response `200`

List Files

Response `200`

Upload File

Response `201`

Response `409`

Upload File (Raw Body)

Download File

Get File Metadata

Delete File

Response `200`

Client API Endpoints

Developer API Endpoints

Object Reference

StorageBucket

BucketObject

Error Codes