Blob Chunked Upload Init

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects/chunked?name=myfile&filename=reads.fastq.gz&expire=30' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  name: 'myfile',
  filename: 'reads.fastq.gz',
  expire: '30',
});

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

const { response: upload } = await response.json();
// persist upload.upload — it is the only handle to this upload

import requests

response = requests.post(
    'https://blob.squarecloud.app/v1/objects/chunked',
    headers={'Authorization': 'YOUR_API_KEY'},
    params={'name': 'myfile', 'filename': 'reads.fastq.gz', 'expire': 30},
)
upload = response.json()['response']

{
  "status": "success",
  "response": {
    "upload": "MzE1NTU5NzE0NTY5ODk1OTM2NC9teWZpbGUtZXgzMC5mYXN0cS5negoyfjQ4WXcuLi4KMzA",
    "id": "3155597145698959364/myfile-ex30.fastq.gz",
    "name": "myfile",
    "prefix": null,
    "url": "https://public-blob.squarecloud.dev/3155597145698959364/myfile-ex30.fastq.gz",
    "chunk": {
      "min_size": 5242880,
      "max_size": 33554432,
      "max_parts": 205,
      "max_object_size": 1073741824
    }
  }
}

string

required

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

Chunked Init opens a chunked upload, the flow for files above the 100 MB single-request cap, up to 1 GiB. It reserves the object’s key and returns an opaque upload token that you carry through the three follow-up calls: Chunked Part to send each chunk, Chunked Complete to seal the object, and Chunked Abort to cancel. There is no server-side session: the token is the whole upload state, so persist it if the upload spans a page reload. A client that loses its token cannot cancel the upload, and the stored chunks count against the account’s limit of 8 open uploads until the service reclaims them (about 24 hours). The query contract is the same as Object Post, plus filename: there is no multipart envelope here, so the stored extension has to come from the query string. Uploading requires a paid plan.

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

The original filename, extension included (e.g. reads.fastq.gz). The stored extension is derived from it, falling back to the mime_type parameter, then to bin.

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.

Limits

Object size: up to 1 GiB (1,073,741,824 bytes).
Chunk size: 5 MB minimum, 32 MB maximum (the last chunk may be smaller).
Chunks per object: 205 (part numbers run from 1 to 205).
Open uploads per account: 8 simultaneous (TOO_MANY_OPEN_UPLOADS, 429).
Rate limit: 5 opens per 10 seconds, blocked for 10 seconds past that.

Read the limits from the chunk object in the response rather than hardcoding them.

Response

string

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

object

Show Toggle object

string

The opaque upload token. Carry it through every later call of the flow; it is the only handle to this upload.

string

The ID (key) the object will be stored under.

string

The name of the file.

string

The prefix under which the file will be stored (null when none was sent).

string

The public CDN URL the object will be served from once completed.

object

The chunked-flow limits: min_size and max_size (chunk bytes), max_parts, and max_object_size (total bytes).

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects/chunked?name=myfile&filename=reads.fastq.gz&expire=30' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  name: 'myfile',
  filename: 'reads.fastq.gz',
  expire: '30',
});

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

const { response: upload } = await response.json();
// persist upload.upload — it is the only handle to this upload

import requests

response = requests.post(
    'https://blob.squarecloud.app/v1/objects/chunked',
    headers={'Authorization': 'YOUR_API_KEY'},
    params={'name': 'myfile', 'filename': 'reads.fastq.gz', 'expire': 30},
)
upload = response.json()['response']

{
  "status": "success",
  "response": {
    "upload": "MzE1NTU5NzE0NTY5ODk1OTM2NC9teWZpbGUtZXgzMC5mYXN0cS5negoyfjQ4WXcuLi4KMzA",
    "id": "3155597145698959364/myfile-ex30.fastq.gz",
    "name": "myfile",
    "prefix": null,
    "url": "https://public-blob.squarecloud.dev/3155597145698959364/myfile-ex30.fastq.gz",
    "chunk": {
      "min_size": 5242880,
      "max_size": 33554432,
      "max_parts": 205,
      "max_object_size": 1073741824
    }
  }
}

Troubleshooting

400 Status Code
401 Status Code
403 Status Code
429 Status Code
500 Status Code

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

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

Rate limited

// Init rate limit reached (5 opens per 10s window, blocked for 10s).
{
    "status": "error",
    "code": "RATE_LIMITED"
}

// 8 chunked uploads already open. Complete or abort one first.
{
    "status": "error",
    "code": "TOO_MANY_OPEN_UPLOADS"
}

Upload failed

// Failed to open the chunked upload. Please try again later.
{
    "status": "error",
    "code": "UPLOAD_FAILED"
}

Chunked PartThis documentation provides a comprehensive overview of the PUT /v1/objects/chunked endpoint of the SquareCloud Blob API.

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects/chunked?name=myfile&filename=reads.fastq.gz&expire=30' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  name: 'myfile',
  filename: 'reads.fastq.gz',
  expire: '30',
});

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

const { response: upload } = await response.json();
// persist upload.upload — it is the only handle to this upload

import requests

response = requests.post(
    'https://blob.squarecloud.app/v1/objects/chunked',
    headers={'Authorization': 'YOUR_API_KEY'},
    params={'name': 'myfile', 'filename': 'reads.fastq.gz', 'expire': 30},
)
upload = response.json()['response']

{
  "status": "success",
  "response": {
    "upload": "MzE1NTU5NzE0NTY5ODk1OTM2NC9teWZpbGUtZXgzMC5mYXN0cS5negoyfjQ4WXcuLi4KMzA",
    "id": "3155597145698959364/myfile-ex30.fastq.gz",
    "name": "myfile",
    "prefix": null,
    "url": "https://public-blob.squarecloud.dev/3155597145698959364/myfile-ex30.fastq.gz",
    "chunk": {
      "min_size": 5242880,
      "max_size": 33554432,
      "max_parts": 205,
      "max_object_size": 1073741824
    }
  }
}

Blob Endpoints

Chunked Uploads

Blob Chunked Upload Init

Limits

Response

Troubleshooting

Unauthorized

Storage quota exceeded

Rate limited

Upload failed

​Limits

​Response

​Troubleshooting

​Object-Related

​Unauthorized

​Storage quota exceeded

​Rate limited

​Upload failed

Limits

Response

Troubleshooting

Object-Related

Unauthorized

Storage quota exceeded

Rate limited

Upload failed