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

> Erstelle mit POST /v1/shares einen Freigabelink: bis zu 30 Tage gültig, widerrufbar, mit optionalem Download-Limit und bei Pro und Enterprise einem Passwort.

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

Create Share erstellt einen Link (`https://files.squarecloud.dev/s/...`), um eine Datei an Menschen zu übergeben: einen Kunden, ein Team, einen Tester. Er funktioniert für öffentliche und private Dateien, gilt bis zu 30 Tage, kann jederzeit widerrufen werden und kann begrenzen, wie oft die Datei heruntergeladen wird. Bei **Pro und Enterprise** kann er außerdem ein Passwort abfragen. Erfordert den Scope `blob:write`.

Das Öffnen des Links lädt die Datei herunter. Ein passwortgeschützter Link zeigt zuerst eine Seite, die in der Sprache des Besuchers nach dem Passwort fragt. Der Link ist an die aktuelle id der Datei gebunden: Das Löschen, Verschieben oder Ändern der Sichtbarkeit der Datei lässt ihn sofort mit `404` antworten, ohne einen Download zu verbrauchen. Unter [Links und Freigabe](/de/blob-reference/links-and-sharing) erfährst du, wie er sich von temporären Links unterscheidet.

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

<ParamField body="expires_in" type="number" default="86400">
  Wie lange der Link gilt, von 60 bis 2592000 Sekunden (30 Tage).
</ParamField>

<ParamField body="max_downloads" type="number">
  Wie viele Downloads der Link erlaubt, von 1 bis 10000. Sind sie aufgebraucht, antwortet er mit `410`. Ohne diesen Wert gibt es kein Limit.
</ParamField>

<ParamField body="password" type="string">
  Ein Passwort mit 8 bis 128 Zeichen, das der Besucher vor dem Download eingeben muss. Nur Pro und Enterprise.
</ParamField>

<Warning>Bei einer **öffentlichen** Datei leitet der Link auf ihre dauerhafte öffentliche URL weiter, die jeder, der ihn öffnet, weiter nutzen kann. Passwort, Download-Limit und Ablauf schützen nur **private** Dateien wirklich.</Warning>

### Limits

<Note>
  * 30 Links pro Minute (`RATE_LIMITED`, 429) und bis zu 1000 aktive Links pro Konto (`TOO_MANY_SHARES`, 409).
  * Jeder Link akzeptiert 120 Aufrufe pro Minute pro IP. Falsche Passwörter sind pro IP und pro Link begrenzt.
  * Der Download einer privaten Datei läuft über einen temporären Link: 60 Requests pro Minute pro IP, plus das Gesamtlimit deines Kontos. Um eine Datei an viele Personen zu verteilen, mach sie öffentlich.
</Note>

### Antwort

Antwortet mit `201 Created`.

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

<ResponseField name="response" type="object">
  <Expandable title="Objekt umschalten">
    <ResponseField name="id" type="string">
      Die Freigabe-id. Verwende sie mit [Delete Share](/de/blob-reference/endpoint/shares-delete).
    </ResponseField>

    <ResponseField name="url" type="string">
      Der Link zum Weitergeben.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601">
      Wann der Link abläuft.
    </ResponseField>

    <ResponseField name="max_downloads" type="number | null">
      Das Download-Limit oder `null`.
    </ResponseField>

    <ResponseField name="password" type="boolean">
      Ob der Link ein Passwort abfragt.
    </ResponseField>

    <ResponseField name="object" type="string">
      Die id der freigegebenen Datei.
    </ResponseField>

    <ResponseField name="object_is_public" type="boolean">
      `true`, wenn die Datei öffentlich ist: Wer ihre öffentliche URL kennt, kann sie weiterhin herunterladen. Das Widerrufen, Begrenzen oder Schützen der Freigabe schränkt den Zugriff auf die Datei selbst also nicht ein.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://blob.squarecloud.app/v1/shares' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
      "expires_in": 604800,
      "max_downloads": 5
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://blob.squarecloud.app/v1/shares', {
    method: 'POST',
    headers: {
      Authorization: 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      object: 'prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf',
      expires_in: 7 * 24 * 60 * 60,
      max_downloads: 5,
    }),
  });
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "id": "q8Zr2LwX7nT0vKc4Hs1YbA",
      "url": "https://files.squarecloud.dev/s/q8Zr2LwX7nT0vKc4Hs1YbA",
      "expires_at": "2026-10-02T12:00:00.000Z",
      "max_downloads": 5,
      "password": false,
      "object": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
      "object_is_public": false
    }
  }
  ```
</ResponseExample>

### Fehler

| Code                    | HTTP | Wann                                                      |
| ----------------------- | ---- | --------------------------------------------------------- |
| `INVALID_OBJECT`        | 400  | `object` fehlt, ist fehlerhaft oder gehört nicht dir.     |
| `INVALID_EXPIRES_IN`    | 400  | `expires_in` ist keine Ganzzahl von 60 bis 2592000.       |
| `INVALID_MAX_DOWNLOADS` | 400  | `max_downloads` ist keine Ganzzahl von 1 bis 10000.       |
| `INVALID_PASSWORD`      | 400  | Das Passwort hat nicht 8 bis 128 Zeichen.                 |
| `UPGRADE_REQUIRED`      | 403  | Passwörter erfordern Pro oder Enterprise.                 |
| `OBJECT_NOT_FOUND`      | 404  | Die Datei existiert nicht.                                |
| `TOO_MANY_SHARES`       | 409  | Das Konto hat 1000 aktive Links. Widerrufe zuerst einige. |
| `RATE_LIMITED`          | 429  | Mehr als 30 Links in einer Minute.                        |