Solicitar acceso

Referencia de la API

Todos los endpoints públicos de la API de Node Lodge: autenticación, parámetros, cuerpos de solicitud y un ejemplo curl para cada uno.

La descripción legible por máquina de esta API está en https://nodelodge.com/v1/openapi.json (OpenAPI 3.1). Impórtela en su cliente HTTP o genere un cliente desde ella.

Autenticación

Cada endpoint indica cómo se autentica:

  • Una clave de API: envíe Authorization: Bearer $NODELODGE_API_KEY. Cree las claves en la consola, en Keys. Consulte la guía rápida de la API para los alcances.
  • Una sesión de consola: los endpoints que usa la consola. Inicie sesión con POST /v1/auth/login y conserve la cookie de sesión (-c cookies.txt), luego envíela (-b cookies.txt). Con la autenticación de dos factores activada, complete el inicio de sesión con POST /v1/auth/mfa/verify, enviando el mismo archivo de cookies con -b cookies.txt -c cookies.txt.
  • Ninguna: endpoints públicos.

Una clave de API en un endpoint que requiere una sesión de consola responde 403 API_KEY_NOT_ALLOWED. Las solicitudes y las respuestas son JSON. Los errores tienen una sola forma: { "error": { "code": "...", "message": "..." } }.

Inicio de sesión y cuenta

POST /v1/account/close

Cierra su cuenta y su organización.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
password cadena Sí hasta 128 caracteres
acceptCreditLoss booleano No 
curl -X POST "https://nodelodge.com/v1/account/close" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"password":"correct horse battery staple"}'

GET /v1/account/closure

Muestra qué implicaría ahora el cierre de su cuenta y qué lo impide.

Autenticación: una sesión de consola.

curl "https://nodelodge.com/v1/account/closure" \
  -b cookies.txt

GET /v1/account/credit

Lee el crédito prepago de su organización y sus movimientos.

Autenticación: una sesión de consola.

curl "https://nodelodge.com/v1/account/credit" \
  -b cookies.txt

GET /v1/account/funds

Lee lo que su organización puede gastar ahora: una nueva sesión se admite según el importe disponible.

Autenticación: una clave de API con el alcance billing:read o una sesión de consola.

curl "https://nodelodge.com/v1/account/funds" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

POST /v1/account/terms

Acepta las condiciones de uso, en la versión que indica GET /v1/client-config.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
version cadena Sí hasta 20 caracteres 
curl -X POST "https://nodelodge.com/v1/account/terms" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"version":"2.0"}'

POST /v1/auth/login

Inicia sesión y recibe una cookie de sesión.

Autenticación: ninguna.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
email dirección de correo electrónico Sí hasta 254 caracteres
password cadena Sí hasta 128 caracteres 
curl -X POST "https://nodelodge.com/v1/auth/login" \
  -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","password":"correct horse battery staple"}'

POST /v1/auth/logout

Cierra esta sesión.

Autenticación: ninguna.

curl -X POST "https://nodelodge.com/v1/auth/logout" \
  -b cookies.txt

GET /v1/auth/mfa

Lee el estado de su autenticación de dos factores.

Autenticación: una sesión de consola.

curl "https://nodelodge.com/v1/auth/mfa" \
  -b cookies.txt

POST /v1/auth/mfa/disable

Desactiva la autenticación de dos factores.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
password cadena Sí hasta 128 caracteres 
curl -X POST "https://nodelodge.com/v1/auth/mfa/disable" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"password":"correct horse battery staple"}'

POST /v1/auth/mfa/recovery-codes

Reemplaza sus códigos de recuperación.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
code cadena Sí entre 6 y 40 caracteres 
curl -X POST "https://nodelodge.com/v1/auth/mfa/recovery-codes" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'

POST /v1/auth/mfa/step-up

Confirma su segundo factor antes de una acción sensible.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
code cadena Sí entre 6 y 40 caracteres 
curl -X POST "https://nodelodge.com/v1/auth/mfa/step-up" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'

POST /v1/auth/mfa/totp/confirm

