Blob Storage API quickstart

Blob Storage keeps your files, serves public ones from a CDN and hands out links to private ones. This page takes you from an API key to an uploaded file and a download link, with curl. Storage is included in every plan: see Blob Storage for the plans, prices and FAQ.

Base URL

Every endpoint of this reference is relative to:

https://blob.squarecloud.app/v1

Authentication

Blob Storage takes the same API keys as the Square Cloud API, in the Authorization header. The key needs the blob:write scope to upload and blob:read to list and download, and it can’t be restricted to specific applications. Create one in your account security settings and keep it in an environment variable:

export SQUARECLOUD_API_KEY="your-api-key"

More on scopes and upload tokens in Authentication.

Upload a file

Object Post takes the file as multipart/form-data and its name, without extension, in the query:

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./logo.png'

{
  "status": "success",
  "response": {
    "id": "pub/3155597145698959364/images/logo.png",
    "private": false,
    "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo.png",
    "size": 416230,
    "name": "logo",
    "prefix": "images",
    "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
    "replaced": false
  }
}

The file is public by default: url works right away in a browser or an <img> tag. Store the id as it comes, since every other route takes it. A single request takes files from 512 bytes to 100 MB. Larger files, up to 10 GiB, go through the chunked upload or the S3 gateway.

Upload a private file

Add private=true and the file gets no public URL (url is null):

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=invoice&prefix=invoices&private=true' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./invoice.pdf'

Download a file

A public file downloads from its url. For a private one, Object Download signs a temporary link that works without credentials, and redirects to it, so curl -L saves the file:

curl -L --output invoice.pdf \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=<id>' \
  --header "Authorization: $SQUARECLOUD_API_KEY"

Replace <id> with the id of the upload. Add redirect=false to get the link as JSON and hand it to someone else. For links you can revoke or protect with a password, create a share link.

List and delete files

Object List returns your files page by page:

curl --url 'https://blob.squarecloud.app/v1/objects?prefix=images/' \
  --header "Authorization: $SQUARECLOUD_API_KEY"

Objects Delete removes one file, or up to 100 in one request:

curl --request DELETE \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "object": "<id>" }'

When something fails

Errors come as { "status": "error", "code": "..." }. The ones you are most likely to meet first:

Code	HTTP	Fix
`ACCESS_DENIED`	401	The key is missing or not recognized. Check the `Authorization` header.
`PERMISSION_DENIED`	401	The account has no active plan, so it can’t upload.
`MISSING_SCOPE`	403	The key lacks `blob:write` or `blob:read`. Create a key with that scope.
`RESOURCE_NOT_ALLOWED`	403	The key is restricted to applications. Use a key without that restriction.
`FILE_TOO_LARGE`	413	The file is over 100 MB. Use the chunked upload.

Every code is in Errors.

Next steps

Blob SDK

Upload and manage files from JavaScript, with chunked uploads handled for you.

S3 compatibility

Use aws-cli, boto3, rclone or any AWS SDK.

Links and sharing

Temporary links, share links and when to use each.

Upload from the browser

Let visitors upload without exposing your API key.

Get started

Objects

Chunked uploads

Account

Share links

S3

Blob Storage API quickstart

Base URL

Authentication

Upload a file

Upload a private file

Download a file

List and delete files

When something fails

Next steps

Blob SDK

S3 compatibility

Links and sharing

Upload from the browser

​Base URL

​Authentication

​Upload a file

​Upload a private file

​Download a file

​List and delete files

​When something fails

​Next steps

Blob SDK

S3 compatibility

Links and sharing

Upload from the browser

Base URL

Authentication

Upload a file

Upload a private file

Download a file

List and delete files

When something fails

Next steps