# TruoCloud

> API publica para operar infraestructura cloud: VPS, DNS, bases de datos administradas,
> contenedores, balanceadores, Object Storage y Mail Gateway.

Base: https://api.truo.cloud/v1 · OpenAPI: https://api.truo.cloud/v1/openapi.json
Autenticacion: `Authorization: Bearer tc_live_...` (API key con scopes).

## Como leer las respuestas
- Recurso: `{ "object": "vps", "id": "svc_10432", ... }` — sin envoltorio.
- Coleccion: `{ "object": "list", "data": [...], "has_more": true, "next_cursor": "..." }`.
  El cursor es **opaco**: no lo construyas ni lo parsees.
- Error (cualquier >=400): `{ "error": { "type", "code", "message", "param", "request_id" } }`.
  Ramifica por `code`, nunca por el texto de `message`.
- Lo que tarda devuelve `202` + un objeto `operation`: hay que consultar `/v1/operations/{id}`
  hasta `succeeded` o `failed`.

## Reglas
- Toda mutacion acepta `Idempotency-Key`. Usala: un reintento sin ella crea dos veces.
- Un servicio que no existe **o que tu credencial no puede ver** devuelve 404, nunca 403.
  Un 403 confirmaria que existe.
- Los ids llevan prefijo tipado (`svc_10432`). Se acepta el numero pelado, se devuelve el prefijado.

