> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Definir regras por prefixo

> Defina regras por prefixo com PUT /v1/account/settings: visibilidade, expiração e cache padrão, limites de tamanho e de tipo, e exclusão automática após N dias.

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

O Atualizar Configurações salva as suas regras, cada uma aplicada aos arquivos sob um prefixo. Uma regra define padrões e limites uma única vez, para todo upload sob ela, venha ele do seu backend, de um [token de upload](/pt-br/blob-reference/endpoint/upload-tokens) ou do dashboard. Exige o escopo `blob:write` e um plano ativo.

Cada plano permite um número de regras: **5** no Hobby e no Standard, **10** no Pro e **20** no Enterprise. As regras salvas antes de um downgrade continuam valendo, mas o próximo salvamento precisa caber no novo plano.

A requisição **substitui a lista inteira**: envie todas as regras que você quer manter, e `{"rules": []}` remove todas. Quando várias regras correspondem a um arquivo, vence a que tem o **prefixo mais longo**.

* **Padrões** (`private`, `expire`, `cache_control`) se aplicam quando o upload não define o seu próprio valor.
* **Limites** (`max_size`, `extensions`) recusam uploads fora deles com `FILE_TOO_LARGE` ou `FILE_TYPE_NOT_ALLOWED`. Eles se aplicam aos uploads pela API REST, não ao [gateway S3](/pt-br/blob-reference/s3-compatibility).
* **Exclusão automática** (`delete_after_days`) exclui os arquivos um número de dias depois de terem sido gravados. Ela se aplica a todos os arquivos sob o prefixo, incluindo os que já existiam e os gravados pelo S3.

<Warning>
  A exclusão automática só começa **24 horas depois de a regra ser salva** (`active_from` no [Obter Configurações](/pt-br/blob-reference/endpoint/settings-get)), então você tem um dia para perceber um prefixo mais amplo do que o pretendido. Salvar de novo uma regra sem alterações mantém a data original. Depois de ativa, os arquivos excluídos não podem ser recuperados.
</Warning>

## Parâmetros

<ParamField body="rules" type="object[]" required>
  Até 5 regras no Hobby e no Standard, 10 no Pro e 20 no Enterprise.

  <Expandable title="propriedades">
    <ParamField body="prefix" type="string" required>
      O prefixo, com o mesmo padrão do [Envio de Objeto](/pt-br/blob-reference/endpoint/post). É salvo com uma `/` no final, então `invoices` cobre `invoices/...` e não `invoices-old/...`.
    </ParamField>

    <ParamField body="private" type="boolean">
      Visibilidade padrão dos novos arquivos.
    </ParamField>

    <ParamField body="expire" type="string">
      Expiração padrão dos novos arquivos (`30d`, `6h`). Abaixo de 7 dias exige Enterprise.
    </ParamField>

    <ParamField body="max_size" type="number">
      Tamanho máximo do arquivo em bytes, de 512 a 10737418240 (10 GiB).
    </ParamField>

    <ParamField body="extensions" type="string[]">
      Extensões aceitas, de 1 a 50, em minúsculas e sem o ponto (`pdf`, `tar.gz`).
    </ParamField>

    <ParamField body="cache_control" type="string">
      Cache padrão: `immutable`, `max-age=N` ou `no-cache` (somente Enterprise).
    </ParamField>

    <ParamField body="delete_after_days" type="number">
      Exclui os arquivos esta quantidade de dias depois de terem sido gravados, de 1 a 3650. Abaixo de 7 exige Enterprise.
    </ParamField>
  </Expandable>
</ParamField>

<Note>Se o plano mudar para um que não inclui uma opção da regra (por exemplo, uma expiração abaixo de 7 dias depois de sair do Enterprise), os uploads sob esse prefixo são recusados com `UPGRADE_REQUIRED` até a regra ser alterada.</Note>

## Limites de taxa

<Note>10 requisições por minuto (`RATE_LIMITED`, 429).</Note>

## Resposta

Retorna as regras salvas, no mesmo formato do [Obter Configurações](/pt-br/blob-reference/endpoint/settings-get).

<RequestExample>
  ```bash cURL theme={"system"}
  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 }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={"system"}
  {
    "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" }
      ]
    }
  }
  ```
</ResponseExample>

## Erros

Erros sobre uma regra incluem o `prefix` dela na resposta.

| Código | HTTP | Quando |
| - | - | - |
| `INVALID_BODY` | 400 | O corpo não é um objeto JSON. |
| `NOTHING_TO_UPDATE` | 400 | O corpo não tem `rules`. |
| `INVALID_RULES` | 400 | `rules` não é um array de objetos. |
| `TOO_MANY_RULES` | 400 | Mais de 20 regras no Enterprise. |
| `INVALID_RULE_PREFIX` / `DUPLICATE_RULE_PREFIX` | 400 | Um prefixo está malformado ou repetido. |
| `INVALID_RULE_PRIVATE` / `INVALID_RULE_EXPIRE` / `INVALID_RULE_MAX_SIZE` / `INVALID_RULE_EXTENSIONS` / `INVALID_RULE_CACHE_CONTROL` / `INVALID_RULE_DELETE_AFTER` | 400 | Um campo de uma regra é inválido. |
| `PERMISSION_DENIED` | 401 | A conta não tem um plano ativo. |
| `UPGRADE_REQUIRED` | 403 | Mais regras do que o plano permite, ou uma regra usa uma opção que exige um plano superior. A `message` informa o limite ou o plano. |
| `RATE_LIMITED` | 429 | Mais de 10 requisições em um minuto. |

## Relacionados

* SDK do Blob: [`blob.rules.set()`](/pt-br/sdks/blob/rules_and_stats)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.