Set prefix rules

Set rules per prefix with PUT /v1/account/settings: default visibility, expiry and cache, size and file type limits, and automatic deletion after N days.

PUT /v1/account/settings

cURL

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

Authorization · 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 an active 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.

Parameters

rules · object[] · required

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

Show properties

prefix · string · required

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

private · boolean

Default visibility of new files.

expire · string

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

max_size · number

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

extensions · string[]

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

cache_control · string

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

delete_after_days · 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

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 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.

Related

• Blob SDK: blob.rules.set()