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

requis

La clé d’API de votre compte. Vous pouvez la trouver dans les paramètres de votre compte.

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.

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.

string

L’id d’un fichier. Envoyez object ou objects.

string[]

Jusqu’à 50 id.

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.

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.

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.

string | null

inline ou attachment (téléchargement avec le nom de fichier d’origine). null supprime l’en-tête.

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.

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 (move: true), puis mettez-le à jour.

Limites de débit

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

Réponse

string

“success” en cas de succès, “error” sinon.

object

Afficher Afficher l'objet

array

Une entrée par fichier, dans l’ordre d’envoi.

Afficher Afficher l'objet

string

L’id tel qu’envoyé dans la requête.

boolean

Indique si toutes les modifications ont été appliquées à ce fichier.

string

Uniquement lorsque ok vaut false : la raison de l’échec pour ce fichier.

boolean

Indique si l’id a changé.

string

L’id actuel du fichier. Enregistrez-le.

boolean

Indique si le fichier est privé.

string | null

L’URL publique, ou null pour les fichiers privés.

number

La taille du fichier, en octets.

ISO 8601 | null

Date à laquelle le fichier sera supprimé, ou null s’il n’expire pas.

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

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.

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

Premiers Pas

Objets

Upload par Morceaux

Compte

Liens de Partage

S3

Fichiers hérités

Limites de débit

Réponse

Erreurs

​Fichiers hérités

​Limites de débit

​Réponse

​Erreurs

Fichiers hérités

Limites de débit

Réponse

Erreurs