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

# Atualização de Objeto Blob

> Altere a visibilidade, a expiração, o cache, a disposition ou os metadados de até 50 arquivos por requisição com PATCH /v1/objects, sem enviá-los de novo.

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

A Atualização de Objeto altera arquivos já armazenados, sem enviá-los de novo: torne-os privados ou públicos, defina ou remova uma expiração e altere o cache, a disposition ou os metadados. Ela aceita um arquivo ou até **50 por requisição**, todos recebendo as mesmas alterações. Exige o escopo `blob:write`.

As alterações são aplicadas na ordem dos campos abaixo, cada uma sobre o resultado da anterior. Com um corpo válido, a rota sempre responde `200`, com um resultado por arquivo.

<Warning>
  **Alterar `private` ou `expire` muda o id do arquivo** (e a URL, para arquivos públicos). Guarde o novo `id` de cada resultado. Links de compartilhamento e links temporários para o id antigo deixam de funcionar. Os demais campos mantêm o id.
</Warning>

<ParamField body="object" type="string">
  O id de um arquivo. Envie `object` ou `objects`.
</ParamField>

<ParamField body="objects" type="string[]">
  Até 50 ids.
</ParamField>

<ParamField body="private" type="boolean">
  `true` torna o arquivo privado: a cópia pública é removida antes de a requisição responder, e a CDN a descarta em cerca de 60 segundos. `false` o publica, o que exige um plano pago. Veja [Links e compartilhamento](/pt-br/blob-reference/links-and-sharing).
</ParamField>

<ParamField body="expire" type="string | null">
  Uma nova expiração contada a partir de agora (`30d`, `6h`, `30`), ou `null` para manter o arquivo para sempre. Exige um plano pago, e expirações abaixo de 7 dias exigem Enterprise.
</ParamField>

<ParamField body="cache_control" type="string | null">
  `immutable`, `max-age=N` (60 a 31536000) ou `no-cache` (somente Enterprise). `null` remove o cabeçalho e vale o padrão da CDN.
</ParamField>

<ParamField body="disposition" type="string | null">
  `inline` ou `attachment` (download com o nome original do arquivo). `null` remove o cabeçalho.
</ParamField>

<ParamField body="metadata" type="object | null">
  Chaves a definir ou alterar. Uma chave com valor `null` é removida, e `metadata: null` remove todas. Até 5 chaves e 512 bytes depois da alteração. Definir chaves exige Pro ou Enterprise; remover é sempre permitido.
</ParamField>

### Arquivos legados

Arquivos legados, enviados antes da atualização de setembro de 2026 (ids sem `pub/` ou `prv/`), podem ser tornados privados e podem receber uma nova expiração: as duas operações os movem para o novo armazenamento, com um novo id. Os cabeçalhos deles (`cache_control`, `disposition`, `metadata`) não podem mudar no próprio arquivo e respondem `OBJECT_IS_LEGACY`: mova o arquivo primeiro com a [Cópia de Objeto](/pt-br/blob-reference/endpoint/copy) (`move: true`) e depois atualize-o.

### Limites de taxa

<Note>50 arquivos a cada 10 segundos, contados por arquivo: um lote completo de 50 usa a janela inteira (`RATE_LIMITED`, 429).</Note>

### Resposta

