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

obbligatorio

La chiave API del tuo account. Puoi trovarla nelle impostazioni del tuo account.

Object Download ti fornisce un link per leggere un file. Per un file privato firma un link temporaneo, valido da 60 secondi a 24 ore, che funziona senza alcuna credenziale. Per un file pubblico restituisce l’URL pubblico. Per impostazione predefinita risponde con un redirect 302, così puoi puntarci direttamente un browser o curl -L; redirect=false restituisce il link come JSON. Richiede lo scope blob:read. I link temporanei (https://files.squarecloud.dev/d/...) non possono essere revocati, supportano Range e le richieste condizionali, e smettono di funzionare quando scadono o quando il file viene eliminato, spostato o cambia visibilità. Per link che puoi revocare, limitare o proteggere con una password, usa un link di condivisione. Vedi Link e condivisione.

string

obbligatorio

L’id del file.

number

predefinito:"3600"

Quanto dura il link temporaneo, da 60 a 86400 secondi (24 ore).

boolean

predefinito:"true"

false restituisce il link come JSON invece di fare il redirect.

string

inline (apri nel browser) oppure attachment (download). Impostarlo produce sempre un link temporaneo, anche per i file pubblici.

string

Il nome con cui il browser salva il file. Implica attachment a meno che disposition non indichi altro, e produce sempre un link temporaneo.

Limiti di frequenza

60 richieste al minuto a questa route (RATE_LIMITED, 429).
Ogni link temporaneo accetta 60 richieste al minuto per IP, oltre a un limite complessivo per tutti i link del tuo account. Oltre questa soglia il link risponde 429 in testo semplice. Per consegnare un file a molte persone, rendilo pubblico: i file pubblici sono serviti dalla CDN, senza questo limite. Un link scaduto o non valido risponde 404.

Risposta

Con redirect=true (predefinito): 302 con il link in Location e Cache-Control: no-store. Con redirect=false:

string

“success” in caso di successo, “error” in caso contrario.

object

Mostra Mostra oggetto

string

Il link: un link temporaneo su files.squarecloud.dev, oppure l’URL pubblico.

ISO 8601 | null

Quando scade il link temporaneo, oppure null per un URL pubblico.

boolean

Se il file è privato.

number

La dimensione del file, in byte.

string

Il Content-Type con cui il file viene servito.

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

Errori

Codice	HTTP	Quando
`INVALID_OBJECT`	400	`object` manca, è malformato o non ti appartiene.
`INVALID_DOWNLOAD_EXPIRES`	400	`expires` non è un intero da 60 a 86400.
`INVALID_OBJECT_DISPOSITION`	400	`disposition` non è `inline` o `attachment`.
`INVALID_FILENAME`	400	`filename` è vuoto dopo la rimozione dei caratteri non validi.
`OBJECT_NOT_FOUND`	404	Il file non esiste.
`RATE_LIMITED`	429	Più di 60 richieste in 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"
  }
}

Primi Passi

Oggetti

Upload a Blocchi

Account

Link di Condivisione

S3

Limiti di frequenza

Risposta

Errori

​Limiti di frequenza

​Risposta

​Errori

Limiti di frequenza

Risposta

Errori