Referencia de API
Utilice las operaciones API e interprete sus resultados
Lea los endpoints disponibles, las reglas de idempotencia, las respuestas de acciones en cola y los límites actuales en el seguimiento de operaciones.
En esta página
Antes de empezar
- Una sesión válida y, para cambios protegidos, su token CSRF.
- Identificadores tomados del catálogo actual o de respuestas autenticadas de API.
- Una clave de idempotencia única para cada pedido, retiro o acción de hardware.
Lea la cuenta antes de cambiarla
Usa los endpoints de lectura para confirmar la cuenta, el saldo y el recurso de destino. GET /api/v1/me devuelve el nombre de usuario, balanceUsd y el csrfToken de la sesión. Los identificadores de recursos son específicos de la cuenta; usa el identificador de servidor o red devuelto para la cuenta actual en lugar de copiar un valor de otro entorno.
El API actual es una interfaz de cuenta compacta, no una plataforma completa de trabajos asíncronos. Guarde las referencias de escrituras exitosas en sus propios registros. No hay un endpoint para listar cada pedido, inspeccionar una acción en cola específica o recuperar el estado de revisión más reciente de un retiro.
| Leer endpoint | Datos devueltos |
|---|---|
| GET /api/v1/ledger | Las últimas entradas del libro mayor de 100, las más recientes primero; sin contrato de paginación. |
| GET /api/v1/servers | Servidores no terminados, estado, región, paidThrough, graceUntil y autoRenew. |
| GET /api/v1/network | Direcciones asignadas, longitudes de prefijo, valores PTR e identificadores de servidor relacionados. |
| GET /api/health | Recuentos básicos de servicio y catálogo; sin garantía de cuenta o de salud del servidor físico. |
Utilice el endpoint de cambio correspondiente
Las acciones de servidor admitidas son reiniciar, power_off, reinstalar, mount_iso, kvm y rotate_root_password. Una URL ISO personalizada debe usar HTTPS público sin credenciales incrustadas. El plazo del pedido es semanal o mensual, representando siete o treinta días. El precio, los descuentos, los fondos y la capacidad son verificados por el servicio; no envíe un precio calculado por el cliente como autoridad.
| Punto final | Campos de solicitud y resultado |
|---|---|
| POST /api/v1/orders | configId, regionId, osId, plazo, cantidad; opcional sshPublicKey. Devuelve el id del pedido y ACEPTADO. |
| POST /api/v1/deposit-addresses | activo. Devuelve dirección, activo, red, confirmaciones requeridas y modo, o error de liquidación no disponible. |
| POST /api/v1/withdrawals | activo, destino, usd. Devuelve id y PENDING_REVIEW; el saldo se retiene. |
| POST /api/v1/servers/{id}/actions | acción; isoUrl para mount_iso. Devuelve el id de la acción y QUEUED. |
| PUT /api/v1/servers/{id}/ddos | modo: BASELINE o ADVANCED. Devuelve QUEUED o UNCHANGED y quoteRequired. |
| PUT /api/v1/network/{id}/rdns | ptr, o un valor vacío para borrarlo. Devuelve el valor PTR almacenado. |
Haga reintentos deliberados
Los pedidos, retiros, acciones de servidor y solicitudes DDoS requieren Idempotency-Key. Utilice 8–100 letras, números, guiones o guiones bajos, y asigne una clave nueva para cada operación distinta prevista. Conserve la clave original, el recurso y la carga útil antes de enviar para poder investigar una respuesta incierta.
Los pedidos pueden reproducir el resultado existente para la misma clave y solicitud normalizada; los detalles de pedido modificados producen un conflicto. Las repeticiones de acciones de servidor devuelven la acción existente cuando es compatible. Mantenga las claves de acción únicas en todos los servidores de la cuenta. Los retiros informan un conflicto cuando ya están registrados en lugar de devolver la solicitud original como un éxito.
POST /api/v1/servers/{serverId}/actions HTTP/1.1
Content-Type: application/json
x-csrf-token: <current-session-token>
Idempotency-Key: <unique-operation-key>
Cookie: <current-session-cookies>
{"action":"reboot"}Distinga la aceptación de la finalización
Una respuesta EN COLAd de 202 confirma que se registró una solicitud de hardware. No contiene una URL de KVM funcional, una contraseña de root de reemplazo ni prueba de que la máquina se reinició. Del mismo modo, ACCEPTED registra un pedido que entra en aprovisionamiento; PENDING_REVIEW registra un retiro que espera revisión del operador. Conserve el identificador devuelto al preguntar sobre la ejecución.
No hay una ruta de sondeo de estado de acciones en esta versión. Vuelva a leer los datos del servidor o de la red cuando corresponda y obtenga confirmación del operador para efectos físicos. Una preferencia de PTR o DDoS almacenada por sí sola no es una medición del DNS público ni de la protección de red en vivo.
Responda a fallas sin duplicar el trabajo
- Error de validación de 400: corrija los campos documentados antes de volver a enviar.
- 401 o 403: repara la autenticación de sesión o la verificación CSRF antes de reintentar.
- 404: verifique que el identificador del recurso pertenezca a la cuenta que inició sesión.
- 409: inspeccione el código de error; saldo insuficiente, capacidad agotada y conflictos de idempotencia requieren respuestas diferentes.
- 502 o 503 en depósitos: no se devolvió ninguna dirección nueva utilizable; no inicie una transferencia.
- Tiempo de espera agotado o respuesta ilegible: verifique los registros de cuenta disponibles y conserve los detalles de la solicitud original. No cree a ciegas una clave de operación nueva.