Termina la activación de una aplicación de autenticación.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
code cadena Sí entre 6 y 40 caracteres 
curl -X POST "https://nodelodge.com/v1/auth/mfa/totp/confirm" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'

POST /v1/auth/mfa/totp/setup

Inicia la activación de una aplicación de autenticación.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
password cadena Sí hasta 128 caracteres 
curl -X POST "https://nodelodge.com/v1/auth/mfa/totp/setup" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"password":"correct horse battery staple"}'

POST /v1/auth/mfa/verify

Completa un inicio de sesión con el código de su aplicación de autenticación.

Autenticación: ninguna.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
code cadena Sí entre 6 y 40 caracteres 
curl -X POST "https://nodelodge.com/v1/auth/mfa/verify" \
  -b cookies.txt -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'

POST /v1/auth/password

Cambia su contraseña.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
currentPassword cadena Sí hasta 128 caracteres
newPassword cadena Sí entre 12 y 128 caracteres 
curl -X POST "https://nodelodge.com/v1/auth/password" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"currentPassword":"correct horse battery staple","newPassword":"a longer passphrase of yours"}'

POST /v1/auth/password-reset/confirm

Define una nueva contraseña desde un enlace de restablecimiento.

Autenticación: ninguna.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
token cadena Sí entre 20 y 100 caracteres
password cadena Sí entre 12 y 128 caracteres 
curl -X POST "https://nodelodge.com/v1/auth/password-reset/confirm" \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_FROM_THE_EMAIL_LINK","password":"correct horse battery staple"}'

POST /v1/auth/password-reset/request

Envía por correo electrónico un enlace de restablecimiento de contraseña.

Autenticación: ninguna.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
email dirección de correo electrónico Sí hasta 254 caracteres 
curl -X POST "https://nodelodge.com/v1/auth/password-reset/request" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com"}'

POST /v1/auth/sessions/revoke-all

Cierra todas las sesiones.

Autenticación: una sesión de consola.

curl -X POST "https://nodelodge.com/v1/auth/sessions/revoke-all" \
  -b cookies.txt

POST /v1/auth/signup

Crea una cuenta y su organización.

Autenticación: ninguna.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
email dirección de correo electrónico Sí hasta 254 caracteres
password cadena Sí entre 12 y 128 caracteres
displayName cadena Sí hasta 80 caracteres
organizationName cadena No hasta 120 caracteres
acceptTerms true Sí
inviteToken cadena No entre 20 y 100 caracteres 
curl -X POST "https://nodelodge.com/v1/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","password":"correct horse battery staple","displayName":"Ada Lovelace","acceptTerms":true}'

POST /v1/auth/verify-email

Confirma su dirección de correo electrónico desde el enlace recibido.

Autenticación: ninguna.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
token cadena Sí entre 20 y 100 caracteres 
curl -X POST "https://nodelodge.com/v1/auth/verify-email" \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_FROM_THE_EMAIL_LINK"}'

POST /v1/auth/verify-email/resend

Vuelve a enviar el correo electrónico de confirmación.

Autenticación: una sesión de consola.

curl -X POST "https://nodelodge.com/v1/auth/verify-email/resend" \
  -b cookies.txt

GET /v1/client-config

Lee la configuración pública de la consola.

Autenticación: ninguna.

curl "https://nodelodge.com/v1/client-config"

GET /v1/me

Lee su perfil, su organización y sus accesos.

Autenticación: una sesión de consola.

curl "https://nodelodge.com/v1/me" \
  -b cookies.txt

Claves de API

GET /v1/api-keys

Lista las claves de API de su organización.

Autenticación: una sesión de consola.

curl "https://nodelodge.com/v1/api-keys" \
  -b cookies.txt

POST /v1/api-keys

Crea una clave de API. La clave se devuelve una sola vez; crearla requiere la autenticación de dos factores y un código reciente.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
name cadena Sí hasta 60 caracteres
scopes array de workloads:read, workloads:write, volumes, secrets, billing:read Sí hasta 5 elementos
monthlySpendCapCents entero No de 1 a 10000000
maxConcurrentWorkloads entero No de 1 a 100
maxTotalSpendCents entero No de 1 a 10000000
maxSessionSpendCents entero No de 1 a 10000000
expiresInDays entero No de 1 a 365, por defecto 90 
curl -X POST "https://nodelodge.com/v1/api-keys" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-runner","scopes":["workloads:read"]}'

