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

> Kopiere, verschiebe oder benenne eine Datei in Blob Storage mit POST /v1/objects/copy um, serverseitig und ohne sie herunterzuladen.

<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 Copy dupliziert eine Datei unter einem neuen Namen, Präfix oder einer neuen Sichtbarkeit, vollständig auf dem Server: Keine Bytes laufen durch deine Anwendung. Mit `move: true` wird die Quelle anschließend entfernt, so **benennst** du eine Datei **um** oder **verschiebst** sie. Erfordert den Scope `blob:write` und einen kostenpflichtigen Plan.

* Die Kopie behält Endung, Content-Type, Cache, Disposition und Metadaten der Quelle.
* Eine Kopie zählt gegen dein Speicherkontingent; eine Verschiebung nicht.
* Das Ziel verwendet immer den aktuellen Speicher, daher ist das Verschieben auch der Weg, eine Legacy-Datei, gespeichert vor dem Update im September 2026, in das neue Format zu überführen (siehe [Object Update](/de/blob-reference/endpoint/update#legacy-dateien)).

<ParamField body="source" type="string" required>
  Die id der zu kopierenden Datei.
</ParamField>

<ParamField body="destination" type="object" required>
  Wohin die Kopie geht.

  <Expandable title="Eigenschaften">
    <ParamField body="name" type="string" required>
      Der neue Name, ohne Endung. Dasselbe Muster wie in [Object Post](/de/blob-reference/endpoint/post).
    </ParamField>

    <ParamField body="prefix" type="string">
      Das neue Präfix. Lass es weg, um die Kopie im Stammverzeichnis zu speichern.
    </ParamField>

    <ParamField body="private" type="boolean">
      Die Sichtbarkeit der Kopie. Standardmäßig die der Quelle.
    </ParamField>

    <ParamField body="expire" type="string | null">
      Ein neuer Ablauf ab jetzt (`30d`, `6h`). `null` entfernt ihn. Lass es weg, um das Ablaufdatum der Quelle beizubehalten.
    </ParamField>

    <ParamField body="security_hash" type="boolean" default="false">
      Fügt dem neuen Namen ein zufälliges Suffix hinzu. Private Kopien erhalten es immer.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="move" type="boolean" default="false">
  `true` entfernt die Quelle, nachdem die Kopie erfolgreich war.
</ParamField>

<ParamField body="overwrite" type="boolean" default="false">
  `true` ersetzt eine bestehende Datei am Ziel. Andernfalls antwortet der Request mit `409 OBJECT_ALREADY_EXISTS`.
</ParamField>

### Rate Limits

<Note>10 Requests pro 10 Sekunden (`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="id" type="string">
      Die id der neuen Datei.
    </ResponseField>

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

    <ResponseField name="url" type="string | null">
      Die öffentliche URL der neuen Datei oder `null`, wenn sie privat ist.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601">
      Wann die neue Datei gelöscht wird. Nur vorhanden, wenn sie abläuft.
    </ResponseField>

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

    <ResponseField name="source" type="string">
      Die id der Quelle.
    </ResponseField>

    <ResponseField name="moved" type="boolean">
      Ob die Quelle entfernt wurde.
    </ResponseField>

    <ResponseField name="replaced" type="boolean">
      Ob eine bestehende Datei am Ziel ersetzt wurde.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Umbenennen theme={null}
  curl --request POST \
    --url 'https://blob.squarecloud.app/v1/objects/copy' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "source": "pub/3155597145698959364/uploads/IMG_2041.png",
      "destination": { "name": "cover", "prefix": "posts/launch" },
      "move": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://blob.squarecloud.app/v1/objects/copy', {
    method: 'POST',
    headers: {
      Authorization: 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      source: 'pub/3155597145698959364/uploads/IMG_2041.png',
      destination: { name: 'cover', prefix: 'posts/launch' },
      move: true,
    }),
  });
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "id": "pub/3155597145698959364/posts/launch/cover.png",
      "private": false,
      "url": "https://blob.squarecloud.dev/pub/3155597145698959364/posts/launch/cover.png",
      "size": 416230,
      "source": "pub/3155597145698959364/uploads/IMG_2041.png",
      "moved": true,
      "replaced": false
    }
  }
  ```
</ResponseExample>

### Fehler

| Code                                                         | HTTP | Wann                                                                |
| ------------------------------------------------------------ | ---- | ------------------------------------------------------------------- |
| `INVALID_OBJECT`                                             | 400  | `source` fehlt, ist fehlerhaft oder gehört nicht dir.               |
| `INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX`              | 400  | Name oder Präfix des Ziels entspricht nicht dem Muster.             |
| `INVALID_DESTINATION`                                        | 400  | `private` oder `security_hash` ist kein Boolean.                    |
| `INVALID_OBJECT_EXPIRE`                                      | 400  | `expire` ist keine Dauer von 1 Stunde bis 1825 Tage.                |
| `INVALID_OBJECT_SECURITY_HASH`                               | 400  | `security_hash: false` bei einer privaten Kopie.                    |
| `SAME_OBJECT`                                                | 400  | Das Ziel ist die Quelle.                                            |
| `PERMISSION_DENIED`                                          | 401  | Das Konto hat keinen aktiven kostenpflichtigen Plan.                |
| `UPGRADE_REQUIRED`                                           | 403  | Der Ablauf erfordert einen höheren Plan.                            |
| `STORAGE_QUOTA_EXCEEDED`                                     | 403  | Die Kopie würde den enthaltenen Speicher überschreiten.             |
| `OBJECT_NOT_FOUND`                                           | 404  | Die Quelle existiert nicht.                                         |
| `OBJECT_ALREADY_EXISTS`                                      | 409  | Am Ziel existiert eine Datei und `overwrite` ist nicht `true`.      |
| `RATE_LIMITED`                                               | 429  | Mehr als 10 Requests in 10 Sekunden.                                |
| `COPY_FAILED`                                                | 500  | Die Kopie ist fehlgeschlagen. Versuche es erneut.                   |
| `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | 503  | Der Speicher ist vorübergehend nicht verfügbar. Versuche es erneut. |