Object Storage

Crear un bucket

POST /v1/object-storage/buckets · scope objectstorage:write · reversible · idempotente

Devuelve el mismo recurso que GET /v1/object-storage/buckets/{bucket}. El alta del backend responde la fila cruda del registro —otra forma, con otro formato de fecha— así que se relee antes de contestar: cuesta una llamada y compra que el alta y la lectura devuelvan el mismo objeto.

curl https://api.truo.cloud/v1/object-storage/buckets \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"respaldos"}'

truo object-storage bucket create <name>

await truo.objectstorage.buckets.create({"name":"respaldos"});

truo_objectstorage({
  "action": "bucket_create"
})

operationId: objectstorage.buckets.create

Borrar un bucket

DELETE /v1/object-storage/buckets/{bucket} · scope objectstorage:write · destructiva — no tiene vuelta atras · idempotente

Un bucket con objetos no se borra: el request falla y no toca nada. ?purge=true lo borra con todo el contenido, y eso no se puede deshacer — no hay papelera ni versiones. Si querés saber cuántos objetos se van a perder, vaciálo primero con POST .../empty, que devuelve la cuenta.

curl https://api.truo.cloud/v1/object-storage/buckets/respaldos \
  -X DELETE \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo object-storage bucket delete respaldos

await truo.objectstorage.buckets.delete("respaldos");

truo_objectstorage({
  "action": "bucket_delete",
  "bucket": "respaldos"
})

operationId: objectstorage.buckets.delete

Vaciar un bucket

POST /v1/object-storage/buckets/{bucket}/empty · scope objectstorage:write · destructiva — no tiene vuelta atras · asincrona · idempotente

Borra todos los objetos y conserva el bucket con su configuración. No se puede deshacer. Sobre un bucket grande puede tardar: el borrado va objeto por objeto contra el almacenamiento.

curl https://api.truo.cloud/v1/object-storage/buckets/respaldos/empty \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo object-storage bucket empty respaldos

await truo.objectstorage.buckets.empty("respaldos");

truo_objectstorage({
  "action": "bucket_empty",
  "bucket": "respaldos"
})

operationId: objectstorage.buckets.empty

Obtener un bucket

GET /v1/object-storage/buckets/{bucket} · scope objectstorage:read

curl https://api.truo.cloud/v1/object-storage/buckets/respaldos \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo object-storage bucket get respaldos

await truo.objectstorage.buckets.get("respaldos");

truo_objectstorage({
  "action": "bucket_get",
  "bucket": "respaldos"
})

operationId: objectstorage.buckets.get

Listar los buckets

GET /v1/object-storage/buckets · scope objectstorage:read

Incluye los buckets creados directamente por el protocolo S3, que no tienen fila de registro: se listan igual —ocultarlos escondería datos que existen— con created_at en null y acceso privado.

curl https://api.truo.cloud/v1/object-storage/buckets \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo object-storage bucket list

await truo.objectstorage.buckets.list();

truo_objectstorage({
  "action": "bucket_list"
})

operationId: objectstorage.buckets.list

Métricas de un bucket

GET /v1/object-storage/buckets/{bucket}/metrics · scope objectstorage:read

Almacenamiento, egress y requests del rango pedido. Las series traen un punto por día UTC y vienen vacías mientras no haya datos, en vez de rellenarse con ceros que se confundirían con un día sin tráfico.

curl https://api.truo.cloud/v1/object-storage/buckets/respaldos/metrics \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo object-storage bucket metrics respaldos

await truo.objectstorage.buckets.metrics("respaldos");

truo_objectstorage({
  "action": "bucket_metrics",
  "bucket": "respaldos"
})

operationId: objectstorage.buckets.metrics

Cambiar la visibilidad de un bucket

PATCH /v1/object-storage/buckets/{bucket} · scope objectstorage:write · reversible · idempotente

Publicar el bucket le acuña una URL de lectura anónima (public_url) y la conserva si después se vuelve privado: republicar devuelve la misma URL, no una nueva.

curl https://api.truo.cloud/v1/object-storage/buckets/respaldos \
  -X PATCH \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"access":"private"}'

truo object-storage bucket update respaldos

await truo.objectstorage.buckets.update("respaldos", {"access":"private"});

truo_objectstorage({
  "action": "bucket_update",
  "bucket": "respaldos"
})

operationId: objectstorage.buckets.update

Emitir una llave de acceso

POST /v1/object-storage/keys · scope objectstorage:keys · reversible · idempotente

Es el único endpoint que devuelve secret_access_key, y lo devuelve una sola vez: no se guarda en claro de nuestro lado y no hay forma de recuperarlo después. Si se pierde, la salida es borrar la llave y emitir otra. Las llaves conviven: emitir una no revoca las anteriores. Acotá cada una a un bucket con scope para que perder una no comprometa el resto.

