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

requerido

La clave de API de tu cuenta. Puedes encontrarla en la configuración de tu cuenta.

Object Update cambia archivos ya almacenados sin volver a subirlos: hacerlos privados o públicos, definir o quitar una expiración, y cambiar la caché, la disposition o los metadatos. Acepta un archivo o hasta 50 por solicitud, y todos reciben los mismos cambios. Requiere el scope blob:write. Los cambios se aplican en el orden de los campos de abajo, cada uno sobre el resultado del anterior. Una vez que el cuerpo es válido, la ruta siempre responde 200, con un resultado por archivo.

Cambiar private o expire cambia el id del archivo (y su URL, en los archivos públicos). Guarda el nuevo id de cada resultado. Los enlaces compartidos y los enlaces temporales al id antiguo dejan de funcionar. Los demás campos conservan el id.

string

El id de un archivo. Envía object u objects.

string[]

Hasta 50 ids.

boolean

true hace privado el archivo: la copia pública se elimina antes de que la solicitud responda, y la CDN la descarta en unos 60 segundos. false lo publica, lo que requiere un plan de pago. Consulta Enlaces y uso compartido.

string | null

Una nueva expiración contada desde ahora (30d, 6h, 30), o null para conservar el archivo para siempre. Requiere un plan de pago, y las expiraciones de menos de 7 días requieren Enterprise.

string | null

immutable, max-age=N (de 60 a 31536000) o no-cache (solo Enterprise). null elimina la cabecera y se aplica el valor por defecto de la CDN.

string | null

inline o attachment (descarga con el nombre de archivo original). null elimina la cabecera.

object | null

Claves que definir o cambiar. Una clave con valor null se elimina, y metadata: null las elimina todas. Hasta 5 claves y 512 bytes tras el cambio. Definir claves requiere Pro o Enterprise; eliminarlas siempre está permitido.

Archivos heredados

Los archivos heredados, subidos antes de la actualización de septiembre de 2026 (ids sin pub/ ni prv/), pueden hacerse privados y recibir una nueva expiración: ambas cosas los mueven al nuevo almacenamiento, con un nuevo id. Sus cabeceras (cache_control, disposition, metadata) no pueden cambiar en el mismo lugar y responden OBJECT_IS_LEGACY: mueve primero el archivo con Object Copy (move: true) y luego actualízalo.

Límites de tasa

50 archivos cada 10 segundos, contados por archivo: un lote completo de 50 usa toda la ventana (RATE_LIMITED, 429).

Respuesta

string

“success” si tuvo éxito, “error” si no.

object

Mostrar Alternar objeto

array

Una entrada por archivo, en el orden enviado.

Mostrar Alternar objeto

string

El id tal como se envió en la solicitud.

boolean

Si se aplicaron todos los cambios a este archivo.

string

Solo cuando ok es false: por qué falló este archivo.

boolean

Si el id cambió.

string

El id actual del archivo. Guárdalo.

boolean

Si el archivo es privado.

string | null

La URL pública, o null para los archivos privados.

number

El tamaño del archivo, en bytes.

ISO 8601 | null

Cuándo se eliminará el archivo, o null cuando no expira.

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

Errores

Errores de toda la solicitud:

Código	HTTP	Cuándo
`INVALID_BODY` / `INVALID_OBJECT`	400	El cuerpo no es un objeto JSON, o un id falta, está mal formado o no es tuyo.
`TOO_MANY_OBJECTS`	400	Más de 50 ids.
`NOTHING_TO_UPDATE`	400	No se envió ningún campo que cambiar.
`INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_METADATA`	400	Un campo tiene un valor no válido.
`UPGRADE_REQUIRED`	403	Un valor requiere un plan superior. El `message` indica cuál.
`RATE_LIMITED`	429	Más de 50 archivos en 10 segundos.

Códigos de un archivo concreto, en su resultado:

Código	Cuándo
`OBJECT_NOT_FOUND`	El archivo no existe.
`PERMISSION_DENIED`	Publicar o cambiar la expiración requiere un plan de pago activo.
`OBJECT_IS_LEGACY`	Cambio de cabeceras en un archivo heredado. Muévelo primero.
`INVALID_OBJECT_METADATA`	El archivo superaría 5 claves o 512 bytes de metadatos.
`VISIBILITY_CHANGE_FAILED`	No se pudo eliminar la copia pública: el archivo sigue siendo público. Reintenta.
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	El almacenamiento no está disponible temporalmente. Reintenta.
`UPDATE_FAILED`	El cambio falló. Reintenta.

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

Primeros Pasos

Objetos

Subida en Partes

Cuenta

Enlaces Compartidos

S3

Archivos heredados

Límites de tasa

Respuesta

Errores

​Archivos heredados

​Límites de tasa

​Respuesta

​Errores

Archivos heredados

Límites de tasa

Respuesta

Errores