PATCH /v1/api-keys/{id}

Cambia los límites de gasto de una clave de API. Requiere un código de dos factores reciente.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
monthlySpendCapCents entero No
maxConcurrentWorkloads entero No
maxTotalSpendCents entero No
maxSessionSpendCents entero No 
curl -X PATCH "https://nodelodge.com/v1/api-keys/$API_KEY_ID" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"monthlySpendCapCents":1}'

DELETE /v1/api-keys/{id}

Revoca una clave de API. Las solicitudes que la usan se detienen de inmediato.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl -X DELETE "https://nodelodge.com/v1/api-keys/$API_KEY_ID" \
  -b cookies.txt

GET /v1/whoami

Verifica una clave o una sesión: la organización y los alcances que conlleva.

Autenticación: una clave de API (cualquier alcance) o una sesión de consola.

curl "https://nodelodge.com/v1/whoami" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

Catálogo Community

GET /v1/catalog/offers

Busca máquinas Community.

Autenticación: una clave de API con el alcance workloads:read o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
gpuModel consulta cadena No hasta 80 caracteres
minGpuCount consulta entero No de 0 a 16
minVramGb consulta número No de 0 a 1024
minRamGb consulta número No de 0 a 65536
minVcpu consulta entero No de 0 a 4096
region consulta cadena No
maxPricePerHourCents consulta entero No de 1 a 9007199254740991
onlineOnly consulta true, false No
sort consulta price_asc, price_desc, vram_desc No por defecto "price_asc"
limit consulta entero No de 1 a 100, por defecto 50 
curl "https://nodelodge.com/v1/catalog/offers" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

GET /v1/catalog/offers/{id}

Lee una oferta Community.

Autenticación: una clave de API con el alcance workloads:read o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl "https://nodelodge.com/v1/catalog/offers/$OFFER_ID" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

GET /v1/catalog/offers/{id}/quote

Calcula el precio de un alquiler Community por un número de horas.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
durationHours consulta entero Sí de 1 a 720
id ruta UUID Sí 
curl "https://nodelodge.com/v1/catalog/offers/$OFFER_ID/quote?durationHours=2" \
  -b cookies.txt

Catálogo Secure

GET /v1/catalog/partner-offers

Lista las máquinas Secure, primero las disponibles, luego las agotadas con la última vez que cada una estuvo disponible.

Autenticación: una clave de API con el alcance workloads:read o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
includeUnavailable consulta true, false No por defecto "true" 
curl "https://nodelodge.com/v1/catalog/partner-offers" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

GET /v1/catalog/partner-offers/{id}

Lee una oferta Secure.

Autenticación: una clave de API con el alcance workloads:read o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl "https://nodelodge.com/v1/catalog/partner-offers/$PARTNER_OFFER_ID" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

Sesiones de cómputo

GET /v1/client-address

Lee la dirección IPv4 pública de la que provienen sus solicitudes, para autorizar SSH en una máquina de centro de datos.

Autenticación: una clave de API con el alcance workloads:read o una sesión de consola.

curl "https://nodelodge.com/v1/client-address" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

GET /v1/environments

Lista los entornos listos para usar; con una oferta, si cada uno funciona en su máquina y, si no, por qué.

Autenticación: una clave de API con el alcance workloads:read o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
offerId consulta UUID No 
curl "https://nodelodge.com/v1/environments" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

GET /v1/sessions

Lista sus sesiones de cómputo, como arrendatario o como proveedor.

Autenticación: una clave de API con el alcance workloads:read o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
side consulta renter, provider No por defecto "renter"
limit consulta entero No de 1 a 200, por defecto 50 
curl "https://nodelodge.com/v1/sessions" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

POST /v1/sessions

