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

> Crea un link di condivisione con POST /v1/shares: valido fino a 30 giorni, revocabile, con un limite di download opzionale e, su Pro ed Enterprise, una password.

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

Create Share crea un link (`https://files.squarecloud.dev/s/...`) per consegnare un file a delle persone: un cliente, un team, un tester. Funziona per file pubblici e privati, dura fino a 30 giorni, può essere revocato in qualsiasi momento e può limitare quante volte il file viene scaricato. Su **Pro ed Enterprise** può anche richiedere una password. Richiede lo scope `blob:write`.

Aprire il link scarica il file. Un link protetto da password mostra prima una pagina che chiede la password, nella lingua del visitatore. Il link è legato all'id attuale del file: eliminare, spostare o cambiare la visibilità del file fa sì che risponda subito `404`, senza consumare un download. Vedi [Link e condivisione](/it/blob-reference/links-and-sharing) per il confronto con i link temporanei.

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

<ParamField body="expires_in" type="number" default="86400">
  Quanto dura il link, da 60 a 2592000 secondi (30 giorni).
</ParamField>

<ParamField body="max_downloads" type="number">
  Quanti download consente il link, da 1 a 10000. Una volta esauriti, risponde `410`. Senza di esso, non c'è limite.
</ParamField>

<ParamField body="password" type="string">
  Una password da 8 a 128 caratteri che il visitatore deve digitare prima di scaricare. Solo Pro ed Enterprise.
</ParamField>

<Warning>Per un file **pubblico** il link reindirizza al suo URL pubblico permanente, che chiunque lo apra può continuare a usare. La password, il limite di download e la scadenza proteggono davvero solo i file **privati**.</Warning>

### Limiti

<Note>
  * 30 link al minuto (`RATE_LIMITED`, 429), e fino a 1000 link attivi per account (`TOO_MANY_SHARES`, 409).
  * Ogni link accetta 120 visite al minuto per IP. Le password errate sono limitate per IP e per link.
  * Il download di un file privato passa per un link temporaneo: 60 richieste al minuto per IP, più il limite complessivo del tuo account. Per consegnare un file a molte persone, rendilo pubblico.
</Note>

### Risposta

Risponde `201 Created`.

<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 della condivisione. Usalo con [Delete Share](/it/blob-reference/endpoint/shares-delete).
    </ResponseField>

    <ResponseField name="url" type="string">
      Il link da distribuire.
    </ResponseField>

    <ResponseField name="expires_at" type="ISO 8601">
      Quando scade il link.
    </ResponseField>

    <ResponseField name="max_downloads" type="number | null">
      Il limite di download, oppure `null`.
    </ResponseField>

    <ResponseField name="password" type="boolean">
      Se il link richiede una password.
    </ResponseField>

    <ResponseField name="object" type="string">
      L'id del file condiviso.
    </ResponseField>

    <ResponseField name="object_is_public" type="boolean">
      `true` quando il file è pubblico: chiunque abbia il suo URL pubblico può comunque scaricarlo, quindi revocare, limitare o proteggere la condivisione non restringe l'accesso al file stesso.
    </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>

### Errori

| Codice                  | HTTP | Quando                                                |
| ----------------------- | ---- | ----------------------------------------------------- |
| `INVALID_OBJECT`        | 400  | `object` manca, è malformato o non ti appartiene.     |
| `INVALID_EXPIRES_IN`    | 400  | `expires_in` non è un intero da 60 a 2592000.         |
| `INVALID_MAX_DOWNLOADS` | 400  | `max_downloads` non è un intero da 1 a 10000.         |
| `INVALID_PASSWORD`      | 400  | La password non ha da 8 a 128 caratteri.              |
| `UPGRADE_REQUIRED`      | 403  | Le password richiedono Pro o Enterprise.              |
| `OBJECT_NOT_FOUND`      | 404  | Il file non esiste.                                   |
| `TOO_MANY_SHARES`       | 409  | L'account ha 1000 link attivi. Revocane alcuni prima. |
| `RATE_LIMITED`          | 429  | Più di 30 link in un minuto.                          |