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

> Copia, sposta o rinomina un file all'interno di Blob Storage con POST /v1/objects/copy, lato server e senza scaricarlo.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  La chiave API del tuo account. Puoi trovarla nelle [impostazioni del tuo account](https://squarecloud.app/it/account/security).
</ParamField>

Object Copy duplica un file con un nuovo nome, prefisso o visibilità, interamente sul server: nessun byte passa per la tua applicazione. Con `move: true` l'origine viene rimossa in seguito, ed è così che **rinomini** o **sposti** un file. Richiede lo scope `blob:write` e un piano a pagamento.

* La copia mantiene estensione, content type, cache, disposition e metadati dell'origine.
* Una copia conta nella tua quota di storage; uno spostamento no.
* La destinazione usa sempre lo storage attuale, quindi spostare è anche il modo per portare un file legacy, archiviato prima dell'aggiornamento di settembre 2026, al nuovo formato (vedi [Object Update](/it/blob-reference/endpoint/update#file-legacy)).

<ParamField body="source" type="string" required>
  L'id del file da copiare.
</ParamField>

<ParamField body="destination" type="object" required>
  Dove va la copia.

  <Expandable title="proprietà">
    <ParamField body="name" type="string" required>
      Il nuovo nome, senza estensione. Stesso pattern di [Object Post](/it/blob-reference/endpoint/post).
    </ParamField>

    <ParamField body="prefix" type="string">
      Il nuovo prefisso. Omettilo per archiviare la copia nella radice.
    </ParamField>

    <ParamField body="private" type="boolean">
      La visibilità della copia. Per impostazione predefinita è quella dell'origine.
    </ParamField>

    <ParamField body="expire" type="string | null">
      Una nuova scadenza calcolata da adesso (`30d`, `6h`). `null` la rimuove. Omettilo per mantenere la data di scadenza dell'origine.
    </ParamField>

    <ParamField body="security_hash" type="boolean" default="false">
      Aggiunge un suffisso casuale al nuovo nome. Le copie private lo ricevono sempre.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="move" type="boolean" default="false">
  `true` rimuove l'origine dopo che la copia è riuscita.
</ParamField>

<ParamField body="overwrite" type="boolean" default="false">
  `true` sostituisce un file esistente nella destinazione. Altrimenti la richiesta risponde `409 OBJECT_ALREADY_EXISTS`.
</ParamField>

### Limiti di frequenza

<Note>10 richieste ogni 10 secondi (`RATE_LIMITED`, 429).</Note>

### Risposta

<ResponseField name="status" type="string">
  "success" in caso di successo, "error" in caso contrario.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Mostra oggetto">
    <ResponseField name="id" type="string">
      L'id del nuovo file.
    </ResponseField>

    <ResponseField name="private" type="boolean">
      Se il nuovo file è privato.
    </ResponseField>

    <ResponseField name="url" type="string | null">
      L'URL pubblico del nuovo file, oppure `null` se è privato.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601">
      Quando il nuovo file verrà eliminato. Presente solo se il file scade.
    </ResponseField>

    <ResponseField name="size" type="number">
      La dimensione del file, in byte.
    </ResponseField>

    <ResponseField name="source" type="string">
      L'id dell'origine.
    </ResponseField>

    <ResponseField name="moved" type="boolean">
      Se l'origine è stata rimossa.
    </ResponseField>

    <ResponseField name="replaced" type="boolean">
      Se un file esistente nella destinazione è stato sostituito.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Rinomina 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>

### Errori

| Codice                                                       | HTTP | Quando                                                            |
| ------------------------------------------------------------ | ---- | ----------------------------------------------------------------- |
| `INVALID_OBJECT`                                             | 400  | `source` manca, è malformato o non ti appartiene.                 |
| `INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX`              | 400  | Il nome o il prefisso di destinazione non rispetta il pattern.    |
| `INVALID_DESTINATION`                                        | 400  | `private` o `security_hash` non è un booleano.                    |
| `INVALID_OBJECT_EXPIRE`                                      | 400  | `expire` non è una durata da 1 ora a 1825 giorni.                 |
| `INVALID_OBJECT_SECURITY_HASH`                               | 400  | `security_hash: false` su una copia privata.                      |
| `SAME_OBJECT`                                                | 400  | La destinazione coincide con l'origine.                           |
| `PERMISSION_DENIED`                                          | 401  | L'account non ha un piano a pagamento attivo.                     |
| `UPGRADE_REQUIRED`                                           | 403  | La scadenza richiede un piano superiore.                          |
| `STORAGE_QUOTA_EXCEEDED`                                     | 403  | La copia supererebbe lo storage incluso.                          |
| `OBJECT_NOT_FOUND`                                           | 404  | L'origine non esiste.                                             |
| `OBJECT_ALREADY_EXISTS`                                      | 409  | Esiste già un file nella destinazione e `overwrite` non è `true`. |
| `RATE_LIMITED`                                               | 429  | Più di 10 richieste in 10 secondi.                                |
| `COPY_FAILED`                                                | 500  | La copia non è riuscita. Riprova.                                 |
| `PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE` | 503  | Lo storage è temporaneamente non disponibile. Riprova.            |