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

> Modifiez la visibilité, l'expiration, le cache, la disposition ou les métadonnées de jusqu'à 50 fichiers par requête avec PATCH /v1/objects, sans les renvoyer.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  La clé d'API de votre compte. Vous pouvez la trouver dans les [paramètres de votre compte](https://squarecloud.app/fr/account/security).
</ParamField>

Object Update modifie des fichiers déjà stockés, sans les renvoyer : les rendre privés ou publics, définir ou supprimer une expiration, et modifier le cache, la disposition ou les métadonnées. Il accepte un fichier ou jusqu'à **50 par requête**, qui reçoivent tous les mêmes modifications. Nécessite le scope `blob:write`.

Les modifications sont appliquées dans l'ordre des champs ci-dessous, chacune sur le résultat de la précédente. Une fois le corps valide, la route répond toujours `200`, avec un résultat par fichier.

<Warning>
  **Modifier `private` ou `expire` change l'id du fichier** (et son URL, pour les fichiers publics). Enregistrez le nouvel `id` de chaque résultat. Les liens de partage et les liens temporaires vers l'ancien id cessent de fonctionner. Les autres champs conservent l'id.
</Warning>

<ParamField body="object" type="string">
  L'id d'un fichier. Envoyez `object` ou `objects`.
</ParamField>

<ParamField body="objects" type="string[]">
  Jusqu'à 50 id.
</ParamField>

<ParamField body="private" type="boolean">
  `true` rend le fichier privé : la copie publique est supprimée avant que la requête ne réponde, et le CDN l'abandonne en environ 60 secondes. `false` le publie, ce qui nécessite un plan payant. Voir [Liens et partage](/fr/blob-reference/links-and-sharing).
</ParamField>

<ParamField body="expire" type="string | null">
  Une nouvelle expiration comptée à partir de maintenant (`30d`, `6h`, `30`), ou `null` pour conserver le fichier indéfiniment. Nécessite un plan payant, et les expirations inférieures à 7 jours nécessitent Enterprise.
</ParamField>

<ParamField body="cache_control" type="string | null">
  `immutable`, `max-age=N` (60 à 31536000) ou `no-cache` (Enterprise uniquement). `null` supprime l'en-tête et la valeur par défaut du CDN s'applique.
</ParamField>

<ParamField body="disposition" type="string | null">
  `inline` ou `attachment` (téléchargement avec le nom de fichier d'origine). `null` supprime l'en-tête.
</ParamField>

<ParamField body="metadata" type="object | null">
  Les clés à définir ou à modifier. Une clé avec une valeur `null` est supprimée, et `metadata: null` les supprime toutes. Jusqu'à 5 clés et 512 octets après la modification. Définir des clés nécessite Pro ou Enterprise ; la suppression est toujours autorisée.
</ParamField>

### Fichiers hérités

Les fichiers hérités, envoyés avant la mise à jour de septembre 2026 (id sans `pub/` ni `prv/`), peuvent être rendus privés et recevoir une nouvelle expiration : les deux opérations les déplacent vers le nouveau stockage, avec un nouvel id. Leurs en-têtes (`cache_control`, `disposition`, `metadata`) ne peuvent pas être modifiés sur place et répondent `OBJECT_IS_LEGACY` : déplacez d'abord le fichier avec [Copie d'objet](/fr/blob-reference/endpoint/copy) (`move: true`), puis mettez-le à jour.

### Limites de débit

<Note>50 fichiers par 10 secondes, comptés par fichier : un lot complet de 50 utilise toute la fenêtre (`RATE_LIMITED`, 429).</Note>

### Réponse

<ResponseField name="status" type="string">
  "success" en cas de succès, "error" sinon.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Afficher l'objet">
    <ResponseField name="results" type="array">
      Une entrée par fichier, dans l'ordre d'envoi.

      <Expandable title="Afficher l'objet">
        <ResponseField name="object" type="string">
          L'id tel qu'envoyé dans la requête.
        </ResponseField>

        <ResponseField name="ok" type="boolean">
          Indique si toutes les modifications ont été appliquées à ce fichier.
        </ResponseField>

        <ResponseField name="code" type="string">
          Uniquement lorsque `ok` vaut `false` : la raison de l'échec pour ce fichier.
        </ResponseField>

        <ResponseField name="changed" type="boolean">
          Indique si l'id a changé.
        </ResponseField>

        <ResponseField name="id" type="string">
          L'id actuel du fichier. Enregistrez-le.
        </ResponseField>

        <ResponseField name="private" type="boolean">
          Indique si le fichier est privé.
        </ResponseField>

        <ResponseField name="url" type="string | null">
          L'URL publique, ou `null` pour les fichiers privés.
        </ResponseField>

        <ResponseField name="size" type="number">
          La taille du fichier, en octets.
        </ResponseField>

        <ResponseField name="expires_at" type="ISO 8601 | null">
          Date à laquelle le fichier sera supprimé, ou `null` s'il n'expire pas.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Rendre privé 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 Modifier les en-têtes 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 Rendre privé 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 Avec un échec 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>

### Erreurs

Erreurs de la requête entière :

| Code                                                                                                                                           | HTTP | Quand                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------- |
| `INVALID_BODY` / `INVALID_OBJECT`                                                                                                              | 400  | Le corps n'est pas un objet JSON, ou un id est absent, mal formé ou ne vous appartient pas. |
| `TOO_MANY_OBJECTS`                                                                                                                             | 400  | Plus de 50 id.                                                                              |
| `NOTHING_TO_UPDATE`                                                                                                                            | 400  | Aucun champ à modifier n'a été envoyé.                                                      |
| `INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_METADATA` | 400  | Un champ a une valeur invalide.                                                             |
| `UPGRADE_REQUIRED`                                                                                                                             | 403  | Une valeur nécessite un plan supérieur. Le `message` indique lequel.                        |
| `RATE_LIMITED`                                                                                                                                 | 429  | Plus de 50 fichiers en 10 secondes.                                                         |

Codes propres à un fichier, dans son résultat :

| Code                                                         | Quand                                                                                        |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| `OBJECT_NOT_FOUND`                                           | Le fichier n'existe pas.                                                                     |
| `PERMISSION_DENIED`                                          | Publier ou modifier l'expiration nécessite un plan payant actif.                             |
| `OBJECT_IS_LEGACY`                                           | Modification d'en-tête sur un fichier hérité. Déplacez-le d'abord.                           |
| `INVALID_OBJECT_METADATA`                                    | Le fichier dépasserait 5 clés ou 512 octets de métadonnées.                                  |
| `VISIBILITY_CHANGE_FAILED`                                   | La copie publique n'a pas pu être supprimée : le fichier **est toujours public**. Réessayez. |
| `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | Le stockage est temporairement indisponible. Réessayez.                                      |
| `UPDATE_FAILED`                                              | La modification a échoué. Réessayez.                                                         |