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

# Blob Object Update

> Modifica visibilità, scadenza, cache, disposition o metadati di fino a 50 file per richiesta con PATCH /v1/objects, senza caricarli di nuovo.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  La chiave API del tuo account. Puoi trovarla nelle [impostazioni del tuo account](https://squarecloud.app/it/account/security).
</ParamField>

Object Update modifica file già archiviati, senza caricarli di nuovo: rendili privati o pubblici, imposta o rimuovi una scadenza e modifica cache, disposition o metadati. Accetta un file o fino a **50 per richiesta**, che ricevono tutti le stesse modifiche. Richiede lo scope `blob:write`.

Le modifiche vengono applicate nell'ordine dei campi qui sotto, ognuna sul risultato della precedente. Una volta che il corpo è valido, la route risponde sempre `200`, con un risultato per file.

<Warning>
  **Modificare `private` o `expire` cambia l'id del file** (e il suo URL, per i file pubblici). Salva il nuovo `id` di ogni risultato. I link di condivisione e i link temporanei al vecchio id smettono di funzionare. Gli altri campi mantengono l'id.
</Warning>

<ParamField body="object" type="string">
  L'id di un file. Invia `object` oppure `objects`.
</ParamField>

<ParamField body="objects" type="string[]">
  Fino a 50 id.
</ParamField>

<ParamField body="private" type="boolean">
  `true` rende il file privato: la copia pubblica viene rimossa prima che la richiesta risponda e la CDN la elimina in circa 60 secondi. `false` lo pubblica, il che richiede un piano a pagamento. Vedi [Link e condivisione](/it/blob-reference/links-and-sharing).
</ParamField>

<ParamField body="expire" type="string | null">
  Una nuova scadenza calcolata da adesso (`30d`, `6h`, `30`), oppure `null` per conservare il file per sempre. Richiede un piano a pagamento, e le scadenze sotto i 7 giorni richiedono Enterprise.
</ParamField>

<ParamField body="cache_control" type="string | null">
  `immutable`, `max-age=N` (da 60 a 31536000) oppure `no-cache` (solo Enterprise). `null` rimuove l'header e si applica il valore predefinito della CDN.
</ParamField>

<ParamField body="disposition" type="string | null">
  `inline` oppure `attachment` (download con il nome file originale). `null` rimuove l'header.
</ParamField>

<ParamField body="metadata" type="object | null">
  Chiavi da impostare o modificare. Una chiave con valore `null` viene rimossa, e `metadata: null` le rimuove tutte. Fino a 5 chiavi e 512 byte dopo la modifica. Impostare chiavi richiede Pro o Enterprise; rimuoverle è sempre consentito.
</ParamField>

### File legacy

I file legacy, caricati prima dell'aggiornamento di settembre 2026 (id senza `pub/` o `prv/`), possono essere resi privati e possono ricevere una nuova scadenza: entrambe le operazioni li spostano nel nuovo storage, con un nuovo id. I loro header (`cache_control`, `disposition`, `metadata`) non possono cambiare sul posto e rispondono `OBJECT_IS_LEGACY`: sposta prima il file con [Object Copy](/it/blob-reference/endpoint/copy) (`move: true`), poi aggiornalo.

### Limiti di frequenza

<Note>50 file ogni 10 secondi, conteggiati per file: un blocco completo di 50 usa l'intera finestra (`RATE_LIMITED`, 429).</Note>

### Risposta

<ResponseField name="status" type="string">
  "success" in caso di successo, "error" in caso contrario.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Mostra oggetto">
    <ResponseField name="results" type="array">
      Una voce per file, nell'ordine di invio.

      <Expandable title="Mostra oggetto">
        <ResponseField name="object" type="string">
          L'id così come inviato nella richiesta.
        </ResponseField>

        <ResponseField name="ok" type="boolean">
          Se tutte le modifiche sono state applicate a questo file.
        </ResponseField>

        <ResponseField name="code" type="string">
          Solo quando `ok` è `false`: il motivo per cui questo file non è riuscito.
        </ResponseField>

        <ResponseField name="changed" type="boolean">
          Se l'id è cambiato.
        </ResponseField>

        <ResponseField name="id" type="string">
          L'id attuale del file. Salvalo.
        </ResponseField>

        <ResponseField name="private" type="boolean">
          Se il file è privato.
        </ResponseField>

        <ResponseField name="url" type="string | null">
          L'URL pubblico, oppure `null` per i file privati.
        </ResponseField>

        <ResponseField name="size" type="number">
          La dimensione del file, in byte.
        </ResponseField>

        <ResponseField name="expires_at" type="ISO 8601 | null">
          Quando il file verrà eliminato, oppure `null` se non scade.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Rendi privato 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 Modifica gli header 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 Rendi privato 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 Con un errore 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>

### Errori

Errori dell'intera richiesta:

| Codice                                                                                                                                         | HTTP | Quando                                                                                |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------- |
| `INVALID_BODY` / `INVALID_OBJECT`                                                                                                              | 400  | Il corpo non è un oggetto JSON, oppure un id manca, è malformato o non ti appartiene. |
| `TOO_MANY_OBJECTS`                                                                                                                             | 400  | Più di 50 id.                                                                         |
| `NOTHING_TO_UPDATE`                                                                                                                            | 400  | Non è stato inviato alcun campo da modificare.                                        |
| `INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_METADATA` | 400  | Un campo ha un valore non valido.                                                     |
| `UPGRADE_REQUIRED`                                                                                                                             | 403  | Un valore richiede un piano superiore. Il `message` indica quale.                     |
| `RATE_LIMITED`                                                                                                                                 | 429  | Più di 50 file in 10 secondi.                                                         |

Codici di un singolo file, nel suo risultato:

| Codice                                                       | Quando                                                                                     |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `OBJECT_NOT_FOUND`                                           | Il file non esiste.                                                                        |
| `PERMISSION_DENIED`                                          | Pubblicare o modificare la scadenza richiede un piano a pagamento attivo.                  |
| `OBJECT_IS_LEGACY`                                           | Modifica degli header su un file legacy. Spostalo prima.                                   |
| `INVALID_OBJECT_METADATA`                                    | Il file supererebbe 5 chiavi o 512 byte di metadati.                                       |
| `VISIBILITY_CHANGE_FAILED`                                   | Non è stato possibile rimuovere la copia pubblica: il file **è ancora pubblico**. Riprova. |
| `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | Lo storage è temporaneamente non disponibile. Riprova.                                     |
| `UPDATE_FAILED`                                              | La modifica non è riuscita. Riprova.                                                       |