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

requis

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

Object Download vous donne un lien pour lire un fichier. Pour un fichier privé, il signe un lien temporaire, valable de 60 secondes à 24 heures, qui fonctionne sans aucun identifiant. Pour un fichier public, il renvoie l’URL publique. Par défaut, il répond avec une redirection 302, vous pouvez donc y pointer directement un navigateur ou curl -L ; redirect=false renvoie le lien en JSON. Nécessite le scope blob:read. Les liens temporaires (https://files.squarecloud.dev/d/...) ne peuvent pas être révoqués, prennent en charge Range et les requêtes conditionnelles, et cessent de fonctionner lorsqu’ils expirent ou lorsque le fichier est supprimé, déplacé ou change de visibilité. Pour des liens que vous pouvez révoquer, limiter ou protéger par un mot de passe, utilisez un lien de partage. Voir Liens et partage.

string

requis

L’id du fichier.

number

défaut:"3600"

Durée de validité du lien temporaire, de 60 à 86400 secondes (24 heures).

boolean

défaut:"true"

false renvoie le lien en JSON au lieu de rediriger.

string

inline (ouvrir dans le navigateur) ou attachment (télécharger). Le définir produit toujours un lien temporaire, même pour les fichiers publics.

string

Le nom sous lequel le navigateur enregistre le fichier. Implique attachment sauf indication contraire de disposition, et produit toujours un lien temporaire.

Limites de débit

60 requêtes par minute vers cette route (RATE_LIMITED, 429).
Chaque lien temporaire accepte 60 requêtes par minute par IP, en plus d’une limite globale pour l’ensemble des liens de votre compte. Au-delà, le lien répond 429 en texte brut. Pour distribuer un fichier à beaucoup de personnes, rendez-le public : les fichiers publics sont servis par le CDN, sans cette limite. Un lien expiré ou invalide répond 404.

Réponse

Avec redirect=true (par défaut) : 302 avec le lien dans Location et Cache-Control: no-store. Avec redirect=false :

string

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

object

Afficher Afficher l'objet

string

Le lien : un lien temporaire sur files.squarecloud.dev, ou l’URL publique.

ISO 8601 | null

Date d’expiration du lien temporaire, ou null pour une URL publique.

boolean

Indique si le fichier est privé.

number

La taille du fichier, en octets.

string

Le Content-Type avec lequel le fichier est servi.

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

Erreurs

Code	HTTP	Quand
`INVALID_OBJECT`	400	`object` est absent, mal formé ou ne vous appartient pas.
`INVALID_DOWNLOAD_EXPIRES`	400	`expires` n’est pas un entier de 60 à 86400.
`INVALID_OBJECT_DISPOSITION`	400	`disposition` ne vaut ni `inline` ni `attachment`.
`INVALID_FILENAME`	400	`filename` est vide après suppression des caractères invalides.
`OBJECT_NOT_FOUND`	404	Le fichier n’existe pas.
`RATE_LIMITED`	429	Plus de 60 requêtes en une minute.

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

Premiers Pas

Objets

Upload par Morceaux

Compte

Liens de Partage

S3

Limites de débit

Réponse

Erreurs

​Limites de débit

​Réponse

​Erreurs

Limites de débit

Réponse

Erreurs