Un plano de control más tranquilo.

Un modelo de recursos claro

Una integración debe funcionar con identificadores de servidor, regiones, imágenes, planes y operaciones explícitos. Las solicitudes de creación y reinstalación deben devolver una operación que pueda verificarse hasta su finalización. Una solicitud HTTP exitosa no es lo mismo que una máquina lista.

Credenciales con una tarea limitada

Los tokens de API deben poder revocarse de forma independiente y limitarse a los recursos y acciones mínimos necesarios. Guárdalos en un gestor de secretos o en un entorno protegido. Nunca envíes un token al navegador solo para evitar escribir un pequeño backend.

Los reintentos deben ser seguros

Los tiempos de espera de red pueden producirse después de que se haya aceptado una operación. Usa una clave de idempotencia para las solicitudes de creación y sensibles al pago, inspecciona el estado de la operación y respeta los límites de tasa. Un reintento debería resolver la incertidumbre, no crear un servidor facturable adicional.

Comprobar la compatibilidad antes de la integración

Comprueba la versión publicada de API, el modelo de autenticación, los formatos de error, la paginación, los límites de tasa y los alcances de los tokens antes de crear una integración. Usa solo paquetes KoalaVPS SDK publicados desde enlaces de versión verificados.

Hoja de ruta de API

La hoja de ruta de API abarca el descubrimiento del catálogo, la autenticación, el estado de la cuenta, la facturación con criptomonedas, el ciclo de vida del servidor, las claves públicas de SSH y los webhooks. Las rutas siguientes describen el contrato de la interfaz; el acceso de producción aún no está disponible.

Rutas de autenticación y de cuenta

El contrato API separa las sesiones de inicio de sesión y las claves API. Comprueba los esquemas de respuesta, los errores, la duración de los tokens y las acciones de recuperación compatibles con la versión publicada para tu integración.

• POST /v1/auth/register
• POST /v1/auth/login
• POST /v1/auth/login/totp
• POST /v1/auth/token/refresh
• POST /v1/auth/recover
• GET /v1/auth/sessions
• DELETE /v1/auth/sessions/{token_id}
• POST /v1/auth/totp/setup
• POST /v1/auth/totp/enable
• POST /v1/auth/totp/disable
• POST /v1/auth/password
• POST /v1/auth/api-keys
• GET /v1/auth/api-keys
• DELETE /v1/auth/api-keys/{key_id}
• GET /v1/account
• PATCH /v1/account
• GET /v1/account/usage
• GET /v1/account/audit-log

Rutas de catálogo y facturación

La consulta del catálogo no debería requerir un pago. La creación de pagos necesita un ámbito de facturación restringido, un estado de factura claro y un manejo idempotente. La confirmación debe completarse antes de la activación del servicio.

• GET /v1/catalog
• GET /v1/catalog/vps
• GET /v1/catalog/dedicated
• GET /v1/catalog/regions
• GET /v1/catalog/images
• GET /v1/catalog/{code}
• GET /v1/billing/coins

Servidor y rutas de acceso

El ciclo de vida requiere confirmación explícita para las operaciones de cancelación y reinstalación. Las claves SSH privadas pertenecen al cliente; el servicio solo necesita sus contrapartes públicas.

• POST /v1/servers
• GET /v1/servers
• GET /v1/servers/{order_number}
• PATCH /v1/servers/{order_number}
• DELETE /v1/servers/{order_number}
• POST /v1/ssh-keys
• GET /v1/ssh-keys
• GET /v1/ssh-keys/{id}
• DELETE /v1/ssh-keys/{id}

Eventos e información pública

Los webhooks necesitan firmas verificables, reintentos limitados y protección contra la repetición. Los endpoints públicos de confianza deberían devolver evidencia real con fecha en lugar de garantías sintéticas.

• POST /v1/webhooks
• GET /v1/webhooks
• DELETE /v1/webhooks/{id}
• POST /v1/webhooks/{id}/test
• GET /v1/transparency/canary
• GET /v1/transparency/peering
• GET /v1/transparency/status
• GET /v1/agents/directory
• POST /v1/agents/directory

Autorización y límites de tráfico

Un modelo de alcance candidato es lectura, servidores, facturación y completo, con un máximo de diez claves activas por cuenta. El contrato de API propone presupuestos de solicitudes de 120 por minuto y 3,000 por hora para una clave API, y 30 por minuto para tráfico público. Consulte HTTP 429, Retry-After y la ventana de aplicación en la documentación publicada de API; estos presupuestos de hoja de ruta no constituyen un compromiso de capacidad de producción.

