> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Blob Object Download

> Obtenez un lien de téléchargement pour n'importe quel fichier avec GET /v1/objects/download : un lien temporaire jusqu'à 24 heures pour les fichiers privés, ou l'URL publique.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  La clé d'API de votre compte. Vous pouvez la trouver dans les [paramètres de votre compte](https://squarecloud.app/fr/account/security).
</ParamField>

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](/fr/blob-reference/endpoint/shares-create). Voir [Liens et partage](/fr/blob-reference/links-and-sharing).

<ParamField query="object" type="string" required>
  L'id du fichier.
</ParamField>

<ParamField query="expires" type="number" default="3600">
  Durée de validité du lien temporaire, de 60 à 86400 secondes (24 heures).
</ParamField>

<ParamField query="redirect" type="boolean" default="true">
  `false` renvoie le lien en JSON au lieu de rediriger.
</ParamField>

<ParamField query="disposition" type="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.
</ParamField>

<ParamField query="filename" type="string" placeholder="report-september.pdf">
  Le nom sous lequel le navigateur enregistre le fichier. Implique `attachment` sauf indication contraire de `disposition`, et produit toujours un lien temporaire.
</ParamField>

### Limites de débit

<Note>
  * 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`.
</Note>

### Réponse

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

<ResponseField name="status" type="string">
  "success" en cas de succès, "error" sinon.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Afficher l'objet">
    <ResponseField name="url" type="string">
      Le lien : un lien temporaire sur `files.squarecloud.dev`, ou l'URL publique.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601 | null">
      Date d'expiration du lien temporaire, ou `null` pour une URL publique.
    </ResponseField>

    <ResponseField name="private" type="boolean">
      Indique si le fichier est privé.
    </ResponseField>

    <ResponseField name="size" type="number">
      La taille du fichier, en octets.
    </ResponseField>

    <ResponseField name="content_type" type="string">
      Le `Content-Type` avec lequel le fichier est servi.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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'
  ```

  ```javascript JavaScript theme={null}
  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
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### 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.                              |