Inicia una sesión de cómputo. Su presupuesto se reserva sobre el crédito prepago y nunca se supera; la facturación sigue el tiempo real desde que la máquina está lista. Indique IDs de claves SSH guardadas, o una clave pública solo para esta sesión. Con una clave de API, el presupuesto cuenta para los límites de la clave.

Autenticación: una clave de API con el alcance workloads:write o una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
offerId UUID No
partnerOfferId UUID No
environmentId cadena Sí
sshKeyIds array de UUID No hasta 10 elementos
sshPublicKey cadena No entre 40 y 16384 caracteres
budgetCents entero Sí de 1 a 10000000
maxDurationHours entero No de 1 a 2160
pricing on_demand, interruptible, reserved Sí
reservedDays entero No de 1 a 30
model objeto No
allowedCidr cadena No entre 7 y 18 caracteres 
curl -X POST "https://nodelodge.com/v1/sessions" \
  -H "Authorization: Bearer $NODELODGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"partnerOfferId":"3f0c8f5e-8c3a-4f39-9a8e-2d9b4c1e7a10","environmentId":"jupyterlab","budgetCents":500,"pricing":"on_demand","sshPublicKey":"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIReplaceWithYourOwnPublicKey you@laptop","allowedCidr":"203.0.113.7"}'

GET /v1/sessions/{id}

Lee una sesión de cómputo. Mientras arranca, launch indica sus pasos (pedido realizado, máquina asignada, máquina iniciada, comprobación del entorno y de la estabilidad, lista) y cuál está en curso.

Autenticación: una clave de API con el alcance workloads:read o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl "https://nodelodge.com/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

GET /v1/sessions/{id}/access

Lee cómo conectarse a una sesión Community lista: SSH a través del relé y JupyterLab. Solo para el arrendatario; con una clave de API, solo las sesiones iniciadas con esa clave. Una sesión Secure lista indica su dirección SSH en directSsh.

Autenticación: una clave de API con el alcance workloads:write o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl "https://nodelodge.com/v1/sessions/$SESSION_ID/access" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

POST /v1/sessions/{id}/budget

Aumenta el presupuesto de una sesión en curso, reservando la diferencia sobre el crédito prepago. Con una clave de API, solo las sesiones iniciadas con esa clave, dentro de sus límites.

Autenticación: una clave de API con el alcance workloads:write o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
budgetCents entero Sí de 1 a 10000000 
curl -X POST "https://nodelodge.com/v1/sessions/$SESSION_ID/budget" \
  -H "Authorization: Bearer $NODELODGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"budgetCents":1}'

GET /v1/sessions/{id}/receipt

Obtiene el recibo de uso de una sesión finalizada, en JSON o en CSV con format=csv.

Autenticación: una clave de API con el alcance workloads:read o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
format consulta json, csv No por defecto "json"
id ruta UUID Sí 
curl "https://nodelodge.com/v1/sessions/$SESSION_ID/receipt" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

POST /v1/sessions/{id}/stop

Detiene una sesión de cómputo. La facturación termina cuando se detiene realmente y el resto del presupuesto se libera.

Autenticación: una clave de API con el alcance workloads:write o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl -X POST "https://nodelodge.com/v1/sessions/$SESSION_ID/stop" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

Claves SSH

GET /v1/ssh-keys

Lista sus claves públicas SSH.

Autenticación: una clave de API con el alcance workloads:read o una sesión de consola.

curl "https://nodelodge.com/v1/ssh-keys" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

POST /v1/ssh-keys

Añade una clave pública SSH. Requiere un código de dos factores reciente si la autenticación de dos factores está activada.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
name cadena No hasta 60 caracteres
publicKey cadena Sí hasta 16384 caracteres 
curl -X POST "https://nodelodge.com/v1/ssh-keys" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"publicKey":"text"}'

DELETE /v1/ssh-keys/{id}

Elimina una de sus claves públicas SSH. Las sesiones ya iniciadas conservan las suyas.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl -X DELETE "https://nodelodge.com/v1/ssh-keys/$SSH_KEY_ID" \
  -b cookies.txt

Alquileres

GET /v1/reservations

