Blob Object Post

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"
    }
}

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 stored extension comes from the filename you send in the multipart part (falling back to the declared MIME type, then to bin), so always send a real filename. Practically any file type is accepted; only executables and installers are refused. Objects can be given an automatic expiration between 7 and 1825 days (5 years), after which they’re no longer served. A single request accepts files from 512 bytes up to 100 MB, the largest body Cloudflare’s edge accepts. Larger files, up to 1 GiB, go through the chunked upload flow. 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.
Send a real filename: the stored extension is derived from it.

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)

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)

number

A number indicating the expiration period of the file, ranging from 7 to 1825 days (5 years).

boolean

Set to true if a security hash is required.

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, formats a browser renders inline (.html, .svg, .xml, .xhtml and similar) are always delivered as downloads (served as application/octet-stream) instead of being rendered. Setting auto_download=true applies the same forced-download behavior to any file type.

File types

Practically any extension is accepted, including formats with no registered MIME type (.bam, .vcf, .fasta, .fastq, .parquet, .h5, .npy and so on). There is no MIME allowlist anymore.

The stored extension is derived from the filename sent in the multipart part, falling back to the declared MIME type, then to bin.
Compound compression suffixes are preserved: reads.fastq.gz is stored as .fastq.gz, not .gz.
The served Content-Type is derived server-side from the extension. Unknown formats are served as application/octet-stream, so they download instead of rendering.
Executables and installers are refused with BLOCKED_FILE_TYPE: exe, msi, dll, bat, cmd, com, scr, cpl, pif, hta, vbs, vbe, jse, wsf, wsh, msc, reg, lnk, sys, drv, ps1, apk, xpi.

Response

string

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

object

Show Toggle object

string

The ID of the uploaded file.

string

The name of the uploaded file.

string

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

number

The size of the uploaded file, in bytes.

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 uploaded filename).

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 7 to 1825. (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"
}

A single request accepts up to 100 MB. For files up to 1 GiB, use the chunked upload flow.

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

// The file extension is malformed or too long.
{
    "status": "error",
    "code": "INVALID_FILE_TYPE"
}

// Executable/installer extensions (exe, msi, bat, apk, ...) are not accepted.
{
    "status": "error",
    "code": "BLOCKED_FILE_TYPE"
}

// The file size is too small (< 512 bytes).
{
    "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

A single request accepts up to 100 MB. For files up to 1 GiB, use the chunked upload flow.

// A single request accepts up to 100 MB. Use /v1/objects/chunked for files up to 1 GiB.
{
    "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"
    }
}

Blob Endpoints

Chunked Uploads

Rate limits & concurrency

File types

Response

Troubleshooting

Unauthorized

Storage quota exceeded

Invalid content type

Payload too large

Rate limited

Upload failed

​Rate limits & concurrency

​File types

​Response

​Troubleshooting

​Object-Related

​File-Related

​Unauthorized

​Storage quota exceeded

​Invalid content type

​Payload too large

​Rate limited

​Upload failed

Rate limits & concurrency

File types

Response

Troubleshooting

Object-Related

File-Related

Unauthorized

Storage quota exceeded

Invalid content type

Payload too large

Rate limited

Upload failed