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

> Erhalte mit GET /v1/objects/download einen Download-Link für jede Datei: einen temporären Link von bis zu 24 Stunden für private Dateien oder die öffentliche URL.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  Der API-Schlüssel für Ihr Konto. Sie finden ihn in Ihren [Kontoeinstellungen](https://squarecloud.app/de/account/security).
</ParamField>

Object Download gibt dir einen Link, um eine Datei zu lesen. Für eine **private** Datei signiert der Endpoint einen temporären Link, gültig von 60 Sekunden bis 24 Stunden, der ohne Zugangsdaten funktioniert. Für eine **öffentliche** Datei gibt er die öffentliche URL zurück. Standardmäßig antwortet er mit einer `302`-Weiterleitung, sodass du einen Browser oder `curl -L` direkt darauf richten kannst; `redirect=false` gibt den Link als JSON zurück. Erfordert den Scope `blob:read`.

Temporäre Links (`https://files.squarecloud.dev/d/...`) können nicht widerrufen werden, unterstützen `Range` und bedingte Requests und funktionieren nicht mehr, wenn sie ablaufen oder wenn die Datei gelöscht, verschoben wird oder ihre Sichtbarkeit ändert. Für Links, die du widerrufen, begrenzen oder mit einem Passwort schützen kannst, verwende einen [Freigabelink](/de/blob-reference/endpoint/shares-create). Siehe [Links und Freigabe](/de/blob-reference/links-and-sharing).

<ParamField query="object" type="string" required>
  Die id der Datei.
</ParamField>

<ParamField query="expires" type="number" default="3600">
  Wie lange der temporäre Link gilt, von 60 bis 86400 Sekunden (24 Stunden).
</ParamField>

<ParamField query="redirect" type="boolean" default="true">
  `false` gibt den Link als JSON zurück, statt weiterzuleiten.
</ParamField>

<ParamField query="disposition" type="string">
  `inline` (im Browser öffnen) oder `attachment` (herunterladen). Wenn gesetzt, entsteht immer ein temporärer Link, auch bei öffentlichen Dateien.
</ParamField>

<ParamField query="filename" type="string" placeholder="report-september.pdf">
  Der Name, unter dem der Browser die Datei speichert. Impliziert `attachment`, sofern `disposition` nichts anderes angibt, und erzeugt immer einen temporären Link.
</ParamField>

### Rate Limits

<Note>
  * 60 Requests pro Minute an diese Route (`RATE_LIMITED`, 429).
  * Jeder temporäre Link akzeptiert 60 Requests pro Minute pro IP, zusätzlich zu einem Gesamtlimit für alle Links deines Kontos. Darüber antwortet der Link mit `429` als reinem Text. Um eine Datei an viele Personen zu verteilen, mach sie öffentlich: Öffentliche Dateien werden vom CDN ausgeliefert, ohne dieses Limit. Ein abgelaufener oder ungültiger Link antwortet mit `404`.
</Note>

### Antwort

Mit `redirect=true` (Standard): `302` mit dem Link in `Location` und `Cache-Control: no-store`. Mit `redirect=false`:

<ResponseField name="status" type="string">
  "success" bei Erfolg, "error" bei Misserfolg.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Objekt umschalten">
    <ResponseField name="url" type="string">
      Der Link: ein temporärer Link auf `files.squarecloud.dev` oder die öffentliche URL.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601 | null">
      Wann der temporäre Link abläuft, oder `null` bei einer öffentlichen URL.
    </ResponseField>

    <ResponseField name="private" type="boolean">
      Ob die Datei privat ist.
    </ResponseField>

    <ResponseField name="size" type="number">
      Die Größe der Datei in Bytes.
    </ResponseField>

    <ResponseField name="content_type" type="string">
      Der `Content-Type`, mit dem die Datei ausgeliefert wird.
    </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>

### Fehler

| Code                         | HTTP | Wann                                                       |
| ---------------------------- | ---- | ---------------------------------------------------------- |
| `INVALID_OBJECT`             | 400  | `object` fehlt, ist fehlerhaft oder gehört nicht dir.      |
| `INVALID_DOWNLOAD_EXPIRES`   | 400  | `expires` ist keine Ganzzahl von 60 bis 86400.             |
| `INVALID_OBJECT_DISPOSITION` | 400  | `disposition` ist nicht `inline` oder `attachment`.        |
| `INVALID_FILENAME`           | 400  | `filename` ist nach dem Entfernen ungültiger Zeichen leer. |
| `OBJECT_NOT_FOUND`           | 404  | Die Datei existiert nicht.                                 |
| `RATE_LIMITED`               | 429  | Mehr als 60 Requests in einer Minute.                      |