Lista sus alquileres, como arrendatario o como proveedor.

Autenticación: una clave de API con el alcance workloads:read o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
side consulta renter, provider No por defecto "renter"
hostId consulta UUID No
limit consulta entero No de 1 a 200, por defecto 50 
curl "https://nodelodge.com/v1/reservations" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

POST /v1/reservations

Reserva una máquina. Cuando las máquinas de centro de datos se inician como sesiones, una oferta de socio responde 409 SESSION_REQUIRED: use POST /v1/sessions. Bajo demanda, el importe retenido cubre los próximos 60 minutos y se renueva mientras la máquina funciona; la facturación es por minuto iniciado de uso real, sin mínimo de una hora.

Autenticación: una clave de API con el alcance workloads:write o una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
offerId UUID Sí
durationHours entero Sí de 1 a 720
startsAt fecha y hora (ISO 8601) No 
curl -X POST "https://nodelodge.com/v1/reservations" \
  -H "Authorization: Bearer $NODELODGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offerId":"3f0c8f5e-8c3a-4f39-9a8e-2d9b4c1e7a10","durationHours":2}'

GET /v1/reservations/summary

Cuenta sus alquileres por estado.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
side consulta renter, provider No por defecto "renter" 
curl "https://nodelodge.com/v1/reservations/summary" \
  -b cookies.txt

GET /v1/reservations/{id}

Lee un alquiler.

Autenticación: una clave de API con el alcance workloads:read o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl "https://nodelodge.com/v1/reservations/$RESERVATION_ID" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

POST /v1/reservations/{id}/cancel

Cancela un alquiler antes de que empiece.

Autenticación: una clave de API con el alcance workloads:write o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl -X POST "https://nodelodge.com/v1/reservations/$RESERVATION_ID/cancel" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

POST /v1/reservations/{id}/complete

Finaliza un alquiler en curso.

Autenticación: una clave de API con el alcance workloads:write o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl -X POST "https://nodelodge.com/v1/reservations/$RESERVATION_ID/complete" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

POST /v1/reservations/{id}/start

Inicia un alquiler con su clave SSH y la dirección IP autorizada a conectarse.

Autenticación: una clave de API con el alcance workloads:write o una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
sshPublicKey cadena Sí entre 40 y 2000 caracteres
allowedCidr cadena Sí entre 7 y 18 caracteres 
curl -X POST "https://nodelodge.com/v1/reservations/$RESERVATION_ID/start" \
  -H "Authorization: Bearer $NODELODGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sshPublicKey":"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIReplaceWithYourOwnPublicKey you@laptop","allowedCidr":"203.0.113.7"}'

Facturación y crédito

GET /v1/billing

Lee su saldo, su tarjeta y sus pagos.

Autenticación: una sesión de consola.

curl "https://nodelodge.com/v1/billing" \
  -b cookies.txt

PUT /v1/billing/auto-topup

Activa o modifica la recarga automática de su crédito.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
thresholdCents entero Sí de 500 a 1000000
amountCents entero Sí de 1000 a 1000000 
curl -X PUT "https://nodelodge.com/v1/billing/auto-topup" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"thresholdCents":500,"amountCents":2500}'

DELETE /v1/billing/auto-topup

Desactiva la recarga automática.

Autenticación: una sesión de consola.

curl -X DELETE "https://nodelodge.com/v1/billing/auto-topup" \
  -b cookies.txt

POST /v1/billing/card

Inicia el registro de una tarjeta, en una página de pago alojada.

Autenticación: una sesión de consola.

curl -X POST "https://nodelodge.com/v1/billing/card" \
  -b cookies.txt

DELETE /v1/billing/card

Elimina su tarjeta registrada.

Autenticación: una sesión de consola.

curl -X DELETE "https://nodelodge.com/v1/billing/card" \
  -b cookies.txt

POST /v1/billing/credit

Compra crédito prepago, en una página de pago alojada.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
amountCents entero Sí de 1000 a 1000000 
curl -X POST "https://nodelodge.com/v1/billing/credit" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"amountCents":2500}'

