Subir un objeto blob en una sola petición

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

Subir un objeto blob en una sola petición

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

Sube un archivo de hasta 100 MB en una sola petición multipart/form-data y lo guarda en path. Para archivos más grandes, usa Iniciar una subida directa. Responde con 201 y el objeto nuevo. Ámbito: blob:write. Acepta un token de subida. Token de subida: esta ruta también acepta un token de subida (Authorization: Bearer vcup_...) en lugar de una clave de API.

string

requerido

Ruta de destino en la cuenta. De 1 a 1024 caracteres, hasta 16 segmentos de [A-Za-z0-9._ -] (de 1 a 255 caracteres cada uno), sin / al principio ni al final, sin // ni .., y con una extensión obligatoria. Las rutas rechazadas devuelven VALIDATION_ERROR; nunca se cambian en silencio.

string

public o private. Por defecto private.

boolean

Reemplaza un objeto que ya esté en path. Por defecto false: una ruta ocupada devuelve BLOB_OBJECT_ALREADY_EXISTS.

boolean

Cuando path está ocupada, guarda el archivo como nombre-1.ext, nombre-2.ext y así sucesivamente (el primer nombre libre) en lugar de devolver BLOB_OBJECT_ALREADY_EXISTS. La respuesta incluye el path final. Por defecto false. No se puede combinar con overwrite, y no tiene efecto con un token de subida que fija el path.

boolean

Inserta - seguido de 10 caracteres aleatorios en base 36 antes de la extensión. Por defecto false. Se fuerza a true para un token de subida sin path fijo.

string

immutable, max-age=<seconds> o no-cache (Enterprise-26 o superior). Por defecto: sin valor definido.

string

inline o attachment. Por defecto: inline. Los archivos que terminan en .html, .htm, .svg, .xml o .xhtml se sirven siempre como attachment.

string

Nombre sugerido al descargar el archivo. Por defecto: el último segmento de path.

string

Marca de tiempo ISO 8601 de cuándo se elimina el objeto. Debe ser como mínimo el plazo mínimo del plan desde ahora (7 días, o 1 hora en Enterprise-26 o superior).

string

Objeto JSON, codificado en URL: hasta 5 claves, cada una [a-z0-9-]{1,64}, 512 bytes en total. Enterprise-12 o superior.

string

SHA-256 del archivo en hexadecimal. Si no coincide, devuelve BLOB_CHECKSUM_MISMATCH y no se guarda nada.

string

El ID del workspace, cuando el blob pertenece a un workspace. La petición actúa sobre el blob del propietario del workspace y necesita el permiso blob:read del workspace (blob:manage en las rutas que modifican datos). Omítelo para actuar sobre tu propio blob.

file

requerido

El archivo, como única parte de multipart/form-data. Hasta 100 MB; se aplica el límite del plan.

Ejemplo de petición

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"

Respuesta

object

El objeto guardado. Responde con 201.

Mostrar propiedades

string

ID estable del objeto. Nunca cambia, aunque cambien la ruta, la visibilidad o la caducidad.

string

Ruta completa dentro de la cuenta, por ejemplo images/avatars/joao.png.

number

Tamaño en bytes.

string

Tipo MIME, derivado en el servidor a partir de la extensión del archivo.

string

Etiqueta de entidad del contenido almacenado.

string | null

SHA-256 del contenido en hexadecimal, cuando la subida envió un checksum. null en otro caso.

string

public (se puede leer mediante su URL pública) o private (necesita un enlace temporal o un enlace para compartir).

string | null

URL pública. null mientras el objeto sea privado.

string | null

immutable, max-age=<seconds> o no-cache (no-cache requiere Enterprise-26 o superior). null significa el valor por defecto.

string

inline (lo muestra el navegador) o attachment (se descarga). HTML, SVG y XML siempre son attachment.

string | null

Nombre sugerido al descargar. null usa el último segmento de path.

object

Hasta 5 claves, cada una [a-z0-9-]{1,64}, 512 bytes en total. Enterprise-12 o superior; {} en otros planes.

string | null

Cuándo se elimina el objeto, como marca de tiempo ISO 8601. null significa que no caduca.

string

Fecha de creación en ISO 8601.

string

Fecha en ISO 8601 del último cambio.

{
  "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"
  }
}

Respuestas de error

string

El código de error que indica el motivo del fallo. Valores posibles:

AUTH_TOKEN_MISSING (401): No se envió la cabecera Authorization.
API_KEY_INVALID (401): La clave de API no existe, fue revocada o su secreto no coincide.
API_KEY_SCOPE_DENIED (403): La clave no tiene el ámbito que necesita esta ruta (blob:read o blob:write); details.required lo indica.
WORKSPACE_PERMISSION_DENIED (403): Solo con workspace_id: no eres miembro, o tu rol no tiene el permiso de blob.
WORKSPACE_NOT_FOUND (404): Solo con workspace_id: no existe un workspace con ese ID, o no eres miembro.
BLOB_UPLOAD_TOKEN_INVALID (401): El token de subida no existe, caducó o fue revocado (solo con un token de subida).
BLOB_CHECKSUM_MISMATCH (400): El checksum_sha256 no coincide con el archivo. No se guardó nada.
VALIDATION_ERROR (400): Un parámetro de la consulta no superó la validación, por ejemplo un path no válido. details.path lo indica.
BLOB_OBJECT_ALREADY_EXISTS (409): path está ocupada y overwrite no es true.
BLOB_FILE_TOO_LARGE (413): El archivo supera los 100 MB, el límite del plan para esta ruta, o el max_size de la regla o del token.
STORAGE_QUOTA_EXCEEDED (403): Guardar el archivo superaría la cuota de blob del plan.
BLOCKED_FILE_TYPE (422): La extensión está bloqueada, no la permite la regla de carpeta o el token, o el archivo es un ejecutable.
BLOB_NAMESPACE_SUSPENDED (403): El almacenamiento de blob de la cuenta está suspendido, o su plan expiró. Las subidas y otras escrituras se rechazan desde el inicio del periodo de gracia de 72 horas.
PLAN_RESTRICTED_FEATURE (403): metadata (por debajo de Enterprise-12) o cache_control: no-cache (por debajo de Enterprise-26) no está incluido en el plan.
BLOB_UPLOAD_TOKEN_CONSTRAINT (403): Solo con un token de subida: la ruta, la carpeta u otra opción que fija el token no coincide con la petición.
BLOB_UPLOAD_TOKEN_EXHAUSTED (401): Solo con un token de subida: ya usó todas sus subidas.
RATE_LIMIT_EXCEEDED (429): Por debajo de Enterprise-12, las subidas están limitadas a 1 por segundo. details.retry_after indica la 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 modificación el 28 de octubre de 2026

Blob Storage

Referencia de la API de Blob

Subir un objeto blob en una sola petición

Ejemplo de petición

Respuesta

Respuestas de error

​Ejemplo de petición

​Respuesta

​Respuestas de error

Ejemplo de petición

Respuesta

Respuestas de error