Pular para o conteúdo principal
POST
curl
O envio tem três passos:
1

Peça o envio

Mande o nome (path), o tamanho exato em bytes (sizeBytes, até o teto do plano), o tipo (contentType) e, se quiser um link fixo, visibility: "public". A Cube confere o limite, a cota do plano e a regra da pasta e devolve o link em upload.url.
2

Mande o arquivo no link

PUT no upload.url com o Content-Type de upload.headers e o arquivo no corpo. O link só aceita esse tamanho e esse tipo, e o arquivo não passa pelo servidor dos projetos.
3

Confirme

Chame Confirmar o envio. Só então o arquivo aparece na lista; o público já vem com o publicUrl, que não vence.
Não mande a chave de API no PUT: o link já traz a autorização, e ele é só para esse arquivo.

Opções do envio

O Blob é dos planos pagos (Block 5 GB, Stack 10 GB, Tower 25 GB, Fortress 50 GB, Monolith 100 GB, Empresas de 200 GB a 6.400 GB), com até 1/5 da cota por arquivo, no máximo 4 GB (Block 1 GB, Stack 2 GB, do Tower em diante 4 GB). O arquivo sobe do jeito que você mandar (quem envia pelo painel tem as fotos reduzidas no navegador antes). Um envio que você desistir de fazer se cancela com Apagar; o tamanho dele segue reservado até o link de envio vencer (15 minutos). O arquivo que chega pelo link e não é confirmado em 10 minutos é removido.

Erros comuns

Todos os códigos, com o formato do erro, em Códigos de erro.

Autorizações

Authorization
string
header
obrigatório

Chave de API da Cube (cube_…), criada no painel em Chaves de API. Mande como Authorization: Bearer cube_…. Cada rota pede uma permissão da chave (o escopo no security da rota, como files:write); sem ela, 403 insufficient_scope com o requiredScope. Veja Chaves de API.

Scopes

blob:write

Corpo

application/json
path
string
obrigatório

O nome, com pastas por /: até 1024 bytes, sem / no começo ou no fim, sem pasta vazia, . ou .., sem \.

sizeBytes
integer
obrigatório

O tamanho exato do arquivo, até o teto do plano (maxObjectBytes): o link só aceita esse tamanho.

Intervalo obrigatório: 0 <= x <= 4294967296
contentType
string

O tipo (image/png), sem parâmetros; padrão application/octet-stream. O link só aceita esse tipo.

visibility
enum<string>

public dá ao arquivo pronto um link fixo que não vence (publicUrl). Sem ele, vale a visibilidade padrão da regra da pasta e, sem regra, private.

Opções disponíveis:
public,
private
expiresAt
string | null

Quando o arquivo vence (ISO, de 1 minuto a 10 anos). null: nunca vence. Sem o campo, vale a expiração padrão da regra da pasta.

isDownloadForced
boolean
padrão:false

O link sempre baixa como anexo, até a imagem.

shouldOverwrite
boolean
padrão:true

false: com um arquivo de mesmo nome, responde 409 object_exists e nada muda.

shouldAddRandomSuffix
boolean
padrão:false

Põe 8 letras e números aleatórios antes da extensão (logo-k3j9x2qa.png).

isMultipart
boolean
padrão:false

Envio em partes de 16 MB, que pode continuar por 24 horas (pelo menos 1 byte).

Resposta

O envio foi reservado: mande o arquivo no link e confirme.

object
object
obrigatório
upload
object
obrigatório