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

> Ändere mit PATCH /v1/objects Sichtbarkeit, Ablauf, Cache, Disposition oder Metadaten von bis zu 50 Dateien pro Request, ohne sie erneut hochzuladen.

<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 Update ändert bereits gespeicherte Dateien, ohne sie erneut hochzuladen: Mache sie privat oder öffentlich, setze oder entferne einen Ablauf und ändere Cache, Disposition oder Metadaten. Der Endpoint akzeptiert eine Datei oder bis zu **50 pro Request**, die alle dieselben Änderungen erhalten. Erfordert den Scope `blob:write`.

Die Änderungen werden in der Reihenfolge der unten aufgeführten Felder angewendet, jede auf das Ergebnis der vorherigen. Sobald der Body gültig ist, antwortet die Route immer mit `200`, mit einem Ergebnis pro Datei.

<Warning>
  **Das Ändern von `private` oder `expire` ändert die id der Datei** (und bei öffentlichen Dateien ihre URL). Speichere die neue `id` aus jedem Ergebnis. Freigabelinks und temporäre Links zur alten id funktionieren nicht mehr. Die anderen Felder behalten die id bei.
</Warning>

<ParamField body="object" type="string">
  Die id einer Datei. Sende `object` oder `objects`.
</ParamField>

<ParamField body="objects" type="string[]">
  Bis zu 50 ids.
</ParamField>

<ParamField body="private" type="boolean">
  `true` macht die Datei privat: Die öffentliche Kopie wird entfernt, bevor der Request antwortet, und das CDN verwirft sie in etwa 60 Sekunden. `false` veröffentlicht sie, was einen kostenpflichtigen Plan erfordert. Siehe [Links und Freigabe](/de/blob-reference/links-and-sharing).
</ParamField>

<ParamField body="expire" type="string | null">
  Ein neuer Ablauf ab jetzt (`30d`, `6h`, `30`) oder `null`, um die Datei für immer zu behalten. Erfordert einen kostenpflichtigen Plan, und Ablaufzeiten unter 7 Tagen erfordern Enterprise.
</ParamField>

<ParamField body="cache_control" type="string | null">
  `immutable`, `max-age=N` (60 bis 31536000) oder `no-cache` (nur Enterprise). `null` entfernt den Header, und der CDN-Standard gilt.
</ParamField>

<ParamField body="disposition" type="string | null">
  `inline` oder `attachment` (Download mit dem ursprünglichen Dateinamen). `null` entfernt den Header.
</ParamField>

<ParamField body="metadata" type="object | null">
  Schlüssel, die gesetzt oder geändert werden sollen. Ein Schlüssel mit dem Wert `null` wird entfernt, und `metadata: null` entfernt alle. Bis zu 5 Schlüssel und 512 Bytes nach der Änderung. Das Setzen von Schlüsseln erfordert Pro oder Enterprise; Entfernen ist immer erlaubt.
</ParamField>

### Legacy-Dateien

Legacy-Dateien, hochgeladen vor dem Update im September 2026 (ids ohne `pub/` oder `prv/`), können privat gemacht werden und einen neuen Ablauf erhalten: Beides verschiebt sie in den neuen Speicher, mit einer neuen id. Ihre Header (`cache_control`, `disposition`, `metadata`) können nicht an Ort und Stelle geändert werden und antworten mit `OBJECT_IS_LEGACY`: Verschiebe die Datei zuerst mit [Object Copy](/de/blob-reference/endpoint/copy) (`move: true`) und aktualisiere sie dann.

### Rate Limits

<Note>50 Dateien pro 10 Sekunden, pro Datei gezählt: Ein voller Stapel von 50 verbraucht das ganze Fenster (`RATE_LIMITED`, 429).</Note>

### Antwort

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

