Blob Object Post - Square Cloud

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./myphone.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
        files={'file': ('myphone.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

Authorization

string

required

The API key for your account. You can find this in your account settings.

Object Post uploads a single file to Square Cloud Blob Storage and returns a CDN-backed URL you can embed or share directly, without provisioning a bucket or managing ACLs yourself. It backs attachments, generated exports, and user-uploaded media for applications hosted on the platform. The uploaded file’s declared content type must match one of the platform’s allowed MIME types; anything outside that list is rejected as INVALID_FILE_TYPE before the file reaches storage. Objects can be given an automatic expiration between 1 and 365 days, after which they’re no longer served. Once a file is uploaded, browse it with Object List, remove it with Object Delete, or track usage against your plan’s quota with Account Stats.

file

required

Use FormData (multipart/form-data). Exactly one file per request.

name

string

required

A string representing the name of the file. (without extension)
Must adhere to the a to z, A to Z, 0 to 9, and _ pattern. (3 to 32 characters)

prefix

string

A string representing the prefix for the file.
Must adhere to the a to z, A to Z, 0 to 9, and _ pattern. (3 to 32 characters)

expire

number

A number indicating the expiration period of the file, ranging from 1 to 365 days.

security_hash

boolean

Set to true if a security hash is required.

auto_download

boolean

Set to true if the file should be set for automatic download.

Rate limits & concurrency

Uploading requires a paid plan.

Every account may have at most 4 uploads in progress simultaneously. Starting another upload while 4 are still running returns TOO_MANY_CONCURRENT_UPLOADS (429).
Hobby and Standard plans are additionally limited to 1 upload per second (RATE_LIMITED, 429). Pro and Enterprise plans are exempt from the per-second limit.

For security, .html and .svg files are always delivered as downloads (served as application/octet-stream) instead of being rendered inline. Setting auto_download=true applies the same forced-download behavior to any file type.

Allowed MIME types

Uploads are validated against a strict MIME allowlist; anything outside it is rejected with INVALID_FILE_TYPE. The stored file extension is derived server-side from the MIME type.

Category	MIME types
Video	`video/mp4`, `video/mpeg`, `video/webm`, `video/x-flv`, `video/x-m4v`
Image	`image/jpeg`, `image/png`, `image/apng`, `image/tiff`, `image/gif`, `image/webp`, `image/bmp`, `image/svg+xml`, `image/x-icon`, `image/ico`, `image/cur`, `image/heic`, `image/heif`
Audio	`audio/wav`, `audio/ogg`, `audio/opus`, `audio/mp4`, `audio/mpeg`, `audio/aac`
Text	`text/html`, `text/css`, `text/csv`, `text/plain`, `text/x-sql`
Application	`application/xml`, `application/sql`, `application/x-sql`, `application/x-sqlite3`, `application/x-pkcs12`, `application/pdf`, `application/json`, `application/javascript`

Response

status

string

Indicates whether the call was successful. “success” if successful, “error” if not.

response

object

Show Toggle object

string

The ID of the uploaded file.

name

string

The name of the uploaded file.

prefix

string

The prefix under which the file was stored (echoed from the prefix query; omitted when none was sent).

size

number

The size of the uploaded file, in bytes.

url

string

The public CDN URL of the uploaded file: https://public-blob.squarecloud.dev/<user_id>/<key>, where the key is [prefix/]name[_hash][-exN].ext (hash and expiration suffixes appear only when used; the extension is derived from the MIME type).

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./myphone.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
        files={'file': ('myphone.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

Troubleshooting

// The provided object name is invalid.
// Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
{
    "status": "error",
    "code": "INVALID_OBJECT_NAME"
}

// The provided object prefix is invalid.
// Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
{
    "status": "error",
    "code": "INVALID_OBJECT_PREFIX"
}

// The provided expiration value for the object is invalid.
// Must be a number ranging from 1 to 365. (value in days).
{
    "status": "error",
    "code": "INVALID_OBJECT_EXPIRE"
}

// The provided security hash boolean is invalid.
// Just set to true or false. 😅
{
    "status": "error",
    "code": "INVALID_OBJECT_SECURITY_HASH"
}

// The provided auto-download boolean is invalid.
// Just set to true or false. 😅
{
    "status": "error",
    "code": "INVALID_STORAGE_AUTO_DOWNLOAD"
}

The current maximum file size is 100MB. In the future, we plan to increase it to 10GB. For now, the limit is 100MB due to technical and load-balancing constraints.

// The provided file is invalid.
{
    "status": "error",
    "code": "INVALID_FILE"
}

// The provided file type is invalid.
{
    "status": "error",
    "code": "INVALID_FILE_TYPE"
}

// The file size is too small (< 1kb).
{
    "status": "error",
    "code": "FILE_TOO_SMALL"
}

Unauthorized

// The API key is missing or invalid. Set a valid key in the Authorization header.
{
    "status": "error",
    "code": "ACCESS_DENIED"
}

// The account has no active paid plan. Uploading to Blob Storage requires a paid plan.
{
    "status": "error",
    "code": "PERMISSION_DENIED"
}

Storage quota exceeded

// You have exceeded your storage quota. Delete some files or upgrade your plan.
{
    "status": "error",
    "code": "STORAGE_QUOTA_EXCEEDED"
}

Invalid content type

// This route only accepts multipart/form-data requests with exactly one file.
{
    "status": "error",
    "code": "INVALID_CONTENT_TYPE"
}

Payload too large

The current maximum file size is 100MB.

// The uploaded file exceeds the maximum allowed size of 100 MB.
{
    "status": "error",
    "code": "FILE_TOO_LARGE"
}

Rate limited

// Per-second upload limit reached (Hobby/Standard: max 1 upload per second).
{
    "status": "error",
    "code": "RATE_LIMITED"
}

// Too many simultaneous uploads (max 4 in progress at a time per account).
{
    "status": "error",
    "code": "TOO_MANY_CONCURRENT_UPLOADS"
}

Upload failed

// Failed to upload object to storage. Please try again later.
{
    "status": "error",
    "code": "UPLOAD_FAILED"
}

Objects DeleteThis documentation provides a comprehensive overview of the DELETE /v1/objects endpoint of the SquareCloud Blob API.

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./myphone.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
        files={'file': ('myphone.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

​Rate limits & concurrency

​Allowed MIME types

​Response

​Troubleshooting

​Object-Related

​File-Related

​Unauthorized

​Storage quota exceeded

​Invalid content type

​Payload too large

​Rate limited

​Upload failed

Rate limits & concurrency

Allowed MIME types

Response

Troubleshooting

Object-Related

File-Related

Unauthorized

Storage quota exceeded

Invalid content type

Payload too large

Rate limited

Upload failed