Temporären Download-Link erstellen

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

erforderlich

Der API-Schlüssel für dein Konto. Du findest ihn in deinen Kontoeinstellungen.

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. Das Erstellen eines temporären Links (für eine private Datei oder mit disposition oder filename) erfordert außerdem einen aktiven Plan; die eigene URL einer öffentlichen Datei bekommst du auch ohne. Temporäre Links (https://files.squarecloud.dev/d/...) können nicht einzeln widerrufen werden und unterstützen Range und bedingte Requests. Sie funktionieren nicht mehr, wenn sie ablaufen, wenn die Datei gelöscht, verschoben wird oder ihre Sichtbarkeit ändert, wenn unter derselben id eine andere Datei geschrieben wird, und wenn der API-Schlüssel, der sie erstellt hat, neu generiert oder widerrufen wird (oder die Dashboard-Sitzung, die sie erstellt hat, abgemeldet wird). Für Links, die du widerrufen, begrenzen oder mit einem Passwort schützen kannst, verwende einen Freigabelink. Siehe Links und Freigabe.

Parameter

string

erforderlich

Die id der Datei.

number

Standard:"3600"

Wie lange der temporäre Link gilt, von 60 bis 86400 Sekunden (24 Stunden).

boolean

Standard:"true"

false gibt den Link als JSON zurück, statt weiterzuleiten.

string

inline (im Browser öffnen) oder attachment (herunterladen). Wenn gesetzt, entsteht immer ein temporärer Link, auch bei öffentlichen Dateien.

string

Der Name, unter dem der Browser die Datei speichert. Impliziert attachment, sofern disposition nichts anderes angibt, und erzeugt immer einen temporären Link.

Rate Limits

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.

Antwort

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

string

“success” bei Erfolg, “error” bei Misserfolg.

object

Anzeigen Eigenschaften

string

Der Link: ein temporärer Link auf files.squarecloud.dev oder die öffentliche URL.

ISO 8601 | null

Wann der temporäre Link abläuft, oder null bei einer öffentlichen URL.

boolean

Ob die Datei privat ist.

number

Die Größe der Datei in Bytes.

string

Der Content-Type, mit dem die Datei ausgeliefert wird.

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

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.
`PERMISSION_DENIED`	401	Ein temporärer Link erfordert einen aktiven Plan.
`OBJECT_NOT_FOUND`	404	Die Datei existiert nicht.
`RATE_LIMITED`	429	Mehr als 60 Requests in einer Minute.

Siehe auch

Blob SDK: blob.downloadUrl()

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

Erste Schritte

Objekte

Chunked-Uploads

Konto

Freigabelinks

S3

Temporären Download-Link erstellen

Parameter

Rate Limits

Antwort

Fehler

Siehe auch

​Parameter

​Rate Limits

​Antwort

​Fehler

​Siehe auch

Parameter

Rate Limits

Antwort

Fehler

Siehe auch