<ResponseField name="response" type="object">
  <Expandable title="Objekt umschalten">
    <ResponseField name="results" type="array">
      Ein Eintrag pro Datei, in der gesendeten Reihenfolge.

      <Expandable title="Objekt umschalten">
        <ResponseField name="object" type="string">
          Die id, wie sie im Request gesendet wurde.
        </ResponseField>

        <ResponseField name="ok" type="boolean">
          Ob jede Änderung auf diese Datei angewendet wurde.
        </ResponseField>

        <ResponseField name="code" type="string">
          Nur wenn `ok` `false` ist: warum diese Datei fehlgeschlagen ist.
        </ResponseField>

        <ResponseField name="changed" type="boolean">
          Ob sich die id geändert hat.
        </ResponseField>

        <ResponseField name="id" type="string">
          Die aktuelle id der Datei. Speichere sie.
        </ResponseField>

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

        <ResponseField name="url" type="string | null">
          Die öffentliche URL oder `null` bei privaten Dateien.
        </ResponseField>

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

        <ResponseField name="expires_at" type="ISO 8601 | null">
          Wann die Datei gelöscht wird, oder `null`, wenn sie nicht abläuft.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Privat machen theme={null}
  curl --request PATCH \
    --url 'https://blob.squarecloud.app/v1/objects' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "object": "pub/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
      "private": true
    }'
  ```

  ```bash Header ändern theme={null}
  curl --request PATCH \
    --url 'https://blob.squarecloud.app/v1/objects' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "objects": [
        "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "pub/3155597145698959364/images/banner_mugws5c0-1b4f0e9851971998e732078544c96b36.png"
      ],
      "cache_control": "max-age=3600",
      "metadata": { "campaign": "spring", "draft": null }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Privat machen theme={null}
  {
    "status": "success",
    "response": {
      "results": [
        {
          "object": "pub/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
          "ok": true,
          "changed": true,
          "id": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
          "private": true,
          "url": null,
          "size": 88412,
          "expires_at": null
        }
      ]
    }
  }
  ```

  ```json Mit einem Fehlschlag theme={null}
  {
    "status": "success",
    "response": {
      "results": [
        {
          "object": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
          "ok": true,
          "changed": false,
          "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
          "private": false,
          "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
          "size": 416230,
          "expires_at": null
        },
        {
          "object": "pub/3155597145698959364/images/banner_mugws5c0-1b4f0e9851971998e732078544c96b36.png",
          "ok": false,
          "code": "OBJECT_NOT_FOUND"
        }
      ]
    }
  }
  ```
</ResponseExample>

### Fehler

Fehler des gesamten Requests:

| Code                                                                                                                                           | HTTP | Wann                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------------------------------- |
| `INVALID_BODY` / `INVALID_OBJECT`                                                                                                              | 400  | Der Body ist kein JSON-Objekt, oder eine id fehlt, ist fehlerhaft oder gehört nicht dir. |
| `TOO_MANY_OBJECTS`                                                                                                                             | 400  | Mehr als 50 ids.                                                                         |
| `NOTHING_TO_UPDATE`                                                                                                                            | 400  | Es wurde kein zu änderndes Feld gesendet.                                                |
| `INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_METADATA` | 400  | Ein Feld hat einen ungültigen Wert.                                                      |
| `UPGRADE_REQUIRED`                                                                                                                             | 403  | Ein Wert erfordert einen höheren Plan. Die `message` nennt welchen.                      |
| `RATE_LIMITED`                                                                                                                                 | 429  | Mehr als 50 Dateien in 10 Sekunden.                                                      |

Codes einer einzelnen Datei, in ihrem Ergebnis:

| Code                                                         | Wann                                                                                                            |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `OBJECT_NOT_FOUND`                                           | Die Datei existiert nicht.                                                                                      |
| `PERMISSION_DENIED`                                          | Veröffentlichen oder Ändern des Ablaufs erfordert einen aktiven kostenpflichtigen Plan.                         |
| `OBJECT_IS_LEGACY`                                           | Header-Änderung an einer Legacy-Datei. Verschiebe sie zuerst.                                                   |
| `INVALID_OBJECT_METADATA`                                    | Die Datei würde 5 Schlüssel oder 512 Bytes an Metadaten überschreiten.                                          |
| `VISIBILITY_CHANGE_FAILED`                                   | Die öffentliche Kopie konnte nicht entfernt werden: Die Datei **ist weiterhin öffentlich**. Versuche es erneut. |
| `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | Der Speicher ist vorübergehend nicht verfügbar. Versuche es erneut.                                             |
| `UPDATE_FAILED`                                              | Die Änderung ist fehlgeschlagen. Versuche es erneut.                                                            |