Atualização de Objeto Blob

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

obrigatório

A chave da API para sua conta. Você pode encontrá-la nas configurações da conta.

A Atualização de Objeto altera arquivos já armazenados, sem enviá-los de novo: torne-os privados ou públicos, defina ou remova uma expiração e altere o cache, a disposition ou os metadados. Ela aceita um arquivo ou até 50 por requisição, todos recebendo as mesmas alterações. Exige o escopo blob:write. As alterações são aplicadas na ordem dos campos abaixo, cada uma sobre o resultado da anterior. Com um corpo válido, a rota sempre responde 200, com um resultado por arquivo.

Alterar private ou expire muda o id do arquivo (e a URL, para arquivos públicos). Guarde o novo id de cada resultado. Links de compartilhamento e links temporários para o id antigo deixam de funcionar. Os demais campos mantêm o id.

string

O id de um arquivo. Envie object ou objects.

string[]

Até 50 ids.

boolean

true torna o arquivo privado: a cópia pública é removida antes de a requisição responder, e a CDN a descarta em cerca de 60 segundos. false o publica, o que exige um plano pago. Veja Links e compartilhamento.

string | null

Uma nova expiração contada a partir de agora (30d, 6h, 30), ou null para manter o arquivo para sempre. Exige um plano pago, e expirações abaixo de 7 dias exigem Enterprise.

string | null

immutable, max-age=N (60 a 31536000) ou no-cache (somente Enterprise). null remove o cabeçalho e vale o padrão da CDN.

string | null

inline ou attachment (download com o nome original do arquivo). null remove o cabeçalho.

object | null

Chaves a definir ou alterar. Uma chave com valor null é removida, e metadata: null remove todas. Até 5 chaves e 512 bytes depois da alteração. Definir chaves exige Pro ou Enterprise; remover é sempre permitido.

Arquivos legados

Arquivos legados, enviados antes da atualização de setembro de 2026 (ids sem pub/ ou prv/), podem ser tornados privados e podem receber uma nova expiração: as duas operações os movem para o novo armazenamento, com um novo id. Os cabeçalhos deles (cache_control, disposition, metadata) não podem mudar no próprio arquivo e respondem OBJECT_IS_LEGACY: mova o arquivo primeiro com a Cópia de Objeto (move: true) e depois atualize-o.

Limites de taxa

50 arquivos a cada 10 segundos, contados por arquivo: um lote completo de 50 usa a janela inteira (RATE_LIMITED, 429).

Resposta

string

“success” se bem-sucedida, “error” caso contrário.

object

Mostrar Alternar objeto

array

Uma entrada por arquivo, na ordem em que foram enviados.

Mostrar Alternar objeto

string

O id como enviado na requisição.

boolean

Se todas as alterações foram aplicadas a este arquivo.

string

Apenas quando ok é false: por que este arquivo falhou.

boolean

Se o id mudou.

string

O id atual do arquivo. Guarde-o.

boolean

Se o arquivo é privado.

string | null

A URL pública, ou null para arquivos privados.

number

O tamanho do arquivo, em bytes.

ISO 8601 | null

Quando o arquivo será excluído, ou null quando ele não 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"
      }
    ]
  }
}

Erros

Erros da requisição inteira:

Código	HTTP	Quando
`INVALID_BODY` / `INVALID_OBJECT`	400	O corpo não é um objeto JSON, ou um id está ausente, malformado ou não é seu.
`TOO_MANY_OBJECTS`	400	Mais de 50 ids.
`NOTHING_TO_UPDATE`	400	Nenhum campo a alterar foi enviado.
`INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_METADATA`	400	Um campo tem um valor inválido.
`UPGRADE_REQUIRED`	403	Um valor exige um plano superior. A `message` indica qual.
`RATE_LIMITED`	429	Mais de 50 arquivos em 10 segundos.

Códigos de um único arquivo, no resultado dele:

Código	Quando
`OBJECT_NOT_FOUND`	O arquivo não existe.
`PERMISSION_DENIED`	Publicar ou alterar a expiração exige um plano pago ativo.
`OBJECT_IS_LEGACY`	Alteração de cabeçalho em um arquivo legado. Mova-o primeiro.
`INVALID_OBJECT_METADATA`	O arquivo passaria de 5 chaves ou 512 bytes de metadados.
`VISIBILITY_CHANGE_FAILED`	A cópia pública não pôde ser removida: o arquivo continua público. Tente novamente.
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	O armazenamento está temporariamente indisponível. Tente novamente.
`UPDATE_FAILED`	A alteração falhou. Tente novamente.

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

Primeiros Passos

Objetos

Uploads em Partes

Conta

Links de Compartilhamento

S3

Atualização de Objeto Blob

Arquivos legados

Limites de taxa

Resposta

Erros

​Arquivos legados

​Limites de taxa

​Resposta

​Erros

Arquivos legados

Limites de taxa

Resposta

Erros