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

> Obtén un enlace de descarga para cualquier archivo con GET /v1/objects/download: un enlace temporal de hasta 24 horas para archivos privados, o la URL pública.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  La clave de API de tu cuenta. Puedes encontrarla en la [configuración de tu cuenta](https://squarecloud.app/es/account/security).
</ParamField>

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](/es/blob-reference/endpoint/shares-create). Consulta [Enlaces y uso compartido](/es/blob-reference/links-and-sharing).

<ParamField query="object" type="string" required>
  El id del archivo.
</ParamField>

<ParamField query="expires" type="number" default="3600">
  Cuánto dura el enlace temporal, de 60 a 86400 segundos (24 horas).
</ParamField>

<ParamField query="redirect" type="boolean" default="true">
  `false` devuelve el enlace como JSON en lugar de redirigir.
</ParamField>

<ParamField query="disposition" type="string">
  `inline` (abrir en el navegador) o `attachment` (descargar). Definirlo siempre produce un enlace temporal, incluso para archivos públicos.
</ParamField>

<ParamField query="filename" type="string" placeholder="report-september.pdf">
  El nombre con el que el navegador guarda el archivo. Implica `attachment` salvo que `disposition` indique otra cosa, y siempre produce un enlace temporal.
</ParamField>

### Límites de tasa

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

### Respuesta

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

<ResponseField name="status" type="string">
  "success" si tuvo éxito, "error" si no.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Alternar objeto">
    <ResponseField name="url" type="string">
      El enlace: un enlace temporal en `files.squarecloud.dev`, o la URL pública.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601 | null">
      Cuándo expira el enlace temporal, o `null` para una URL pública.
    </ResponseField>

    <ResponseField name="private" type="boolean">
      Si el archivo es privado.
    </ResponseField>

    <ResponseField name="size" type="number">
      El tamaño del archivo, en bytes.
    </ResponseField>

    <ResponseField name="content_type" type="string">
      El `Content-Type` con el que se sirve el archivo.
    </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>

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