Enviar objeto de blob em uma única requisição

curl --request POST \
  --url https://blob.vertracloud.app/v1/objects \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://blob.vertracloud.app/v1/objects', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://blob.vertracloud.app/v1/objects"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://blob.vertracloud.app/v1/objects"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "response": {
    "id": "0b6f7c1e-3d2a-4f5b-9a8c-1d2e3f4a5b6c",
    "path": "images/logo.png",
    "size": 48213,
    "content_type": "image/png",
    "etag": "9b2cf535f27731c974343645a3085d39",
    "sha256": null,
    "visibility": "public",
    "url": "https://blob.vertracloud.dev/k7p2m9x4qa/images/logo.png",
    "cache_control": null,
    "content_disposition": "inline",
    "filename": null,
    "metadata": {},
    "expires_at": null,
    "created_at": "2026-10-14T12:00:00.000Z",
    "updated_at": "2026-10-14T12:00:00.000Z"
  }
}

POST

objects

Enviar objeto de blob em uma única requisição

curl --request POST \
  --url https://blob.vertracloud.app/v1/objects \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://blob.vertracloud.app/v1/objects', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://blob.vertracloud.app/v1/objects"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://blob.vertracloud.app/v1/objects"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "response": {
    "id": "0b6f7c1e-3d2a-4f5b-9a8c-1d2e3f4a5b6c",
    "path": "images/logo.png",
    "size": 48213,
    "content_type": "image/png",
    "etag": "9b2cf535f27731c974343645a3085d39",
    "sha256": null,
    "visibility": "public",
    "url": "https://blob.vertracloud.dev/k7p2m9x4qa/images/logo.png",
    "cache_control": null,
    "content_disposition": "inline",
    "filename": null,
    "metadata": {},
    "expires_at": null,
    "created_at": "2026-10-14T12:00:00.000Z",
    "updated_at": "2026-10-14T12:00:00.000Z"
  }
}

Envia um arquivo de até 100 MB em uma única requisição multipart/form-data e o armazena em path. Para arquivos maiores, use Iniciar um upload direto. Responde com 201 e o novo objeto. Escopo: blob:write. Aceita um token de upload. Token de upload: esta rota também aceita um token de upload (Authorization: Bearer vcup_...) no lugar de uma chave de API.

string

obrigatório

Caminho de destino na conta. De 1 a 1024 caracteres, até 16 segmentos de [A-Za-z0-9._ -] (de 1 a 255 caracteres cada), sem / no início ou no fim, sem // nem .., e é obrigatória uma extensão. Caminhos recusados retornam VALIDATION_ERROR; eles nunca são alterados em silêncio.

string

public ou private. Padrão private.

boolean

Substitui um objeto que já existe em path. Padrão false: um caminho ocupado retorna BLOB_OBJECT_ALREADY_EXISTS.

boolean

Quando path está ocupado, salva o arquivo como nome-1.ext, nome-2.ext e assim por diante (o primeiro nome livre), em vez de retornar BLOB_OBJECT_ALREADY_EXISTS. A resposta traz o path final. Padrão false. Não pode ser combinado com overwrite e não tem efeito com um token de upload que fixa o path.

boolean

Insere - seguido de 10 caracteres aleatórios em base 36 antes da extensão. Padrão false. Forçado para true em um token de upload sem path fixo.

string

immutable, max-age=<seconds> ou no-cache (Enterprise-26 ou superior). Padrão: nenhum valor definido.

string

inline ou attachment. Padrão: inline. Arquivos com extensão .html, .htm, .svg, .xml ou .xhtml são sempre servidos como attachment.

string

Nome sugerido quando o arquivo é baixado. Padrão: o último segmento de path.

string

Timestamp ISO 8601 de quando o objeto é excluído. Precisa ser pelo menos o mínimo do plano a partir de agora (7 dias, ou 1 hora no Enterprise-26 ou superior).

string

Objeto JSON, codificado em URL: até 5 chaves, cada uma [a-z0-9-]{1,64}, 512 bytes no total. Enterprise-12 ou superior.

string

SHA-256 do arquivo em hexadecimal. Se não bater, retorna BLOB_CHECKSUM_MISMATCH e nada é armazenado.

string

O ID do workspace, quando o blob pertence a um workspace. A chamada atua sobre o blob do proprietário do workspace e exige a permissão blob:read do workspace (blob:manage nas rotas que alteram dados). Deixe de fora para atuar sobre o seu próprio blob.

file

obrigatório

O arquivo, como única parte do multipart/form-data. Até 100 MB; vale o limite do plano.

Exemplo de requisição

curl -X POST "https://blob.vertracloud.app/v1/objects?path=images/logo.png&visibility=public" \
  -H "Authorization: Bearer $VERTRA_API_KEY" \
  -F "file=@./logo.png"

Resposta

object

O objeto armazenado. Responde com 201.

Mostrar propriedades

string

ID estável do objeto. Nunca muda, mesmo quando o caminho, a visibilidade ou a expiração mudam.

string

Caminho completo dentro da conta, por exemplo images/avatars/joao.png.

number

