Carica un file su Blob Storage

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./logo.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./logo.png')]), 'logo.png');

const params = new URLSearchParams({
  name: 'logo',
  prefix: 'images',
  security_hash: 'true',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('logo.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'},
        files={'file': ('logo.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "name": "logo",
        "prefix": "images",
        "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
        "replaced": false
    }
}

{
    "status": "success",
    "response": {
        "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "name": "2026-09",
        "prefix": "invoices",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "replaced": false
    }
}

string

obbligatorio

La chiave API del tuo account. Puoi trovarla nelle impostazioni del tuo account.

Object Post carica un file e restituisce il suo id e, per i file pubblici, un url CDN che puoi incorporare o condividere direttamente. È alla base di allegati, esportazioni generate e contenuti multimediali caricati dagli utenti per le applicazioni ospitate sulla piattaforma. Una singola richiesta accetta file da 512 byte fino a 100 MB. I file più grandi, fino a 10 GiB, passano per il flusso di upload chunked o per il gateway S3. Richiede lo scope blob:write, oppure un upload token inviato in Authorization, e un piano attivo.

Tratta l’id restituito come opaco: salvalo così com’è e rimandalo alle altre route. Inizia con pub/ o prv/ e può cambiare quando il file cambia visibilità o scadenza. I file legacy, archiviati prima dell’aggiornamento di settembre 2026, mantengono id senza quel prefisso, e ogni route accetta entrambi.

Parametri

file

obbligatorio

Usa FormData (multipart/form-data), esattamente un file per richiesta.
Invia un nome file reale: l’estensione archiviata deriva da esso (reads.fastq.gz resta .fastq.gz).

string

obbligatorio

Il nome del file, senza estensione. Da 1 a 128 caratteri: lettere, cifre, _, . e -, iniziando con una lettera, una cifra o _. Non può contenere ...

string

Un percorso di cartella per il file, fino a 8 segmenti separati da / e 256 caratteri in totale. Ogni segmento segue lo stesso pattern di name, fino a 64 caratteri. Una / finale viene ignorata.

boolean

predefinito:"false"

true archivia il file senza URL pubblico. Leggilo tramite Object Download, un link di condivisione o il gateway S3. Se omesso, decide la regola del prefisso.

string

Elimina automaticamente il file dopo questo tempo: 30 o 30d per i giorni, 6h per le ore. Da 1 ora a 1825 giorni (5 anni). Le scadenze sotto i 7 giorni richiedono il piano Enterprise. Se omesso, decide la regola del prefisso.

boolean

predefinito:"false"

true aggiunge un suffisso casuale al nome, così l’URL non può essere indovinato e un nuovo upload non sostituisce mai uno precedente. I file privati lo ricevono sempre (false insieme a private=true viene rifiutato).

boolean

predefinito:"true"

Senza security hash, un nuovo upload con lo stesso nome e prefisso sostituisce il file. false lo rifiuta invece con 409 OBJECT_ALREADY_EXISTS.

string

inline (apri nel browser) oppure attachment (download, con il nome file originale).

boolean

predefinito:"false"

true fa sì che i browser scarichino il file invece di aprirlo, qualunque sia il suo tipo.

string

Per quanto tempo la CDN e i browser conservano il file: immutable (1 anno), max-age=N con N da 60 a 31536000 secondi, oppure no-cache (ogni lettura va allo storage; solo Enterprise). I file con security hash usano immutable come predefinito. La cache non dura mai più della scadenza del file.

string

Un oggetto JSON di valori stringa, restituito da Object Info. Le chiavi usano a-z, 0-9 e - (fino a 64 caratteri). Fino a 5 chiavi e 512 byte in totale. Solo Pro ed Enterprise.

string

Lo SHA-256 del file. Se non corrisponde, l’upload viene rifiutato con CHECKSUM_MISMATCH e non viene archiviato nulla.

Limiti di frequenza e concorrenza

Ogni account può avere al massimo 4 upload in corso contemporaneamente (TOO_MANY_CONCURRENT_UPLOADS, 429).
I piani Hobby e Standard sono limitati a 1 upload al secondo (RATE_LIMITED, 429). Pro ed Enterprise ne sono esenti.
Gli upload oltre lo storage incluso dell’account vengono rifiutati con STORAGE_QUOTA_EXCEEDED.

Tipi di file

Praticamente qualsiasi estensione è accettata, compresi i formati senza un tipo MIME registrato (.bam, .vcf, .fasta, .parquet, .h5, .npy e così via).

Il Content-Type servito è derivato lato server dall’estensione. I formati sconosciuti vengono serviti come application/octet-stream.
I formati che un browser renderizza (.html, .svg, .xml e simili) vengono sempre serviti come download.
Eseguibili e installer vengono rifiutati con BLOCKED_FILE_TYPE: exe, msi, dll, bat, cmd, com, scr, cpl, pif, hta, vbs, vbe, jse, wsf, wsh, msc, reg, lnk, sys, drv, ps1, apk, xpi.
Una regola del prefisso o un upload token possono limitare le estensioni accettate e la dimensione.

Risposta

string

“success” in caso di successo, “error” in caso contrario.

object

Mostra Mostra oggetto

string

L’id dell’oggetto: pub/<user_id>/<path> oppure prv/<user_id>/<path>. Trattalo come opaco.

boolean

Se il file è privato.

string | null

L’URL CDN pubblico (https://blob.squarecloud.dev/pub/...), oppure null per i file privati.

ISO 8601

Quando il file verrà eliminato. Presente solo se il file scade.

number

La dimensione del file, in byte.

string

Il nome inviato nella richiesta.

string

Il prefisso, quando ne è stato inviato uno.

string

Lo SHA-256 del file archiviato, in esadecimale.

boolean

true quando l’upload ha sostituito un file esistente con lo stesso nome.

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./logo.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./logo.png')]), 'logo.png');

const params = new URLSearchParams({
  name: 'logo',
  prefix: 'images',
  security_hash: 'true',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('logo.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'},
        files={'file': ('logo.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "name": "logo",
        "prefix": "images",
        "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
        "replaced": false
    }
}

{
    "status": "success",
    "response": {
        "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "name": "2026-09",
        "prefix": "invoices",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "replaced": false
    }
}

Errori

Codice	HTTP	Quando
`INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX`	400	`name` o `prefix` non rispetta il pattern.
`INVALID_OBJECT_EXPIRE`	400	`expire` non è una durata da 1 ora a 1825 giorni.
`INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_OVERWRITE` / `INVALID_STORAGE_AUTO_DOWNLOAD`	400	Il flag non è `true` o `false`.
`INVALID_OBJECT_SECURITY_HASH`	400	Non è un booleano, oppure è `false` su un file privato.
`INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_METADATA` / `INVALID_CHECKSUM`	400	Il valore non rientra nelle forme accettate.
`INVALID_FILE` / `INVALID_FILE_TYPE` / `BLOCKED_FILE_TYPE` / `FILE_TYPE_NOT_ALLOWED`	400	La parte del file manca, la sua estensione è malformata o bloccata, oppure la regola o il token non la consentono.
`FILE_TOO_SMALL`	400	Il file ha meno di 512 byte.
`CHECKSUM_MISMATCH`	400	Il file non corrisponde a `checksum_sha256`. Non è stato archiviato nulla.
`PERMISSION_DENIED`	401	L’account non ha un piano attivo.
`UPLOAD_TOKEN_USED`	401	L’upload token non ha più utilizzi disponibili. Un token scaduto risponde `ACCESS_DENIED`.
`STORAGE_QUOTA_EXCEEDED`	403	L’upload supererebbe lo storage incluso.
`PREFIX_NOT_ALLOWED`	403	L’upload token è vincolato a un altro prefisso.
`UPGRADE_REQUIRED`	403	Un’opzione richiede un piano superiore. Il `message` indica quale.
`ACCOUNT_BLOCKED`	403	L’account è bloccato e non può archiviare file.
`INVALID_CONTENT_TYPE`	409	La richiesta non è `multipart/form-data`.
`OBJECT_ALREADY_EXISTS`	409	Il nome esiste già e `overwrite=false`.
`FILE_TOO_LARGE`	413	Oltre 100 MB, oppure oltre la dimensione consentita dalla regola o dal token.
`RATE_LIMITED` / `TOO_MANY_CONCURRENT_UPLOADS`	429	1 upload al secondo (Hobby e Standard), oppure 4 in corso.
`UPLOAD_FAILED`	500	Lo storage ha avuto un errore. Riprova.
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	Lo storage è temporaneamente non disponibile. Riprova.

Vedi Errori per l’elenco completo.

Vedi anche

SDK Blob: blob.put()

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./logo.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./logo.png')]), 'logo.png');

const params = new URLSearchParams({
  name: 'logo',
  prefix: 'images',
  security_hash: 'true',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('logo.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'},
        files={'file': ('logo.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "name": "logo",
        "prefix": "images",
        "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
        "replaced": false
    }
}

{
    "status": "success",
    "response": {
        "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "name": "2026-09",
        "prefix": "invoices",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "replaced": false
    }
}

Primi passi

Oggetti

Upload a blocchi

Account

Link di condivisione

S3

Carica un file su Blob Storage

Parametri

Limiti di frequenza e concorrenza

Tipi di file

Risposta

Errori

Vedi anche

​Parametri

​Limiti di frequenza e concorrenza

​Tipi di file

​Risposta

​Errori

​Vedi anche

Parametri

Limiti di frequenza e concorrenza

Tipi di file

Risposta

Errori

Vedi anche