GET /v1/limits

Lee los límites de cuenta de su organización: GPU simultáneas, clases de GPU, crédito por 24 horas, lo que está en uso y el siguiente nivel.

Autenticación: una clave de API con el alcance billing:read o una sesión de consola.

curl "https://nodelodge.com/v1/limits" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

Máquinas (proveedores)

GET /v1/hosts

Lista sus máquinas.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
limit consulta entero No de 1 a 500, por defecto 100
cursor consulta cadena No hasta 200 caracteres 
curl "https://nodelodge.com/v1/hosts" \
  -b cookies.txt

POST /v1/hosts/enrollment-codes

Crea un código de un solo uso para emparejar una máquina.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
hostName cadena Sí hasta 80 caracteres 
curl -X POST "https://nodelodge.com/v1/hosts/enrollment-codes" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"hostName":"garage-4090"}'

GET /v1/hosts/{hostId}

Lee una de sus máquinas.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
hostId ruta UUID Sí 
curl "https://nodelodge.com/v1/hosts/$HOST_ID" \
  -b cookies.txt

DELETE /v1/hosts/{hostId}

Quita una máquina revocada de sus listas.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
hostId ruta UUID Sí 
curl -X DELETE "https://nodelodge.com/v1/hosts/$HOST_ID" \
  -b cookies.txt

POST /v1/hosts/{hostId}/{action}

Desactiva, activa o revoca una máquina.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
hostId ruta UUID Sí
action ruta disable, enable, revoke Sí 
curl -X POST "https://nodelodge.com/v1/hosts/$HOST_ID/disable" \
  -b cookies.txt

Ofertas (proveedores)

GET /v1/hosts/{hostId}/offer

Lee la oferta de una máquina.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
hostId ruta UUID Sí 
curl "https://nodelodge.com/v1/hosts/$HOST_ID/offer" \
  -b cookies.txt

PUT /v1/hosts/{hostId}/offer

Define la tarifa por hora, la región y los límites de reserva de una máquina.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
hostId ruta UUID Sí

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
pricePerHourCents entero Sí de 1 a 1000000
regionCode cadena Sí
minHours entero No de 1 a 720, por defecto 1
maxHours entero No de 1 a 720, por defecto 24 
curl -X PUT "https://nodelodge.com/v1/hosts/$HOST_ID/offer" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"pricePerHourCents":150,"regionCode":"CA-QC"}'

POST /v1/hosts/{hostId}/offer/{action}

Publica o retira la oferta de una máquina.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
hostId ruta UUID Sí
action ruta publish, unpublish Sí 
curl -X POST "https://nodelodge.com/v1/hosts/$HOST_ID/offer/publish" \
  -b cookies.txt

Notificaciones

GET /v1/notifications

Lista sus notificaciones.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
limit consulta entero No de 1 a 100, por defecto 20
cursor consulta cadena No hasta 200 caracteres
unread consulta true, false No por defecto "false" 
curl "https://nodelodge.com/v1/notifications" \
  -b cookies.txt

GET /v1/notifications/preferences

Lee su configuración de notificaciones.

Autenticación: una sesión de consola.

curl "https://nodelodge.com/v1/notifications/preferences" \
  -b cookies.txt

PUT /v1/notifications/preferences

Cambia su configuración de notificaciones.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
types array de objetos No hasta 31 elementos
creditLowThresholdCents entero No 
curl -X PUT "https://nodelodge.com/v1/notifications/preferences" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"types":[{"type":"session.ending_soon","email":false}]}'

POST /v1/notifications/read-all

Marca todas las notificaciones como leídas.

Autenticación: una sesión de consola.

curl -X POST "https://nodelodge.com/v1/notifications/read-all" \
  -b cookies.txt

GET /v1/notifications/unread-count

Cuenta sus notificaciones no leídas.

Autenticación: una sesión de consola.

curl "https://nodelodge.com/v1/notifications/unread-count" \
  -b cookies.txt

POST /v1/notifications/unsubscribe

Detiene un tipo de correo electrónico, desde el enlace de ese correo.

Autenticación: ninguna.

