Start a chunked upload

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects/chunked?name=dataset&filename=reads.fastq.gz&prefix=genomics&private=true' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  name: 'dataset',
  filename: file.name,
  prefix: 'genomics',
  private: 'true',
});

const res = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
});
const { response: upload } = await res.json();
// persist upload.upload: it is the handle to this upload

import requests

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

{
  "status": "success",
  "response": {
    "upload": "Zk3pQ8vR2mWx7LcT0aYbNe5uHs1JqGd9KoVfBr4XtIy6EwUz.q2Ws8nLc0VbR5TfYp3Hk",
    "id": "prv/3155597145698959364/genomics/dataset_mugws5c0-3c59dc048e8850243be8079a5c74d079.fastq.gz",
    "private": true,
    "url": null,
    "name": "dataset",
    "prefix": "genomics",
    "chunk": {
      "min_size": 5242880,
      "max_size": 33554432,
      "max_parts": 2048,
      "max_object_size": 10737418240
    }
  }
}

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 limit, up to 10 GiB. It returns an opaque upload token that you carry through the next calls:

Init

This route. Keep the upload token.

Send the parts

Chunked Part, in any order, up to 6 at a time.

Complete

Chunked Complete seals the file. Or Chunked Abort to cancel.

There is no server-side session: the token is the whole upload state, so persist it if the upload may span a page reload. Lost it? Open Uploads lists the open uploads with their tokens, and Chunked Status tells which parts already arrived. Uploads idle for 24 hours are aborted automatically.

Parameters

The query parameters are the same as in Object Post, plus filename and mime_type: there is no multipart envelope here, so the extension has to come from the query. Requires the blob:write scope, or an upload token, and an active plan.

string

required

The file name, without extension. Same pattern as in Object Post.

string

The original file name, extension included. The stored extension comes from it, then from mime_type, then falls back to bin.

string

Used for the extension only when filename has none.

string

Same as in Object Post.

boolean

Same as in Object Post.

string

Same as in Object Post.

boolean

Same as in Object Post.

boolean

Same as in Object Post.

string

Same as in Object Post.

boolean

Same as in Object Post.

string

Same as in Object Post.

string

Same as in Object Post.

Limits

File size: up to 10 GiB (10,737,418,240 bytes), or less when a rule or upload token sets a smaller limit.
Part size: 5 MB minimum (5,242,880 bytes), 32 MB maximum (33,554,432 bytes). The last part may be smaller.
Parts per file: up to 2048.
Open uploads per account: 32, counting uploads opened through the S3 gateway (TOO_MANY_OPEN_UPLOADS, 429).
Rate limit: 5 opens per 10 seconds.
An account already over its included storage can’t open uploads (STORAGE_QUOTA_EXCEEDED).

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

Response

string

“success” if successful, “error” if not.

object

Show Toggle object

string

The opaque upload token. Send it on every later call of the flow.

string

The id the file will have once completed.

boolean

Whether the file will be private.

string | null

The public URL the file will have, or null when private.

ISO 8601

When the file will be deleted. Present only when it expires.

string

The name sent in the request.

string

The prefix, when one was sent.

object

The limits of this upload: min_size and max_size (part bytes), max_parts, and max_object_size (file bytes).

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects/chunked?name=dataset&filename=reads.fastq.gz&prefix=genomics&private=true' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  name: 'dataset',
  filename: file.name,
  prefix: 'genomics',
  private: 'true',
});

const res = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
});
const { response: upload } = await res.json();
// persist upload.upload: it is the handle to this upload

import requests

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

{
  "status": "success",
  "response": {
    "upload": "Zk3pQ8vR2mWx7LcT0aYbNe5uHs1JqGd9KoVfBr4XtIy6EwUz.q2Ws8nLc0VbR5TfYp3Hk",
    "id": "prv/3155597145698959364/genomics/dataset_mugws5c0-3c59dc048e8850243be8079a5c74d079.fastq.gz",
    "private": true,
    "url": null,
    "name": "dataset",
    "prefix": "genomics",
    "chunk": {
      "min_size": 5242880,
      "max_size": 33554432,
      "max_parts": 2048,
      "max_object_size": 10737418240
    }
  }
}

Errors

Code	HTTP	When
`INVALID_OBJECT_*` / `INVALID_STORAGE_AUTO_DOWNLOAD`	400	A parameter is invalid, as in Object Post.
`INVALID_FILE_TYPE` / `BLOCKED_FILE_TYPE` / `FILE_TYPE_NOT_ALLOWED`	400	The extension is malformed, blocked, or not allowed by the rule or token.
`PERMISSION_DENIED`	401	The account has no active plan.
`UPLOAD_TOKEN_USED`	401	The upload token has no uses left. An expired token answers `ACCESS_DENIED`.
`STORAGE_QUOTA_EXCEEDED`	403	The account is already over its included storage.
`PREFIX_NOT_ALLOWED`	403	The upload token is bound to another prefix.
`UPGRADE_REQUIRED`	403	An option needs a higher plan.
`TOO_MANY_OPEN_UPLOADS`	429	The account has 32 open uploads. Complete or abort one.
`RATE_LIMITED`	429	More than 5 opens in 10 seconds.
`UPLOAD_FAILED`	500	The upload could not be opened. Retry.
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	Storage is temporarily unavailable. Retry.

Blob SDK: blob.put() runs the whole chunked flow for files above 90 MiB

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects/chunked?name=dataset&filename=reads.fastq.gz&prefix=genomics&private=true' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  name: 'dataset',
  filename: file.name,
  prefix: 'genomics',
  private: 'true',
});

const res = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
});
const { response: upload } = await res.json();
// persist upload.upload: it is the handle to this upload

import requests

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

{
  "status": "success",
  "response": {
    "upload": "Zk3pQ8vR2mWx7LcT0aYbNe5uHs1JqGd9KoVfBr4XtIy6EwUz.q2Ws8nLc0VbR5TfYp3Hk",
    "id": "prv/3155597145698959364/genomics/dataset_mugws5c0-3c59dc048e8850243be8079a5c74d079.fastq.gz",
    "private": true,
    "url": null,
    "name": "dataset",
    "prefix": "genomics",
    "chunk": {
      "min_size": 5242880,
      "max_size": 33554432,
      "max_parts": 2048,
      "max_object_size": 10737418240
    }
  }
}

Get started

Objects

Chunked uploads

Account

Share links

S3

Parameters

Limits

Response

Errors

​Parameters

​Limits

​Response

​Errors

​Related

Parameters

Limits

Response

Errors

Related