Tamanho em bytes.

string

Tipo MIME, derivado no servidor a partir da extensão do arquivo.

string

Entity tag do conteúdo armazenado.

string | null

SHA-256 do conteúdo em hexadecimal, quando o upload enviou um checksum. null caso contrário.

string

public (legível pela URL pública) ou private (precisa de um link temporário ou de um compartilhamento).

string | null

URL pública. null enquanto o objeto é privado.

string | null

immutable, max-age=<seconds> ou no-cache (no-cache exige Enterprise-26 ou superior). null significa o padrão.

string

inline (exibido pelo navegador) ou attachment (baixado). HTML, SVG e XML são sempre attachment.

string | null

Nome sugerido no download. null usa o último segmento de path.

object

Até 5 chaves, cada uma [a-z0-9-]{1,64}, 512 bytes no total. Enterprise-12 ou superior; {} nos demais planos.

string | null

Quando o objeto é excluído, em timestamp ISO 8601. null significa sem expiração.

string

Data de criação em ISO 8601.

string

Data da última alteração em ISO 8601.

{
  "response": {
    "id": "0b6f7c1e-3d2a-4f5b-9a8c-1d2e3f4a5b6c",
    "path": "images/logo.png",
    "size": 48213,
    "content_type": "image/png",
    "etag": "9b2cf535f27731c974343645a3085d39",
    "sha256": null,
    "visibility": "public",
    "url": "https://blob.vertracloud.dev/k7p2m9x4qa/images/logo.png",
    "cache_control": null,
    "content_disposition": "inline",
    "filename": null,
    "metadata": {},
    "expires_at": null,
    "created_at": "2026-10-14T12:00:00.000Z",
    "updated_at": "2026-10-14T12:00:00.000Z"
  }
}

Respostas de erro

string

O código de erro que indica o motivo da falha. Valores possíveis:

AUTH_TOKEN_MISSING (401): o cabeçalho Authorization não foi enviado.
API_KEY_INVALID (401): a chave de API não existe, foi revogada ou o segredo não confere.
API_KEY_SCOPE_DENIED (403): a chave não tem o escopo que esta rota exige (blob:read ou blob:write); details.required informa qual.
WORKSPACE_PERMISSION_DENIED (403): somente com workspace_id: você não é membro, ou o seu papel não tem a permissão de blob.
WORKSPACE_NOT_FOUND (404): somente com workspace_id: não existe workspace com esse ID, ou você não é membro.
BLOB_UPLOAD_TOKEN_INVALID (401): o token de upload não existe, expirou ou foi revogado (somente com token de upload).
BLOB_CHECKSUM_MISMATCH (400): o checksum_sha256 não confere com o arquivo. Nada foi armazenado.
VALIDATION_ERROR (400): um parâmetro de consulta falhou na validação, por exemplo um path inválido. details.path informa qual.
BLOB_OBJECT_ALREADY_EXISTS (409): path está ocupado e overwrite não é true.
BLOB_FILE_TOO_LARGE (413): o arquivo tem mais de 100 MB, o limite do plano para esta rota, ou o max_size da regra ou do token.
STORAGE_QUOTA_EXCEEDED (403): armazenar o arquivo ultrapassaria a cota de blob do plano.
BLOCKED_FILE_TYPE (422): a extensão está bloqueada, não é permitida pela regra da pasta ou pelo token, ou o arquivo é um executável.
BLOB_NAMESPACE_SUSPENDED (403): o armazenamento de blob da conta está suspenso, ou o plano expirou. Uploads e outras gravações são recusados desde o início do período de carência de 72 horas.
PLAN_RESTRICTED_FEATURE (403): metadata (abaixo do Enterprise-12) ou cache_control: no-cache (abaixo do Enterprise-26) não está incluído no plano.
BLOB_UPLOAD_TOKEN_CONSTRAINT (403): somente com token de upload: o caminho, a pasta ou outra opção fixada pelo token não confere com a requisição.
BLOB_UPLOAD_TOKEN_EXHAUSTED (401): somente com token de upload: ele já usou todos os seus usos.
RATE_LIMIT_EXCEEDED (429): abaixo do Enterprise-12, os uploads são limitados a 1 por segundo. details.retry_after informa a espera.

{
  "code": "AUTH_TOKEN_MISSING"
}

{
  "code": "API_KEY_SCOPE_DENIED"
}

{
  "code": "WORKSPACE_NOT_FOUND"
}

{
  "code": "BLOB_CHECKSUM_MISMATCH"
}

{
  "code": "BLOB_OBJECT_ALREADY_EXISTS"
}

{
  "code": "BLOB_FILE_TOO_LARGE"
}

{
  "code": "BLOCKED_FILE_TYPE"
}

{
  "code": "RATE_LIMIT_EXCEEDED"
}

Última modificação em 28 de outubro de 2026

Blob Storage

Referência da API do Blob

Enviar objeto de blob em uma única requisição

Exemplo de requisição

Resposta

Respostas de erro

​Exemplo de requisição

​Resposta

​Respostas de erro

Exemplo de requisição

Resposta

Respostas de erro