Nombre Ubicación Tipo Obligatorio Reglas
token consulta cadena No hasta 100 caracteres

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
token cadena No hasta 100 caracteres
List-Unsubscribe One-Click No 
curl -X POST "https://nodelodge.com/v1/notifications/unsubscribe" \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_FROM_THE_EMAIL_LINK"}'

POST /v1/notifications/{id}/read

Marca una notificación como leída.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl -X POST "https://nodelodge.com/v1/notifications/$NOTIFICATION_ID/read" \
  -b cookies.txt

Actividad

GET /v1/audit-events

Lista la actividad de su organización.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
limit consulta entero No de 1 a 200, por defecto 50 
curl "https://nodelodge.com/v1/audit-events" \
  -b cookies.txt

Soporte

POST /v1/public/abuse-reports

Denuncia el abuso de una máquina Node Lodge, sin cuenta.

Autenticación: ninguna.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
email dirección de correo electrónico Sí hasta 254 caracteres
name cadena No hasta 120 caracteres
kind malware, phishing, spam, network_attack, copyright, illegal_content, other Sí
target cadena Sí entre 3 y 500 caracteres
description cadena Sí entre 20 y 5000 caracteres
evidence cadena No hasta 2000 caracteres
website cadena No hasta 500 caracteres
elapsedMs entero Sí de 0 a 86400000
proof objeto Sí 
curl -X POST "https://nodelodge.com/v1/public/abuse-reports" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","kind":"phishing","target":"https://example.com/login","description":"A login page imitating a bank is served from this address.","website":"","elapsedMs":12000,"proof":{"salt":"abababababababababababab","challenge":"cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd","number":48211,"expiresAt":"2026-11-06T10:10:00.000Z","signature":"efefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef"}}'

GET /v1/public/abuse/challenge

Obtiene el desafío de prueba de trabajo que resuelve el formulario de denuncia antes del envío.

Autenticación: ninguna.

curl "https://nodelodge.com/v1/public/abuse/challenge"

POST /v1/support/attachments

Obtiene un enlace de subida válido 5 minutos para un archivo adjunto (PNG, JPEG, WebP, PDF, texto, JSON, CSV, 10 MB como máximo).

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
ticketId UUID No
fileName cadena Sí hasta 255 caracteres
contentType cadena Sí hasta 100 caracteres
sizeBytes entero Sí de 1 a 10485760 
curl -X POST "https://nodelodge.com/v1/support/attachments" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"fileName":"text","contentType":"text","sizeBytes":1}'

GET /v1/support/attachments/{id}

Obtiene un enlace de descarga válido 60 segundos para un archivo adjunto.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl "https://nodelodge.com/v1/support/attachments/$ATTACHMENT_ID" \
  -b cookies.txt

GET /v1/support/options

Lista las sesiones y los pagos a los que puede referirse una solicitud de soporte.

Autenticación: una sesión de consola.

curl "https://nodelodge.com/v1/support/options" \
  -b cookies.txt

GET /v1/support/tickets

Lista sus solicitudes de soporte, primero las de actividad más reciente. Los propietarios y administradores ven todas las solicitudes de la organización.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
limit consulta entero No de 1 a 100, por defecto 50
cursor consulta cadena No hasta 200 caracteres
status consulta open, waiting_on_customer, resolved, closed No 
curl "https://nodelodge.com/v1/support/tickets" \
  -b cookies.txt

POST /v1/support/tickets

Abre una solicitud de soporte, opcionalmente sobre una sesión o un pago de su organización.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
category limit_increase, billing, technical, account_security, abuse Sí
subject cadena Sí entre 3 y 200 caracteres
body cadena Sí hasta 10000 caracteres
sessionId UUID No
paymentId UUID No
errorReference cadena No hasta 64 caracteres
requestedTier 1 o 2 o 3 No
attachmentIds array de UUID No hasta 5 elementos
followUpOf UUID No 
curl -X POST "https://nodelodge.com/v1/support/tickets" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"category":"technical","subject":"Jupyter does not open","body":"The session is ready but the notebook page stays blank."}'

