Blob Update Settings

PUT

account

settings

curl --request PUT \
  --url 'https://blob.squarecloud.app/v1/account/settings' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "rules": [
      { "prefix": "invoices", "private": true, "extensions": ["pdf"] },
      { "prefix": "avatars", "max_size": 2097152, "extensions": ["png", "jpg", "webp"], "cache_control": "max-age=86400" },
      { "prefix": "tmp", "delete_after_days": 7 }
    ]
  }'

{
  "status": "success",
  "response": {
    "rules": [
      { "prefix": "invoices/", "private": true, "extensions": ["pdf"], "created_at": "2026-09-25T12:00:00.000Z" },
      { "prefix": "avatars/", "max_size": 2097152, "extensions": ["png", "jpg", "webp"], "cache_control": "max-age=86400", "created_at": "2026-09-25T12:00:00.000Z" },
      { "prefix": "tmp/", "delete_after_days": 7, "created_at": "2026-09-25T12:00:00.000Z", "active_from": "2026-09-26T12:00:00.000Z" }
    ]
  }
}

string

required

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

Update Settings saves your rules, each applying to the files under a prefix. A rule sets defaults and limits once, for every upload under it, whether it comes from your backend, an upload token or the dashboard. Requires the blob:write scope and a paid plan. Each plan allows a number of rules: 5 on Hobby and Standard, 10 on Pro and 20 on Enterprise. Rules saved before a downgrade keep applying, but the next save must fit the new plan. The request replaces the whole list: send every rule you want to keep, and {"rules": []} removes them all. When several rules match a file, the one with the longest prefix wins.

Defaults (private, expire, cache_control) apply when the upload doesn’t set its own value.
Limits (max_size, extensions) refuse uploads outside them with FILE_TOO_LARGE or FILE_TYPE_NOT_ALLOWED. They apply to REST uploads, not to the S3 gateway.
Automatic deletion (delete_after_days) deletes files a number of days after they were written. It applies to every file under the prefix, including files that already existed and files written over S3.

Automatic deletion only starts 24 hours after the rule is saved (active_from in Get Settings), so you have a day to catch a prefix that is broader than intended. Saving an unchanged rule again keeps its original date. Once active, deleted files can’t be recovered.

object[]

required

Up to 5 rules on Hobby and Standard, 10 on Pro and 20 on Enterprise.

Show properties

string

required

The prefix, same pattern as in Object Post. Saved with a trailing /, so invoices covers invoices/... and not invoices-old/....

boolean

Default visibility of new files.

string

Default expiry of new files (30d, 6h). Under 7 days needs Enterprise.

number

Maximum file size in bytes, from 512 to 10737418240 (10 GiB).

string[]

Accepted extensions, 1 to 50, lowercase and without the dot (pdf, tar.gz).

string

Default cache: immutable, max-age=N or no-cache (Enterprise only).

number

Deletes files this many days after they were written, from 1 to 3650. Under 7 needs Enterprise.

If the plan changes to one that doesn’t include a rule’s option (for example an expiry under 7 days after leaving Enterprise), uploads under that prefix are refused with UPGRADE_REQUIRED until the rule is changed.

Rate limits

10 requests per minute (RATE_LIMITED, 429).

Response

Returns the saved rules, in the same shape as Get Settings.

curl --request PUT \
  --url 'https://blob.squarecloud.app/v1/account/settings' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "rules": [
      { "prefix": "invoices", "private": true, "extensions": ["pdf"] },
      { "prefix": "avatars", "max_size": 2097152, "extensions": ["png", "jpg", "webp"], "cache_control": "max-age=86400" },
      { "prefix": "tmp", "delete_after_days": 7 }
    ]
  }'

{
  "status": "success",
  "response": {
    "rules": [
      { "prefix": "invoices/", "private": true, "extensions": ["pdf"], "created_at": "2026-09-25T12:00:00.000Z" },
      { "prefix": "avatars/", "max_size": 2097152, "extensions": ["png", "jpg", "webp"], "cache_control": "max-age=86400", "created_at": "2026-09-25T12:00:00.000Z" },
      { "prefix": "tmp/", "delete_after_days": 7, "created_at": "2026-09-25T12:00:00.000Z", "active_from": "2026-09-26T12:00:00.000Z" }
    ]
  }
}

Errors

Errors about one rule include its prefix in the response.

Code	HTTP	When
`INVALID_BODY`	400	The body is not a JSON object.
`NOTHING_TO_UPDATE`	400	The body has no `rules`.
`INVALID_RULES`	400	`rules` is not an array of objects.
`TOO_MANY_RULES`	400	More than 20 rules on Enterprise.
`INVALID_RULE_PREFIX` / `DUPLICATE_RULE_PREFIX`	400	A prefix is malformed or repeated.
`INVALID_RULE_PRIVATE` / `INVALID_RULE_EXPIRE` / `INVALID_RULE_MAX_SIZE` / `INVALID_RULE_EXTENSIONS` / `INVALID_RULE_CACHE_CONTROL` / `INVALID_RULE_DELETE_AFTER`	400	A rule field is invalid.
`PERMISSION_DENIED`	401	The account has no active paid plan.
`UPGRADE_REQUIRED`	403	More rules than the plan allows, or a rule uses an option that needs a higher plan. The `message` says the limit or the plan.
`RATE_LIMITED`	429	More than 10 requests in a minute.

curl --request PUT \
  --url 'https://blob.squarecloud.app/v1/account/settings' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "rules": [
      { "prefix": "invoices", "private": true, "extensions": ["pdf"] },
      { "prefix": "avatars", "max_size": 2097152, "extensions": ["png", "jpg", "webp"], "cache_control": "max-age=86400" },
      { "prefix": "tmp", "delete_after_days": 7 }
    ]
  }'

{
  "status": "success",
  "response": {
    "rules": [
      { "prefix": "invoices/", "private": true, "extensions": ["pdf"], "created_at": "2026-09-25T12:00:00.000Z" },
      { "prefix": "avatars/", "max_size": 2097152, "extensions": ["png", "jpg", "webp"], "cache_control": "max-age=86400", "created_at": "2026-09-25T12:00:00.000Z" },
      { "prefix": "tmp/", "delete_after_days": 7, "created_at": "2026-09-25T12:00:00.000Z", "active_from": "2026-09-26T12:00:00.000Z" }
    ]
  }
}

Getting Started

Objects

Chunked Uploads

Account

Share Links

S3

Rate limits

Response

Errors

​Rate limits

​Response

​Errors

Rate limits

Response

Errors