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

> Cambia la visibilidad, la expiración, la caché, la disposition o los metadatos de hasta 50 archivos por solicitud con PATCH /v1/objects, sin volver a subirlos.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  La clave de API de tu cuenta. Puedes encontrarla en la [configuración de tu cuenta](https://squarecloud.app/es/account/security).
</ParamField>

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.

<Warning>
  **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.
</Warning>

<ParamField body="object" type="string">
  El id de un archivo. Envía `object` u `objects`.
</ParamField>

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

<ParamField body="private" type="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](/es/blob-reference/links-and-sharing).
</ParamField>

<ParamField body="expire" type="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.
</ParamField>

<ParamField body="cache_control" type="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.
</ParamField>

<ParamField body="disposition" type="string | null">
  `inline` o `attachment` (descarga con el nombre de archivo original). `null` elimina la cabecera.
</ParamField>

<ParamField body="metadata" type="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.
</ParamField>

### 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](/es/blob-reference/endpoint/copy) (`move: true`) y luego actualízalo.

### Límites de tasa

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

### Respuesta

<ResponseField name="status" type="string">
  "success" si tuvo éxito, "error" si no.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Alternar objeto">
    <ResponseField name="results" type="array">
      Una entrada por archivo, en el orden enviado.

      <Expandable title="Alternar objeto">
        <ResponseField name="object" type="string">
          El id tal como se envió en la solicitud.
        </ResponseField>

        <ResponseField name="ok" type="boolean">
          Si se aplicaron todos los cambios a este archivo.
        </ResponseField>

        <ResponseField name="code" type="string">
          Solo cuando `ok` es `false`: por qué falló este archivo.
        </ResponseField>

        <ResponseField name="changed" type="boolean">
          Si el id cambió.
        </ResponseField>

        <ResponseField name="id" type="string">
          El id actual del archivo. Guárdalo.
        </ResponseField>

        <ResponseField name="private" type="boolean">
          Si el archivo es privado.
        </ResponseField>

        <ResponseField name="url" type="string | null">
          La URL pública, o `null` para los archivos privados.
        </ResponseField>

        <ResponseField name="size" type="number">
          El tamaño del archivo, en bytes.
        </ResponseField>

        <ResponseField name="expires_at" type="ISO 8601 | null">
          Cuándo se eliminará el archivo, o `null` cuando no expira.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Hacer 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 Cambiar cabeceras 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 Hacer 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 Con un fallo 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>

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