GET /v1/support/tickets/{id}

Lee una solicitud de soporte y sus mensajes.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl "https://nodelodge.com/v1/support/tickets/$TICKET_ID" \
  -b cookies.txt

POST /v1/support/tickets/{id}/messages

Responde a una solicitud de soporte. Una respuesta a una solicitud resuelta la reabre dentro de los 14 días.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
body cadena Sí hasta 10000 caracteres
attachmentIds array de UUID No hasta 5 elementos 
curl -X POST "https://nodelodge.com/v1/support/tickets/$TICKET_ID/messages" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"body":"text"}'

POST /v1/support/tickets/{id}/rating

Valora la respuesta a una solicitud resuelta.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
rating good, bad Sí
comment cadena No hasta 1000 caracteres 
curl -X POST "https://nodelodge.com/v1/support/tickets/$TICKET_ID/rating" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"rating":"good"}'

POST /v1/support/tickets/{id}/reopen

Reabre una solicitud resuelta, dentro de los 14 días posteriores a su resolución.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl -X POST "https://nodelodge.com/v1/support/tickets/$TICKET_ID/reopen" \
  -b cookies.txt

POST /v1/support/tickets/{id}/resolve

Marca una solicitud de soporte como resuelta.

Autenticación: una sesión de consola.

Nombre Ubicación Tipo Obligatorio Reglas
id ruta UUID Sí 
curl -X POST "https://nodelodge.com/v1/support/tickets/$TICKET_ID/resolve" \
  -b cookies.txt

Sitio público

POST /v1/access-requests

Solicita acceso a Node Lodge.

Autenticación: ninguna.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
email dirección de correo electrónico Sí hasta 254 caracteres
company cadena No hasta 120 caracteres
role renter, provider Sí
useCase cadena Sí
website cadena No hasta 500 caracteres 
curl -X POST "https://nodelodge.com/v1/access-requests" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","role":"renter","useCase":"Fine-tune a 7B model overnight"}'

POST /v1/newsletter

Registra una suscripción al boletín.

Autenticación: ninguna.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
email cadena Sí hasta 254 caracteres
locale en, fr, de, es No 
curl -X POST "https://nodelodge.com/v1/newsletter" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com"}'

POST /v1/newsletter/confirm

Confirma una suscripción al boletín.

Autenticación: ninguna.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
token cadena Sí hasta 200 caracteres 
curl -X POST "https://nodelodge.com/v1/newsletter/confirm" \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_FROM_THE_EMAIL_LINK"}'

POST /v1/newsletter/unsubscribe

Cancela la suscripción al boletín.

Autenticación: ninguna.

Nombre Ubicación Tipo Obligatorio Reglas
token consulta cadena No hasta 200 caracteres

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
token cadena No hasta 200 caracteres
List-Unsubscribe One-Click No 
curl -X POST "https://nodelodge.com/v1/newsletter/unsubscribe" \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_FROM_THE_EMAIL_LINK"}'

GET /v1/public/gpus

Lista los modelos de GPU en oferta, tal como los muestra el sitio público.

Autenticación: ninguna.

curl "https://nodelodge.com/v1/public/gpus"

Otros

POST /v1/smart-launch/recommend

Recomienda máquinas para una carga de trabajo, con los motivos y sus límites.

Autenticación: una sesión de consola.

Cuerpo de la solicitud (JSON):

Campo Tipo Obligatorio Reglas
useCase run_model, fine_tune, generate_images, notebook Sí
modelId cadena No hasta 80 caracteres
quantization fp16, int8, int4 No por defecto "fp16"
contextTokens entero No de 1 a 1048576, por defecto 4096
concurrency entero No de 1 a 256, por defecto 1
minVramGb entero No de 1 a 1024
budgetUsd número No como máximo 1000000
maxPricePerHourUsd número No como máximo 10000
tier secure, community, either No por defecto "either"
countries array de cadenas No hasta 40 elementos, por defecto [] 
curl -X POST "https://nodelodge.com/v1/smart-launch/recommend" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"useCase":"run_model"}'

Última actualización