Download de Objeto Blob

GET

objects

download

curl --request GET \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf&expires=600&redirect=false' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  object: 'prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf',
  expires: '600',
  filename: 'invoice-september.pdf',
  redirect: 'false',
});

const res = await fetch(`https://blob.squarecloud.app/v1/objects/download?${params}`, {
  headers: { Authorization: 'YOUR_API_KEY' },
});
const { response } = await res.json();
// hand response.url to the user; it works without credentials for 10 minutes

{
  "status": "success",
  "response": {
    "url": "https://files.squarecloud.dev/d/Rb7nKq2WvX9sLp4TzYc1Hm8JdF0gUe6AoNiQ3tVwBk5Sy.Pj3Lx9Qe2Rw7Ty4Uo",
    "expires_at": "2026-09-25T12:10:00.000Z",
    "private": true,
    "size": 88412,
    "content_type": "application/pdf"
  }
}

string

obrigatório

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

O Download de Objeto te dá um link para ler um arquivo. Para um arquivo privado, ele assina um link temporário, válido de 60 segundos a 24 horas, que funciona sem nenhuma credencial. Para um arquivo público, ele retorna a URL pública. Por padrão ele responde com um redirecionamento 302, então você pode apontar um navegador ou curl -L diretamente para ele; redirect=false retorna o link como JSON. Exige o escopo blob:read. Links temporários (https://files.squarecloud.dev/d/...) não podem ser revogados, suportam Range e requisições condicionais, e deixam de funcionar quando expiram ou quando o arquivo é excluído, movido ou muda de visibilidade. Para links que você pode revogar, limitar ou proteger com senha, use um link de compartilhamento. Veja Links e compartilhamento.

string

obrigatório

O id do arquivo.

number

padrão:"3600"

Por quanto tempo o link temporário dura, de 60 a 86400 segundos (24 horas).

boolean

padrão:"true"

false retorna o link como JSON em vez de redirecionar.

string

inline (abre no navegador) ou attachment (download). Defini-lo sempre gera um link temporário, mesmo para arquivos públicos.

string

O nome com que o navegador salva o arquivo. Implica attachment, a menos que disposition diga o contrário, e sempre gera um link temporário.

Limites de taxa

60 requisições por minuto nesta rota (RATE_LIMITED, 429).
Cada link temporário aceita 60 requisições por minuto por IP, além de um limite geral para todos os links da sua conta. Acima disso o link responde 429 em texto simples. Para entregar um arquivo a muitas pessoas, torne-o público: arquivos públicos são servidos pela CDN, sem esse limite. Um link expirado ou inválido responde 404.

Resposta

Com redirect=true (padrão): 302 com o link em Location e Cache-Control: no-store. Com redirect=false:

string

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

object

Mostrar Alternar objeto

string

O link: um link temporário em files.squarecloud.dev, ou a URL pública.

ISO 8601 | null

Quando o link temporário expira, ou null para uma URL pública.

boolean

Se o arquivo é privado.

number

O tamanho do arquivo, em bytes.

string

O Content-Type com que o arquivo é servido.

curl --request GET \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf&expires=600&redirect=false' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  object: 'prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf',
  expires: '600',
  filename: 'invoice-september.pdf',
  redirect: 'false',
});

const res = await fetch(`https://blob.squarecloud.app/v1/objects/download?${params}`, {
  headers: { Authorization: 'YOUR_API_KEY' },
});
const { response } = await res.json();
// hand response.url to the user; it works without credentials for 10 minutes

{
  "status": "success",
  "response": {
    "url": "https://files.squarecloud.dev/d/Rb7nKq2WvX9sLp4TzYc1Hm8JdF0gUe6AoNiQ3tVwBk5Sy.Pj3Lx9Qe2Rw7Ty4Uo",
    "expires_at": "2026-09-25T12:10:00.000Z",
    "private": true,
    "size": 88412,
    "content_type": "application/pdf"
  }
}

Erros

Código	HTTP	Quando
`INVALID_OBJECT`	400	`object` está ausente, malformado ou não é seu.
`INVALID_DOWNLOAD_EXPIRES`	400	`expires` não é um inteiro de 60 a 86400.
`INVALID_OBJECT_DISPOSITION`	400	`disposition` não é `inline` nem `attachment`.
`INVALID_FILENAME`	400	`filename` fica vazio depois de remover os caracteres inválidos.
`OBJECT_NOT_FOUND`	404	O arquivo não existe.
`RATE_LIMITED`	429	Mais de 60 requisições em um minuto.

curl --request GET \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf&expires=600&redirect=false' \
  --header 'Authorization: YOUR_API_KEY'

const params = new URLSearchParams({
  object: 'prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf',
  expires: '600',
  filename: 'invoice-september.pdf',
  redirect: 'false',
});

const res = await fetch(`https://blob.squarecloud.app/v1/objects/download?${params}`, {
  headers: { Authorization: 'YOUR_API_KEY' },
});
const { response } = await res.json();
// hand response.url to the user; it works without credentials for 10 minutes

{
  "status": "success",
  "response": {
    "url": "https://files.squarecloud.dev/d/Rb7nKq2WvX9sLp4TzYc1Hm8JdF0gUe6AoNiQ3tVwBk5Sy.Pj3Lx9Qe2Rw7Ty4Uo",
    "expires_at": "2026-09-25T12:10:00.000Z",
    "private": true,
    "size": 88412,
    "content_type": "application/pdf"
  }
}

Primeiros Passos

Objetos

Uploads em Partes

Conta

Links de Compartilhamento

S3

Download de Objeto Blob

Limites de taxa

Resposta

Erros

​Limites de taxa

​Resposta

​Erros

Limites de taxa

Resposta

Erros