curl https://api.truo.cloud/v1/object-storage/keys \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"backups-produccion"}'

truo object-storage key create <name>

await truo.objectstorage.keys.create({"name":"backups-produccion"});

truo_objectstorage({
  "action": "key_create"
})

operationId: objectstorage.keys.create

Revocar una llave de acceso

DELETE /v1/object-storage/keys/{key_id} · scope objectstorage:keys · destructiva — no tiene vuelta atras · idempotente

La revocación es inmediata. Revocar una llave invalida también las URLs prefirmadas que se firmaron con ella, aunque no hayan expirado: la firma se valida contra la llave, y una llave revocada ya no existe. Es la única forma de cortar una URL prefirmada antes de tiempo.

curl https://api.truo.cloud/v1/object-storage/keys/AKIA7QF2K3M9XZ4NPRTV \
  -X DELETE \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo object-storage key delete AKIA7QF2K3M9XZ4NPRTV

await truo.objectstorage.keys.delete("AKIA7QF2K3M9XZ4NPRTV");

truo_objectstorage({
  "action": "key_delete",
  "keyId": "AKIA7QF2K3M9XZ4NPRTV"
})

operationId: objectstorage.keys.delete

Listar las llaves de acceso

GET /v1/object-storage/keys · scope objectstorage:read

Solo las activas, y nunca el secreto.

curl https://api.truo.cloud/v1/object-storage/keys \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo object-storage key list

await truo.objectstorage.keys.list();

truo_objectstorage({
  "action": "key_list"
})

operationId: objectstorage.keys.list

Borrar objetos

POST /v1/object-storage/buckets/{bucket}/objects/delete · scope objectstorage:write · destructiva — no tiene vuelta atras · idempotente

Borrado en lote por key. Es un POST y no un DELETE porque la lista de keys va en el cuerpo: un DELETE con body no lo mandan igual todos los clientes HTTP. No se puede deshacer. deleted puede ser menor que la cantidad de keys pedidas: las que no existían no cuentan.

curl https://api.truo.cloud/v1/object-storage/buckets/respaldos/objects/delete \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keys":["fotos/logo.png"]}'

truo object-storage object delete respaldos

await truo.objectstorage.objects.delete("respaldos", {"keys":["fotos/logo.png"]});

truo_objectstorage({
  "action": "object_delete",
  "bucket": "respaldos"
})

operationId: objectstorage.objects.delete

Listar objetos de un bucket

GET /v1/object-storage/buckets/{bucket}/objects · scope objectstorage:read

Un nivel a la vez, como un explorador de archivos: las entradas con is_folder: true son prefijos, y se navegan pasando su key como prefix. No acepta limit: el backend fija el tamaño de página (hasta 1000 entradas) y recortar acá perdería objetos en silencio al avanzar el cursor.

curl https://api.truo.cloud/v1/object-storage/buckets/respaldos/objects \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo object-storage object list respaldos

await truo.objectstorage.objects.list("respaldos");

truo_objectstorage({
  "action": "object_list",
  "bucket": "respaldos"
})

operationId: objectstorage.objects.list

Firmar una URL temporal

POST /v1/object-storage/buckets/{bucket}/presign · scope objectstorage:read · reversible

Devuelve un link que funciona sin credenciales hasta que expira. method: "GET" para descargar (requiere objectstorage:read), method: "PUT" para subir (requiere objectstorage:write). La URL es una credencial de portador: funciona para cualquiera que la tenga y la única forma de cortarla antes de que venza es revocar la llave S3 que la firmó. Pedí el TTL más corto que te sirva. Hereda además el alcance de esa llave: si está acotada a un bucket o es de solo lectura, la URL no puede más que ella.

curl https://api.truo.cloud/v1/object-storage/buckets/respaldos/presign \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"fotos/logo.png"}'

truo object-storage object presign respaldos <key>

await truo.objectstorage.objects.presign("respaldos", {"key":"fotos/logo.png"});

truo_objectstorage({
  "action": "object_presign",
  "bucket": "respaldos"
})

operationId: objectstorage.objects.presign

Obtener el Object Storage de la cuenta

GET /v1/object-storage · scope objectstorage:read

Uso, endpoint y estado. Es singleton por cuenta: no hay listado ni id que pasar. El almacenamiento y el conteo de objetos salen del último snapshot diario, no de un escaneo en vivo, así que un objeto recién subido puede tardar en reflejarse en los totales.

curl https://api.truo.cloud/v1/object-storage \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo object-storage get

await truo.objectstorage.tenant.get();

truo_objectstorage({
  "action": "get"
})

operationId: objectstorage.tenant.get