<ResponseField name="status" type="string">
  "success" se bem-sucedida, "error" caso contrário.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Alternar objeto">
    <ResponseField name="results" type="array">
      Uma entrada por arquivo, na ordem em que foram enviados.

      <Expandable title="Alternar objeto">
        <ResponseField name="object" type="string">
          O id como enviado na requisição.
        </ResponseField>

        <ResponseField name="ok" type="boolean">
          Se todas as alterações foram aplicadas a este arquivo.
        </ResponseField>

        <ResponseField name="code" type="string">
          Apenas quando `ok` é `false`: por que este arquivo falhou.
        </ResponseField>

        <ResponseField name="changed" type="boolean">
          Se o id mudou.
        </ResponseField>

        <ResponseField name="id" type="string">
          O id atual do arquivo. Guarde-o.
        </ResponseField>

        <ResponseField name="private" type="boolean">
          Se o arquivo é privado.
        </ResponseField>

        <ResponseField name="url" type="string | null">
          A URL pública, ou `null` para arquivos privados.
        </ResponseField>

        <ResponseField name="size" type="number">
          O tamanho do arquivo, em bytes.
        </ResponseField>

        <ResponseField name="expires_at" type="ISO 8601 | null">
          Quando o arquivo será excluído, ou `null` quando ele não expira.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Tornar privado theme={null}
  curl --request PATCH \
    --url 'https://blob.squarecloud.app/v1/objects' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "object": "pub/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
      "private": true
    }'
  ```

  ```bash Alterar cabeçalhos theme={null}
  curl --request PATCH \
    --url 'https://blob.squarecloud.app/v1/objects' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "objects": [
        "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "pub/3155597145698959364/images/banner_mugws5c0-1b4f0e9851971998e732078544c96b36.png"
      ],
      "cache_control": "max-age=3600",
      "metadata": { "campaign": "spring", "draft": null }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Tornar privado theme={null}
  {
    "status": "success",
    "response": {
      "results": [
        {
          "object": "pub/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
          "ok": true,
          "changed": true,
          "id": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
          "private": true,
          "url": null,
          "size": 88412,
          "expires_at": null
        }
      ]
    }
  }
  ```

  ```json Com uma falha theme={null}
  {
    "status": "success",
    "response": {
      "results": [
        {
          "object": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
          "ok": true,
          "changed": false,
          "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
          "private": false,
          "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
          "size": 416230,
          "expires_at": null
        },
        {
          "object": "pub/3155597145698959364/images/banner_mugws5c0-1b4f0e9851971998e732078544c96b36.png",
          "ok": false,
          "code": "OBJECT_NOT_FOUND"
        }
      ]
    }
  }
  ```
</ResponseExample>

### Erros

Erros da requisição inteira:

| Código                                                                                                                                         | HTTP | Quando                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------------------------------------- |
| `INVALID_BODY` / `INVALID_OBJECT`                                                                                                              | 400  | O corpo não é um objeto JSON, ou um id está ausente, malformado ou não é seu. |
| `TOO_MANY_OBJECTS`                                                                                                                             | 400  | Mais de 50 ids.                                                               |
| `NOTHING_TO_UPDATE`                                                                                                                            | 400  | Nenhum campo a alterar foi enviado.                                           |
| `INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_METADATA` | 400  | Um campo tem um valor inválido.                                               |
| `UPGRADE_REQUIRED`                                                                                                                             | 403  | Um valor exige um plano superior. A `message` indica qual.                    |
| `RATE_LIMITED`                                                                                                                                 | 429  | Mais de 50 arquivos em 10 segundos.                                           |

Códigos de um único arquivo, no resultado dele:

| Código                                                       | Quando                                                                                  |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `OBJECT_NOT_FOUND`                                           | O arquivo não existe.                                                                   |
| `PERMISSION_DENIED`                                          | Publicar ou alterar a expiração exige um plano pago ativo.                              |
| `OBJECT_IS_LEGACY`                                           | Alteração de cabeçalho em um arquivo legado. Mova-o primeiro.                           |
| `INVALID_OBJECT_METADATA`                                    | O arquivo passaria de 5 chaves ou 512 bytes de metadados.                               |
| `VISIBILITY_CHANGE_FAILED`                                   | A cópia pública não pôde ser removida: o arquivo **continua público**. Tente novamente. |
| `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | O armazenamento está temporariamente indisponível. Tente novamente.                     |
| `UPDATE_FAILED`                                              | A alteração falhou. Tente novamente.                                                    |