Blob Object Download

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 Ihr Konto. Sie finden ihn in Ihren 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. 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. Siehe Links und Freigabe.

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 Objekt umschalten

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.
`OBJECT_NOT_FOUND`	404	Die Datei existiert nicht.
`RATE_LIMITED`	429	Mehr als 60 Requests in einer Minute.

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

Rate Limits

Antwort

Fehler

​Rate Limits

​Antwort

​Fehler

Rate Limits

Antwort

Fehler