## Documentacion
- [Introduccion](https://docs.truo.cloud/)
- [Autenticacion](https://docs.truo.cloud/empezar/autenticacion/)
- [El contrato](https://docs.truo.cloud/empezar/contrato/)
- [Errores](https://docs.truo.cloud/errores/)
- [Limites de uso](https://docs.truo.cloud/limites/)
- [Politica de deprecacion](https://docs.truo.cloud/deprecation/)
- [Para agentes de IA](https://docs.truo.cloud/agentes/)

## Operaciones (103)

### Meta
- `meta.capabilities` — GET /v1/meta/capabilities: Qué soporta esta instancia de la API

### Account
- `account.get` — GET /v1/account (scope `account:read`): Obtener la cuenta y la credencial actual

### Services
- `services.get` — GET /v1/services/{id} (scope `services:read`): Obtener un servicio
- `services.list` — GET /v1/services (scope `services:read`): Listar los servicios de la cuenta

### VPS
- `vps.backups.create` — POST /v1/vps/{id}/backups (scope `vps:write`) · asincrona: Crear un backup
- `vps.backups.delete` — DELETE /v1/vps/{id}/backups/{backup_id} (scope `vps:write`) ⚠️ destructiva: Borrar un backup
- `vps.backups.list` — GET /v1/vps/{id}/backups (scope `vps:read`): Backups del VPS
- `vps.backups.restore` — POST /v1/vps/{id}/backups/{backup_id}/restore (scope `vps:write`) ⚠️ destructiva · asincrona: Restaurar un backup
- `vps.config.get` — GET /v1/vps/{id}/config (scope `vps:read`): Configuración de la máquina
- `vps.console.create` — POST /v1/vps/{id}/console (scope `vps:console`): Abrir una consola
- `vps.get` — GET /v1/vps/{id} (scope `vps:read`): Obtener un VPS con su estado real
- `vps.ips.list` — GET /v1/vps/{id}/ips (scope `vps:read`): IPs asignadas al VPS
- `vps.list` — GET /v1/vps (scope `vps:read`): Listar los VPS de la cuenta
- `vps.metrics.list` — GET /v1/vps/{id}/metrics (scope `vps:read`): Serie de uso de CPU, memoria, disco y red
- `vps.power` — POST /v1/vps/{id}/power (scope `vps:power`) · asincrona: Encender, apagar o reiniciar
- `vps.reinstall` — POST /v1/vps/{id}/reinstall (scope `vps:write`) ⚠️ destructiva · asincrona: Reinstalar el sistema operativo
- `vps.templates.list` — GET /v1/vps/{id}/templates (scope `vps:read`): Sistemas operativos disponibles para reinstalar
- `vps.update` — PATCH /v1/vps/{id} (scope `vps:write`): Renombrar un VPS

### DNS
- `dns.records.delete` — DELETE /v1/dns/zones/{zone}/records/{name}/{type} (scope `dns:write`) ⚠️ destructiva: Borrar un RRset
- `dns.records.get` — GET /v1/dns/zones/{zone}/records/{name}/{type} (scope `dns:read`): Obtener un RRset
- `dns.records.list` — GET /v1/dns/zones/{zone}/records (scope `dns:read`): Listar los registros de una zona
- `dns.records.patch` — PATCH /v1/dns/zones/{zone}/records (scope `dns:write`) ⚠️ destructiva: Aplicar varios cambios a la vez
- `dns.records.put` — PUT /v1/dns/zones/{zone}/records/{name}/{type} (scope `dns:write`): Crear o reemplazar un RRset
- `dns.zones.export` — GET /v1/dns/zones/{zone}/export (scope `dns:read`): Exportar la zona en formato BIND
- `dns.zones.get` — GET /v1/dns/zones/{zone} (scope `dns:read`): Obtener una zona
- `dns.zones.list` — GET /v1/dns/zones (scope `dns:read`): Listar las zonas DNS de la cuenta

### DBaaS
- `dbaas.backups.create` — POST /v1/dbaas/{id}/backups (scope `dbaas:write`) · asincrona: Crear un backup
- `dbaas.backups.list` — GET /v1/dbaas/{id}/backups (scope `dbaas:read`): Backups del servicio
- `dbaas.connection.get` — GET /v1/dbaas/{id}/connection (scope `dbaas:read`): Datos de conexión, sin la credencial
- `dbaas.credentials.create` — POST /v1/dbaas/{id}/credentials (scope `dbaas:credentials`): Revelar la credencial de administración
- `dbaas.databases.create` — POST /v1/dbaas/{id}/databases (scope `dbaas:write`): Crear una base
- `dbaas.databases.delete` — DELETE /v1/dbaas/{id}/databases/{name} (scope `dbaas:write`) ⚠️ destructiva: Borrar una base
- `dbaas.databases.list` — GET /v1/dbaas/{id}/databases (scope `dbaas:read`): Listar las bases del servicio
- `dbaas.instances.get` — GET /v1/dbaas/{id} (scope `dbaas:read`): Obtener una base de datos con su estado real
- `dbaas.instances.list` — GET /v1/dbaas (scope `dbaas:read`): Listar las bases de datos gestionadas de la cuenta
- `dbaas.instances.restart` — POST /v1/dbaas/{id}/restart (scope `dbaas:write`): Reiniciar el motor
- `dbaas.logs.get` — GET /v1/dbaas/{id}/logs (scope `dbaas:read`): Últimas líneas del log del motor
- `dbaas.stats.get` — GET /v1/dbaas/{id}/stats (scope `dbaas:read`): Métricas de la instancia
- `dbaas.users.create` — POST /v1/dbaas/{id}/users (scope `dbaas:write`): Crear un usuario
- `dbaas.users.delete` — DELETE /v1/dbaas/{id}/users/{username} (scope `dbaas:write`) ⚠️ destructiva: Borrar un usuario
- `dbaas.users.list` — GET /v1/dbaas/{id}/users (scope `dbaas:read`): Listar los usuarios del motor
- `dbaas.users.set_password` — POST /v1/dbaas/{id}/users/{username}/password (scope `dbaas:write`): Cambiar la password de un usuario

### CaaS
- `caas.apps.create` — POST /v1/caas/{id}/apps (scope `caas:write`): Crear una app
- `caas.apps.delete` — DELETE /v1/caas/{id}/apps/{app_id} (scope `caas:write`) ⚠️ destructiva: Borrar una app
- `caas.apps.deploy` — POST /v1/caas/{id}/apps/{app_id}/deploy (scope `caas:deploy`) · asincrona: Desplegar una app
- `caas.apps.get` — GET /v1/caas/{id}/apps/{app_id} (scope `caas:read`): Obtener una app
- `caas.apps.list` — GET /v1/caas/{id}/apps (scope `caas:read`): Listar las apps del servicio
- `caas.apps.logs` — GET /v1/caas/{id}/apps/{app_id}/logs (scope `caas:read`): Logs de una app
- `caas.apps.restart` — POST /v1/caas/{id}/apps/{app_id}/restart (scope `caas:write`): Reiniciar una app
- `caas.databases.create` — POST /v1/caas/{id}/databases (scope `caas:write`): Crear una base de datos
- `caas.databases.list` — GET /v1/caas/{id}/databases (scope `caas:read`): Bases de datos del servicio
- `caas.deployments.list` — GET /v1/caas/{id}/apps/{app_id}/deployments (scope `caas:read`): Historial de despliegues de una app
- `caas.domains.create` — POST /v1/caas/{id}/apps/{app_id}/domains (scope `caas:write`): Agregar un dominio a una app
- `caas.domains.delete` — DELETE /v1/caas/{id}/apps/{app_id}/domains/{host} (scope `caas:write`) ⚠️ destructiva: Quitar un dominio de una app
- `caas.domains.list` — GET /v1/caas/{id}/apps/{app_id}/domains (scope `caas:read`): Dominios de una app
- `caas.env.list` — GET /v1/caas/{id}/apps/{app_id}/env (scope `caas:read`): Nombres de las variables de entorno
- `caas.env.replace` — PUT /v1/caas/{id}/apps/{app_id}/env (scope `caas:write`) ⚠️ destructiva: Reemplazar las variables de entorno
- `caas.instances.get` — GET /v1/caas/{id} (scope `caas:read`): Obtener un servicio CaaS con su estado real
- `caas.instances.list` — GET /v1/caas (scope `caas:read`): Listar los servicios CaaS de la cuenta

### Load Balancer
- `lb.backends.create` — POST /v1/load-balancers/{id}/backends (scope `lb:write`): Agregar un destino a un listener
- `lb.backends.delete` — DELETE /v1/load-balancers/{id}/backends/{listener}/{ip}/{port} (scope `lb:write`) ⚠️ destructiva: Quitar un destino de un listener
- `lb.backends.list` — GET /v1/load-balancers/{id}/backends (scope `lb:read`): Listar los destinos
- `lb.instances.get` — GET /v1/load-balancers/{id} (scope `lb:read`): Obtener un load balancer con su estado real
- `lb.instances.list` — GET /v1/load-balancers (scope `lb:read`): Listar los load balancers de la cuenta
- `lb.listeners.list` — GET /v1/load-balancers/{id}/listeners (scope `lb:read`): Listar los listeners
- `lb.listeners.replace` — PUT /v1/load-balancers/{id}/listeners (scope `lb:write`) ⚠️ destructiva: Reemplazar la configuración de listeners
- `lb.stats.get` — GET /v1/load-balancers/{id}/stats (scope `lb:read`): Estado y tráfico por listener

### Object Storage
- `objectstorage.buckets.create` — POST /v1/object-storage/buckets (scope `objectstorage:write`): Crear un bucket
- `objectstorage.buckets.delete` — DELETE /v1/object-storage/buckets/{bucket} (scope `objectstorage:write`) ⚠️ destructiva: Borrar un bucket
- `objectstorage.buckets.empty` — POST /v1/object-storage/buckets/{bucket}/empty (scope `objectstorage:write`) ⚠️ destructiva · asincrona: Vaciar un bucket
- `objectstorage.buckets.get` — GET /v1/object-storage/buckets/{bucket} (scope `objectstorage:read`): Obtener un bucket
- `objectstorage.buckets.list` — GET /v1/object-storage/buckets (scope `objectstorage:read`): Listar los buckets
- `objectstorage.buckets.metrics` — GET /v1/object-storage/buckets/{bucket}/metrics (scope `objectstorage:read`): Métricas de un bucket
- `objectstorage.buckets.update` — PATCH /v1/object-storage/buckets/{bucket} (scope `objectstorage:write`): Cambiar la visibilidad de un bucket
- `objectstorage.keys.create` — POST /v1/object-storage/keys (scope `objectstorage:keys`): Emitir una llave de acceso
- `objectstorage.keys.delete` — DELETE /v1/object-storage/keys/{key_id} (scope `objectstorage:keys`) ⚠️ destructiva: Revocar una llave de acceso
- `objectstorage.keys.list` — GET /v1/object-storage/keys (scope `objectstorage:read`): Listar las llaves de acceso
- `objectstorage.objects.delete` — POST /v1/object-storage/buckets/{bucket}/objects/delete (scope `objectstorage:write`) ⚠️ destructiva: Borrar objetos
- `objectstorage.objects.list` — GET /v1/object-storage/buckets/{bucket}/objects (scope `objectstorage:read`): Listar objetos de un bucket
- `objectstorage.objects.presign` — POST /v1/object-storage/buckets/{bucket}/presign (scope `objectstorage:read`): Firmar una URL temporal
- `objectstorage.tenant.get` — GET /v1/object-storage (scope `objectstorage:read`): Obtener el Object Storage de la cuenta

### Mail Gateway
- `mailgateway.domains.create` — POST /v1/mail-gateway/domains (scope `mailgateway:write`): Agregar un dominio de envío
- `mailgateway.domains.delete` — DELETE /v1/mail-gateway/domains/{domain} (scope `mailgateway:write`) ⚠️ destructiva: Quitar un dominio de envío
- `mailgateway.domains.list` — GET /v1/mail-gateway/domains (scope `mailgateway:read`): Listar los dominios de envío
- `mailgateway.domains.verify` — POST /v1/mail-gateway/domains/{domain}/verify (scope `mailgateway:write`): Consultar la verificación de un dominio
- `mailgateway.keys.create` — POST /v1/mail-gateway/keys (scope `mailgateway:send`): Crear una API key de envío
- `mailgateway.keys.delete` — DELETE /v1/mail-gateway/keys/{key_id} (scope `mailgateway:write`) ⚠️ destructiva: Revocar una API key de envío
- `mailgateway.keys.list` — GET /v1/mail-gateway/keys (scope `mailgateway:read`): Listar las API keys de envío
- `mailgateway.messages.list` — GET /v1/mail-gateway/messages (scope `mailgateway:read`): Listar los mensajes enviados
- `mailgateway.metrics.get` — GET /v1/mail-gateway/metrics (scope `mailgateway:read`): Métricas de entrega y reputación
- `mailgateway.smtp.get` — GET /v1/mail-gateway/smtp (scope `mailgateway:read`): Ver la configuración SMTP
- `mailgateway.smtp.reveal` — POST /v1/mail-gateway/smtp (scope `mailgateway:send`): Revelar la password SMTP
- `mailgateway.smtp.rotate` — POST /v1/mail-gateway/smtp/rotate (scope `mailgateway:send`) ⚠️ destructiva: Rotar la credencial SMTP
- `mailgateway.tenant.get` — GET /v1/mail-gateway (scope `mailgateway:read`): Obtener el Mail Gateway de la cuenta
- `mailgateway.usage.get` — GET /v1/mail-gateway/usage (scope `mailgateway:read`): Uso del mes en curso

### Operations
- `operations.get` — GET /v1/operations/{id} (scope `operations:read`): Estado de una operación
- `operations.list` — GET /v1/operations (scope `operations:read`): Listar operaciones recientes de la cuenta

### API Keys
- `apiKeys.create` — POST /v1/api-keys (scope `apikeys:write`): Crear una API key
- `apiKeys.get` — GET /v1/api-keys/{id} (scope `apikeys:read`): Obtener una API key
- `apiKeys.list` — GET /v1/api-keys (scope `apikeys:read`): Listar las API keys de la cuenta
- `apiKeys.revoke` — POST /v1/api-keys/{id}/revoke (scope `apikeys:write`) ⚠️ destructiva: Revocar una API key
- `apiKeys.update` — PATCH /v1/api-keys/{id} (scope `apikeys:write`): Modificar una API key

### Audit
- `auditLogs.list` — GET /v1/audit-logs (scope `audit:read`): Listar la actividad de API de la cuenta