Blob Create Share

POST

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/shares' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "expires_in": 604800,
    "max_downloads": 5
  }'

const response = await fetch('https://blob.squarecloud.app/v1/shares', {
  method: 'POST',
  headers: {
    Authorization: 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    object: 'prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf',
    expires_in: 7 * 24 * 60 * 60,
    max_downloads: 5,
  }),
});

{
  "status": "success",
  "response": {
    "id": "q8Zr2LwX7nT0vKc4Hs1YbA",
    "url": "https://files.squarecloud.dev/s/q8Zr2LwX7nT0vKc4Hs1YbA",
    "expires_at": "2026-10-02T12:00:00.000Z",
    "max_downloads": 5,
    "password": false,
    "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "object_is_public": false
  }
}

string

required

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

Create Share makes a link (https://files.squarecloud.dev/s/...) to hand one file to people: a client, a team, a tester. It works for public and private files, lasts up to 30 days, can be revoked at any time and can limit how many times the file is downloaded. On Pro and Enterprise it can also ask for a password. Requires the blob:write scope. Opening the link downloads the file. A password-protected link first shows a page asking for the password, in the visitor’s language. The link is tied to the file’s current id: deleting, moving or changing the visibility of the file makes it answer 404 right away, without spending a download. See Links and sharing for how it compares to temporary links.

string

required

The id of the file to share.

number

default:"86400"

How long the link lasts, from 60 to 2592000 seconds (30 days).

number

How many downloads the link allows, from 1 to 10000. Once spent, it answers 410. Without it, there is no cap.

string

A password of 8 to 128 characters the visitor must type before downloading. Pro and Enterprise only.

For a public file the link redirects to its permanent public URL, which anyone who opens it can keep using. The password, the download cap and the expiry only truly protect private files.

Limits

30 links per minute (RATE_LIMITED, 429), and up to 1000 active links per account (TOO_MANY_SHARES, 409).
Each link accepts 120 visits per minute per IP. Wrong passwords are limited per IP and per link.
Downloading a private file goes through a temporary link: 60 requests per minute per IP, plus the overall limit of your account. To hand a file to many people, make it public.

Response

Answers 201 Created.

string

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

object

Show Toggle object

string

The share id. Use it with Delete Share.

string

The link to hand out.

ISO 8601

When the link expires.

number | null

The download cap, or null.

boolean

Whether the link asks for a password.

string

The id of the shared file.

boolean

true when the file is public: anyone with its public URL can still download it, so revoking, capping or protecting the share doesn’t restrict access to the file itself.

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/shares' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "expires_in": 604800,
    "max_downloads": 5
  }'

const response = await fetch('https://blob.squarecloud.app/v1/shares', {
  method: 'POST',
  headers: {
    Authorization: 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    object: 'prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf',
    expires_in: 7 * 24 * 60 * 60,
    max_downloads: 5,
  }),
});

{
  "status": "success",
  "response": {
    "id": "q8Zr2LwX7nT0vKc4Hs1YbA",
    "url": "https://files.squarecloud.dev/s/q8Zr2LwX7nT0vKc4Hs1YbA",
    "expires_at": "2026-10-02T12:00:00.000Z",
    "max_downloads": 5,
    "password": false,
    "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "object_is_public": false
  }
}

Errors

Code	HTTP	When
`INVALID_OBJECT`	400	`object` is missing, malformed or not yours.
`INVALID_EXPIRES_IN`	400	`expires_in` is not an integer from 60 to 2592000.
`INVALID_MAX_DOWNLOADS`	400	`max_downloads` is not an integer from 1 to 10000.
`INVALID_PASSWORD`	400	The password doesn’t have 8 to 128 characters.
`UPGRADE_REQUIRED`	403	Passwords need Pro or Enterprise.
`OBJECT_NOT_FOUND`	404	The file doesn’t exist.
`TOO_MANY_SHARES`	409	The account has 1000 active links. Revoke some first.
`RATE_LIMITED`	429	More than 30 links in a minute.

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/shares' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "expires_in": 604800,
    "max_downloads": 5
  }'

const response = await fetch('https://blob.squarecloud.app/v1/shares', {
  method: 'POST',
  headers: {
    Authorization: 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    object: 'prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf',
    expires_in: 7 * 24 * 60 * 60,
    max_downloads: 5,
  }),
});

{
  "status": "success",
  "response": {
    "id": "q8Zr2LwX7nT0vKc4Hs1YbA",
    "url": "https://files.squarecloud.dev/s/q8Zr2LwX7nT0vKc4Hs1YbA",
    "expires_at": "2026-10-02T12:00:00.000Z",
    "max_downloads": 5,
    "password": false,
    "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "object_is_public": false
  }
}

Getting Started

Objects

Chunked Uploads

Account

Share Links

S3

Limits

Response

Errors

​Limits

​Response

​Errors

Limits

Response

Errors