Blob Object Download

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

requerido

La clave de API de tu cuenta. Puedes encontrarla en la configuración de tu cuenta.

Object Download te da un enlace para leer un archivo. Para un archivo privado firma un enlace temporal, válido de 60 segundos a 24 horas, que funciona sin ninguna credencial. Para un archivo público devuelve la URL pública. Por defecto responde con una redirección 302, así que puedes apuntar un navegador o curl -L directamente a él; redirect=false devuelve el enlace como JSON. Requiere el scope blob:read. Los enlaces temporales (https://files.squarecloud.dev/d/...) no se pueden revocar, admiten Range y solicitudes condicionales, y dejan de funcionar cuando expiran o cuando el archivo se elimina, se mueve o cambia de visibilidad. Para enlaces que puedas revocar, limitar o proteger con contraseña, usa un enlace compartido. Consulta Enlaces y uso compartido.

string

requerido

El id del archivo.

number

predeterminado:"3600"

Cuánto dura el enlace temporal, de 60 a 86400 segundos (24 horas).

boolean

predeterminado:"true"

false devuelve el enlace como JSON en lugar de redirigir.

string

inline (abrir en el navegador) o attachment (descargar). Definirlo siempre produce un enlace temporal, incluso para archivos públicos.

string

El nombre con el que el navegador guarda el archivo. Implica attachment salvo que disposition indique otra cosa, y siempre produce un enlace temporal.

Límites de tasa

60 solicitudes por minuto a esta ruta (RATE_LIMITED, 429).
Cada enlace temporal acepta 60 solicitudes por minuto por IP, además de un límite general para todos los enlaces de tu cuenta. Por encima de eso, el enlace responde 429 en texto plano. Para entregar un archivo a muchas personas, hazlo público: los archivos públicos los sirve la CDN, sin este límite. Un enlace expirado o no válido responde 404.

Respuesta

Con redirect=true (por defecto): 302 con el enlace en Location y Cache-Control: no-store. Con redirect=false:

string

“success” si tuvo éxito, “error” si no.

object

Mostrar Alternar objeto

string

El enlace: un enlace temporal en files.squarecloud.dev, o la URL pública.

ISO 8601 | null

Cuándo expira el enlace temporal, o null para una URL pública.

boolean

Si el archivo es privado.

number

El tamaño del archivo, en bytes.

string

El Content-Type con el que se sirve el archivo.

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

Errores

Código	HTTP	Cuándo
`INVALID_OBJECT`	400	`object` falta, está mal formado o no es tuyo.
`INVALID_DOWNLOAD_EXPIRES`	400	`expires` no es un entero de 60 a 86400.
`INVALID_OBJECT_DISPOSITION`	400	`disposition` no es `inline` ni `attachment`.
`INVALID_FILENAME`	400	`filename` queda vacío tras eliminar los caracteres no válidos.
`OBJECT_NOT_FOUND`	404	El archivo no existe.
`RATE_LIMITED`	429	Más de 60 solicitudes en un 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"
  }
}

Primeros Pasos

Objetos

Subida en Partes

Cuenta

Enlaces Compartidos

S3

Límites de tasa

Respuesta

Errores

​Límites de tasa

​Respuesta

​Errores

Límites de tasa

Respuesta

Errores