Blob Object Update

PATCH

objects

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

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

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

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

string

obbligatorio

La chiave API del tuo account. Puoi trovarla nelle impostazioni del tuo account.

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.

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.

string

L’id di un file. Invia object oppure objects.

string[]

Fino a 50 id.

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.

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.

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.

string | null

inline oppure attachment (download con il nome file originale). null rimuove l’header.

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.

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 (move: true), poi aggiornalo.

Limiti di frequenza

50 file ogni 10 secondi, conteggiati per file: un blocco completo di 50 usa l’intera finestra (RATE_LIMITED, 429).

Risposta

string

“success” in caso di successo, “error” in caso contrario.

object

Mostra Mostra oggetto

array

Una voce per file, nell’ordine di invio.

Mostra Mostra oggetto

string

L’id così come inviato nella richiesta.

boolean

Se tutte le modifiche sono state applicate a questo file.

string

Solo quando ok è false: il motivo per cui questo file non è riuscito.

boolean

Se l’id è cambiato.

string

L’id attuale del file. Salvalo.

boolean

Se il file è privato.

string | null

L’URL pubblico, oppure null per i file privati.

number

La dimensione del file, in byte.

ISO 8601 | null

Quando il file verrà eliminato, oppure null se non scade.

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

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

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

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

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.

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

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

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

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

Primi Passi

Oggetti

Upload a Blocchi

Account

Link di Condivisione

S3

File legacy

Limiti di frequenza

Risposta

Errori

​File legacy

​Limiti di frequenza

​Risposta

​Errori

File legacy

Limiti di frequenza

Risposta

Errori