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

> Ottieni un link di download per qualsiasi file con GET /v1/objects/download: un link temporaneo fino a 24 ore per i file privati, oppure l'URL pubblico.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  La chiave API del tuo account. Puoi trovarla nelle [impostazioni del tuo account](https://squarecloud.app/it/account/security).
</ParamField>

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](/it/blob-reference/endpoint/shares-create). Vedi [Link e condivisione](/it/blob-reference/links-and-sharing).

<ParamField query="object" type="string" required>
  L'id del file.
</ParamField>

<ParamField query="expires" type="number" default="3600">
  Quanto dura il link temporaneo, da 60 a 86400 secondi (24 ore).
</ParamField>

<ParamField query="redirect" type="boolean" default="true">
  `false` restituisce il link come JSON invece di fare il redirect.
</ParamField>

<ParamField query="disposition" type="string">
  `inline` (apri nel browser) oppure `attachment` (download). Impostarlo produce sempre un link temporaneo, anche per i file pubblici.
</ParamField>

<ParamField query="filename" type="string" placeholder="report-september.pdf">
  Il nome con cui il browser salva il file. Implica `attachment` a meno che `disposition` non indichi altro, e produce sempre un link temporaneo.
</ParamField>

### Limiti di frequenza

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

### Risposta

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

<ResponseField name="status" type="string">
  "success" in caso di successo, "error" in caso contrario.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Mostra oggetto">
    <ResponseField name="url" type="string">
      Il link: un link temporaneo su `files.squarecloud.dev`, oppure l'URL pubblico.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601 | null">
      Quando scade il link temporaneo, oppure `null` per un URL pubblico.
    </ResponseField>

    <ResponseField name="private" type="boolean">
      Se il file è privato.
    </ResponseField>

    <ResponseField name="size" type="number">
      La dimensione del file, in byte.
    </ResponseField>

    <ResponseField name="content_type" type="string">
      Il `Content-Type` con cui il file viene servito.
    </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>

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