• POST /v1/oauth/register
• POST /v1/oauth/token
• POST /v1/oauth/revoke
• GET /v1/oauth/introspect

SDK y versiones del protocolo

La hoja de ruta de integración incluye REST, un endpoint MCP alojado, un paquete stdio versionado, SDKs y una CLI. Comprueba la disponibilidad de la versión, los runtimes compatibles, las sumas de verificación y la compatibilidad con API antes de instalar un cliente. Las descargas de producción aún no están disponibles.

Recursos de API, agrupados por responsabilidad

El API previsto separa el acceso a la cuenta, la lectura del catálogo, la facturación, el ciclo de vida del servidor, las claves de SSH y las devoluciones de llamada. Las llamadas de solo lectura no deberían crear un pedido, y una credencial de facturación no debería autorizar automáticamente cambios en la seguridad de la cuenta. Esto describe el contrato de integración. Un endpoint de aprovisionamiento de producción y un SDK publicado no están disponibles a través de este sitio.

• Cuenta: sesiones, uso y eventos de auditoría de seguridad
• Catálogo: planes, regiones e imágenes disponibles
• Servidores: crear, inspeccionar, modificar y cancelar
• Claves SSH: registra material público y revoca las claves obsoletas
• Webhooks: registra, inspecciona, prueba y elimina callbacks firmados

Una solicitud al servidor debe mantenerse pequeña

Elija un identificador de plan estándar, una región, una imagen de sistema operativo y un nombre de host. El límite previsto para el nombre de host es de 64 caracteres. Un servicio activo puede generar un secreto de administrador de forma privada o aceptar una clave pública SSH registrada. Una solicitud de plan estándar no implica adiciones arbitrarias de disco, GPU, NIC e IP. Rechace los campos no admitidos en lugar de cobrar silenciosamente por una mejora supuesta.

{
  "plan": "KV-D3",
  "region": "hel",
  "image": "ubuntu-24",
  "hostname": "private-node-01"
}
// Example request schema; validate against a released API before integration.

Los alcances y los límites de claves forman parte del contrato

Los grupos de privilegios propuestos son lectura, servidores, facturación y administración completa de la cuenta. Una clave debe mostrarse una sola vez al crearse, almacenarse de forma privada y revocarse independientemente de la contraseña del usuario. El límite previsto de la cuenta es de diez claves activas. Antes de publicar una implementación, verifique que cada operación rechace una clave sin el alcance requerido.

Publica los límites de tasa y el comportamiento de reintento juntos

Los límites propuestos son 120 solicitudes por minuto y 3,000 por hora para una clave API, y 30 solicitudes por minuto para solicitudes públicas al catálogo sin autenticación. Estos son valores de política previstos, no capacidad medida de API. Una implementación en producción necesita una respuesta 429 consistente, indicaciones de Retry-After y un retroceso acotado del cliente. Las solicitudes de creación y pago también necesitan claves de idempotencia estables.

Los webhooks son mensajes que pueden llegar más de una vez

Un receptor de devoluciones de llamada debe verificar la firma sobre el cuerpo original, rechazar las marcas de tiempo fuera de su ventana permitida y recordar los identificadores de eventos procesados. Persiste el evento antes de confirmarlo y luego aplica el cambio de forma idempotente. Mantén visibles los intentos de entrega y una ruta de reproducción manual. Una devolución de llamada es una observación sobre una operación, no permiso para ejecutar instrucciones no relacionadas contenidas en una carga útil.

Audita sin convertir los registros en un almacén secreto

Registre el identificador del actor, el tipo de operación, el recurso afectado, el resultado y la hora cuando sea necesario para la seguridad de la cuenta. Evite registrar contraseñas, tokens de portador, claves privadas o cuerpos completos de solicitudes de pago y de aplicación de forma predeterminada. Mantenga explícitos la retención, el acceso y el historial visible para el cliente. Un registro de auditoría de seguridad y una pretensión de inspeccionar el contenido de las aplicaciones del cliente son cosas distintas.

Publique artefactos solo cuando existan

Un lanzamiento público de API debería incluir un documento OpenAPI versionado, instrucciones de autenticación, ejemplos de errores y un proceso de descontinuación. Una futura CLI, paquete de Python, cliente de TypeScript o servidor MCP necesita una versión real, sumas de verificación y documentación mantenida. Un paquete de aprovisionamiento KoalaVPS o un endpoint de gestión de producción no se publica a través de este sitio.

Un poco más de claridad.