Storage API

REST endpoints for the three-step upload flow, presigned download URLs, file listing, and deletion.

Base URL & auth

Base URL: https://api.koolbase.com/v1/sdk

Required headers:
  x-api-key: pk_live_your_public_key_here

Endpoints

POST/sdk/storage/upload-urlGet a presigned R2 upload URL

POST/sdk/storage/confirmConfirm upload and record metadata

GET/sdk/storage/download-urlGet a download URL for a file

GET/sdk/storage/listList files in a bucket

DELETE/sdk/storage/objectDelete a file

POST /sdk/storage/upload-url

// Request
{
  "bucket": "avatars",
  "path": "user_abc123.jpg",
  "content_type": "image/jpeg"
}

// Response 200
{
  "upload_url": "https://r2.example.com/presigned?...",
  "expires_in": 300
}

After receiving the URL, PUT the file bytes directly to upload_url. The URL expires in 300 seconds.

POST /sdk/storage/confirm

// Request — call after successful PUT to R2
{
  "bucket": "avatars",
  "path": "user_abc123.jpg",
  "content_type": "image/jpeg",
  "size": 204800
}

// Response 201
{
  "id": "uuid",
  "bucket": "avatars",
  "path": "user_abc123.jpg",
  "content_type": "image/jpeg",
  "size": 204800,
  "created_at": "2026-01-01T00:00:00Z"
}

GET /sdk/storage/download-url

// Query params: ?bucket=avatars&path=user_abc123.jpg

// Response 200
{
  "url": "https://pub-xxx.r2.dev/user_abc123.jpg"
}

GET /sdk/storage/list

// Query params: ?bucket=avatars&prefix=user_

// Response 200
{
  "files": [
    {
      "path": "user_abc123.jpg",
      "size": 204800,
      "content_type": "image/jpeg",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

DELETE /sdk/storage/object

// Request body
{ "bucket": "avatars", "path": "user_abc123.jpg" }

// Response 204 No Content