Cree un token de API y haga la primera llamada

Crea un token con el alcance más pequeño que funcione

Los tokens se crean en el panel bajo la cuenta y llevan alcances: read, write, billing. Un token con write puede pedir servidores, lo que significa que si se filtra, cuesta dinero. Dale a un script de monitoreo read y nada más.

Dos ajustes que vale la pena usar mientras estás ahí: una fecha de caducidad y una restricción de origen que fija el token al prefijo desde el que se ejecuta tu automatización. Ambos son opcionales. Ambos son baratos.

El valor se muestra una sola vez, porque almacenamos un hash de él en lugar del token. Perderlo significa crear otro.

export Paragon_TOKEN=...

Mejor que el historial de shell, en una máquina que ejecuta sin supervisión:

systemd-creds encrypt token.txt /etc/credstore.encrypted/paragon-token

La primera llamada

curl -s https://paragonvps.com/api/v1/account -H "Authorization: Bearer $Paragon_TOKEN" | jq .

Todo es JSON, todo vive bajo /api/v1, y cada respuesta lleva un encabezado request_id. Cítalo en un ticket y encontramos la llamada exacta en segundos, en lugar de preguntarte a qué hora fue.

curl -s https://paragonvps.com/api/v1/instances -H "Authorization: Bearer $Paragon_TOKEN" | jq -r '.[] | .id + " " + .hostname + " " + .site + " " + .state'

Pedir uno

curl -s -X POST https://paragonvps.com/api/v1/instances -H "Authorization: Bearer $Paragon_TOKEN" -H "Content-Type: application/json" -H "Idempotency-Key: 2026-07-16-edge-01" -d '{"plan":"r-8","site":"AMS-01","image":"debian-13","hostname":"edge-01","ssh_keys":["primary"]}'

Envía el encabezado Idempotency-Key. Reintentar un POST sin él es como la gente termina con dos servidores y una intención; la clave se recuerda durante veinticuatro horas y devuelve el resultado original en lugar de construir una segunda instancia. Los datos de usuario de cloud-init van en el mismo cuerpo, codificados en base64, bajo user_data_b64.

Un pedido carga contra tu saldo de cuenta cuando el saldo cubre el primer ciclo. De lo contrario, la respuesta lleva una factura y una dirección de pago, y la instancia aparece una vez que la factura se liquida.

Límites de velocidad y errores

Seiscientas solicitudes por minuto por token. Si lo superas, obtienes un 429 con un encabezado Retry-After, que está ahí para ser leído, en lugar de ser reemplazado por un sleep fijo en un bucle.

Los errores son JSON que llevan un code, un message legible para humanos y el request_id. El estado te da la clase: 400 enviaste algo incorrecto, 401 el token es inválido o ha sido revocado, 403 el token no tiene el alcance, 404 no existe o no es tuyo, 409 la instancia está en un estado que no puede hacer eso, y 5xx es nuestro.

Paginación y sondeo

Las colecciones toman ?page= y ?per_page= y devuelven un encabezado Link. Las operaciones largas te dan un trabajo en lugar de bloquear, lo que cubre aprovisionamiento, migración y restauración:

curl -s https://paragonvps.com/api/v1/jobs/<job-id> -H "Authorization: Bearer $Paragon_TOKEN" | jq -r .state

Sondea eso cada pocos segundos, o registra un webhook y deja de sondear por completo. Los webhooks están firmados; comprueba la firma antes de actuar sobre uno.

Revocación

Instantánea, desde el panel o con otro token:

curl -s -X DELETE https://paragonvps.com/api/v1/tokens/<token-id> -H "Authorization: Bearer $Paragon_TOKEN"

Las solicitudes en curso terminan y la siguiente obtiene un 401. Si sospechas que un token se ha filtrado, revoca primero e investiga después. Un token no puede cambiar tu correo de cuenta o tu segundo factor, pero ciertamente puede gastar dinero.

La referencia completa, cada endpoint y cada campo, está en /docs/api.