API reference

Every public endpoint of the Node Lodge API: authentication, parameters, request bodies and a curl example for each.

The machine-readable description of this API is at https://nodelodge.com/v1/openapi.json (OpenAPI 3.1). Import it in your HTTP client or generate a client from it.

Authentication

Each endpoint states how it authenticates:

An API key: send Authorization: Bearer $NODELODGE_API_KEY. Create keys in the console, under Keys. See API quickstart for scopes.
A console session: the endpoints the console uses. Sign in with POST /v1/auth/login and keep the session cookie (-c cookies.txt), then send it (-b cookies.txt). With two-factor authentication on, finish the sign-in with POST /v1/auth/mfa/verify, sending the same cookie file with -b cookies.txt -c cookies.txt.
None: public endpoints.

An API key on an endpoint that needs a console session answers 403 API_KEY_NOT_ALLOWED. Requests and responses are JSON. Errors have one shape: { "error": { "code": "...", "message": "..." } }.

POST /v1/account/close

Close your account and its organization.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`password`	string	Yes	up to 128 characters
`acceptCreditLoss`	boolean	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

See what closing your account does now, and what blocks it.

Authentication: A console session.

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

GET /v1/account/credit

Read your organization’s prepaid credit and its entries.

Authentication: A console session.

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

GET /v1/account/funds

Read what your organization can spend now: a new session is admitted against the available amount.

Authentication: An API key with the billing:read scope, or a console session.

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

POST /v1/account/terms

Accept the terms of use, in the version that GET /v1/client-config names.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`version`	string	Yes	up to 20 characters

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

Authentication: None.

Request body (JSON):

Field	Type	Required	Rules
`email`	email address	Yes	up to 254 characters
`password`	string	Yes	up to 128 characters

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

Sign out of this session.

Authentication: None.

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

GET /v1/auth/mfa

Read your two-factor status.

Authentication: A console session.

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

POST /v1/auth/mfa/disable

Turn off two-factor authentication.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`password`	string	Yes	up to 128 characters

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

Replace your recovery codes.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`code`	string	Yes	6 characters or more, up to 40 characters

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

Confirm your second factor before a sensitive action.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`code`	string	Yes	6 characters or more, up to 40 characters

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

Finish turning on an authenticator app.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`code`	string	Yes	6 characters or more, up to 40 characters

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

Start turning on an authenticator app.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`password`	string	Yes	up to 128 characters

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

Complete a sign-in with your authenticator code.

Authentication: None.

Request body (JSON):

Field	Type	Required	Rules
`code`	string	Yes	6 characters or more, up to 40 characters

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

Change your password.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`currentPassword`	string	Yes	up to 128 characters
`newPassword`	string	Yes	12 characters or more, up to 128 characters

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

Set a new password from a reset link.

Authentication: None.

Request body (JSON):

Field	Type	Required	Rules
`token`	string	Yes	20 characters or more, up to 100 characters
`password`	string	Yes	12 characters or more, up to 128 characters

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

Send a password reset link by email.

Authentication: None.

Request body (JSON):

Field	Type	Required	Rules
`email`	email address	Yes	up to 254 characters

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

Sign out of every session.

Authentication: A console session.

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

POST /v1/auth/signup

Create an account and its organization.

Authentication: None.

Request body (JSON):

Field	Type	Required	Rules
`email`	email address	Yes	up to 254 characters
`password`	string	Yes	12 characters or more, up to 128 characters
`displayName`	string	Yes	up to 80 characters
`organizationName`	string	No	up to 120 characters
`acceptTerms`	`true`	Yes
`inviteToken`	string	No	20 characters or more, up to 100 characters

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

Confirm your email address from the link you received.

Authentication: None.

Request body (JSON):

Field	Type	Required	Rules
`token`	string	Yes	20 characters or more, up to 100 characters

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

Send the confirmation email again.

Authentication: A console session.

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

GET /v1/client-config

Read the console’s public settings.

Authentication: None.

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

GET /v1/me

Read your profile, organization and access.

Authentication: A console session.

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

API keys

GET /v1/api-keys

List your organization’s API keys.

Authentication: A console session.

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

POST /v1/api-keys

Create an API key. The key is returned once; creating one requires two-factor authentication and a recent code.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`name`	string	Yes	up to 60 characters
`scopes`	array of `workloads:read`, `workloads:write`, `volumes`, `secrets`, `billing:read`	Yes	up to 5 items
`monthlySpendCapCents`	integer	No	1 to 10000000
`maxConcurrentWorkloads`	integer	No	1 to 100
`maxTotalSpendCents`	integer	No	1 to 10000000
`maxSessionSpendCents`	integer	No	1 to 10000000
`expiresInDays`	integer	No	1 to 365, default `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}

Change the spending limits of an API key. Requires a recent two-factor code.

Authentication: A console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

Request body (JSON):

Field	Type	Required
`monthlySpendCapCents`	integer	No
`maxConcurrentWorkloads`	integer	No
`maxTotalSpendCents`	integer	No
`maxSessionSpendCents`	integer	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}

Revoke an API key. Requests using it stop at once.

Authentication: A console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

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

GET /v1/whoami

Check a key or a session: the organization and the scopes it carries.

Authentication: An API key (any scope), or a console session.

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

Community catalog

GET /v1/catalog/offers

Search Community machines.

Authentication: An API key with the workloads:read scope, or a console session.

Name	In	Type	Required	Rules
`gpuModel`	query	string	No	up to 80 characters
`minGpuCount`	query	integer	No	0 to 16
`minVramGb`	query	number	No	0 to 1024
`minRamGb`	query	number	No	0 to 65536
`minVcpu`	query	integer	No	0 to 4096
`region`	query	string	No
`maxPricePerHourCents`	query	integer	No	1 to 9007199254740991
`onlineOnly`	query	`true`, `false`	No
`sort`	query	`price_asc`, `price_desc`, `vram_desc`	No	default `"price_asc"`
`limit`	query	integer	No	1 to 100, default `50`

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

GET /v1/catalog/offers/{id}

Read one Community offer.

Authentication: An API key with the workloads:read scope, or a console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

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

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

Price a Community rental for a number of hours.

Authentication: A console session.

Name	In	Type	Required	Rules
`durationHours`	query	integer	Yes	1 to 720
`id`	path	UUID	Yes

curl "https://nodelodge.com/v1/catalog/offers/$OFFER_ID/quote?durationHours=2" \
  -b cookies.txt

Secure catalog

GET /v1/catalog/partner-offers

List Secure machines, in stock first, then out of stock with the last time each was available.

Authentication: An API key with the workloads:read scope, or a console session.

Name	In	Type	Required	Rules
`includeUnavailable`	query	`true`, `false`	No	default `"true"`

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

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

Read one Secure offer.

Authentication: An API key with the workloads:read scope, or a console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

curl "https://nodelodge.com/v1/catalog/partner-offers/$PARTNER_OFFER_ID" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

Compute sessions

GET /v1/client-address

Read the public IPv4 address your requests come from, to admit SSH to a data-center machine.

Authentication: An API key with the workloads:read scope, or a console session.

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

GET /v1/environments

List ready-to-use environments; with an offer, whether each runs on its machine and why not.

Authentication: An API key with the workloads:read scope, or a console session.

Name	In	Type	Required	Rules
`offerId`	query	UUID	No
`tier`	query	`secure`	No

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

GET /v1/sessions

List your compute sessions, as renter or as provider.

Authentication: An API key with the workloads:read scope, or a console session.

Name	In	Type	Required	Rules
`side`	query	`renter`, `provider`	No	default `"renter"`
`limit`	query	integer	No	1 to 200, default `50`

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

POST /v1/sessions

Start a compute session. Its budget is reserved on prepaid credit and never exceeded; billing follows real time from the moment the machine is ready. Give saved SSH key ids, or one public key for this session only. With an API key, the budget counts toward the limits of the key.

Authentication: An API key with the workloads:write scope, or a console session.

Request body (JSON):

Field	Type	Required	Rules
`offerId`	UUID	No
`partnerOfferId`	UUID	No
`environmentId`	string	Yes
`sshKeyIds`	array of UUID	No	up to 10 items
`sshPublicKey`	string	No	40 characters or more, up to 16384 characters
`budgetCents`	integer	Yes	1 to 10000000
`maxDurationHours`	integer	No	1 to 2160
`pricing`	`on_demand`, `interruptible`, `reserved`	Yes
`reservedDays`	integer	No	1 to 30
`model`	object	No
`allowedCidr`	string	No	7 characters or more, up to 18 characters

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}

Read a compute session. While it starts, launch gives its steps (order placed, machine allocated, machine started, environment and stability checks, ready) and which one is under way.

Authentication: An API key with the workloads:read scope, or a console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

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

GET /v1/sessions/{id}/access

Read how to connect to a ready Community session: SSH through the relay and JupyterLab. Renter only; with an API key, sessions launched with that key only. A ready Secure session gives its SSH address in directSsh.

Authentication: An API key with the workloads:write scope, or a console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

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

POST /v1/sessions/{id}/budget

Raise the budget of a running session, reserving the difference on prepaid credit. With an API key, sessions launched with that key only, within its limits.

Authentication: An API key with the workloads:write scope, or a console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

Request body (JSON):

Field	Type	Required	Rules
`budgetCents`	integer	Yes	1 to 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

Get the usage receipt of an ended session, as JSON or as CSV with format=csv.

Authentication: An API key with the workloads:read scope, or a console session.

Name	In	Type	Required	Rules
`format`	query	`json`, `csv`	No	default `"json"`
`id`	path	UUID	Yes

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

POST /v1/sessions/{id}/stop

Stop a compute session. Billing ends when it really stops and the rest of the budget is released.

Authentication: An API key with the workloads:write scope, or a console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

curl -X POST "https://nodelodge.com/v1/sessions/$SESSION_ID/stop" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

SSH keys

GET /v1/ssh-keys

List your SSH public keys.

Authentication: An API key with the workloads:read scope, or a console session.

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

POST /v1/ssh-keys

Add an SSH public key. Requires a recent two-factor code when two-factor is on.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`name`	string	No	up to 60 characters
`publicKey`	string	Yes	up to 16384 characters

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}

Remove one of your SSH public keys. Sessions already started keep theirs.

Authentication: A console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

curl -X DELETE "https://nodelodge.com/v1/ssh-keys/$SSH_KEY_ID" \
  -b cookies.txt

Rentals

GET /v1/reservations

List your rentals, as a renter or as a provider.

Authentication: An API key with the workloads:read scope, or a console session.

Name	In	Type	Required	Rules
`side`	query	`renter`, `provider`	No	default `"renter"`
`hostId`	query	UUID	No
`limit`	query	integer	No	1 to 200, default `50`

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

POST /v1/reservations

Book a machine. When data-center machines start as sessions, a partner offer answers 409 SESSION_REQUIRED: use POST /v1/sessions. On demand, the amount held covers the next 60 minutes and is renewed while the machine runs; billing is per started minute of real use, with no one-hour minimum.

Authentication: An API key with the workloads:write scope, or a console session.

Request body (JSON):

Field	Type	Required	Rules
`offerId`	UUID	Yes
`durationHours`	integer	Yes	1 to 720
`startsAt`	date and time (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

Count your rentals by status.

Authentication: A console session.

Name	In	Type	Required	Rules
`side`	query	`renter`, `provider`	No	default `"renter"`

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

GET /v1/reservations/{id}

Read one rental.

Authentication: An API key with the workloads:read scope, or a console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

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

POST /v1/reservations/{id}/cancel

Cancel a rental before it starts.

Authentication: An API key with the workloads:write scope, or a console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

curl -X POST "https://nodelodge.com/v1/reservations/$RESERVATION_ID/cancel" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

POST /v1/reservations/{id}/complete

End a running rental.

Authentication: An API key with the workloads:write scope, or a console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

curl -X POST "https://nodelodge.com/v1/reservations/$RESERVATION_ID/complete" \
  -H "Authorization: Bearer $NODELODGE_API_KEY"

POST /v1/reservations/{id}/start

Start a rental with your SSH key and the IP address allowed to connect.

Authentication: An API key with the workloads:write scope, or a console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

Request body (JSON):

Field	Type	Required	Rules
`sshPublicKey`	string	Yes	40 characters or more, up to 2000 characters
`allowedCidr`	string	Yes	7 characters or more, up to 18 characters

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"}'

Billing and credit

GET /v1/billing

Read your balance, card and payments.

Authentication: A console session.

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

PUT /v1/billing/auto-topup

Turn on or change automatic top-up of your credit.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`thresholdCents`	integer	Yes	500 to 1000000
`amountCents`	integer	Yes	1000 to 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

Turn off automatic top-up.

Authentication: A console session.

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

POST /v1/billing/card

Start saving a card, on a hosted payment page.

Authentication: A console session.

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

DELETE /v1/billing/card

Remove your saved card.

Authentication: A console session.

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

POST /v1/billing/credit

Buy prepaid credit, on a hosted payment page.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`amountCents`	integer	Yes	1000 to 1000000

curl -X POST "https://nodelodge.com/v1/billing/credit" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"amountCents":2500}'

GET /v1/limits

Read your organization’s account limits: GPUs at a time, GPU classes, credit per 24 hours, what is in use and the next step.

Authentication: An API key with the billing:read scope, or a console session.

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

Machines (providers)

GET /v1/hosts

List your machines.

Authentication: A console session.

Name	In	Type	Required	Rules
`limit`	query	integer	No	1 to 500, default `100`
`cursor`	query	string	No	up to 200 characters

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

POST /v1/hosts/enrollment-codes

Create a one-time code to pair a machine.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`hostName`	string	Yes	up to 80 characters

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}

Read one of your machines.

Authentication: A console session.

Name	In	Type	Required	Rules
`hostId`	path	UUID	Yes

curl "https://nodelodge.com/v1/hosts/$HOST_ID" \
  -b cookies.txt

DELETE /v1/hosts/{hostId}

Remove a revoked machine from your lists.

Authentication: A console session.

Name	In	Type	Required	Rules
`hostId`	path	UUID	Yes

curl -X DELETE "https://nodelodge.com/v1/hosts/$HOST_ID" \
  -b cookies.txt

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

Disable, enable or revoke a machine.

Authentication: A console session.

Name	In	Type	Required	Rules
`hostId`	path	UUID	Yes
`action`	path	`disable`, `enable`, `revoke`	Yes

curl -X POST "https://nodelodge.com/v1/hosts/$HOST_ID/disable" \
  -b cookies.txt

Offers (providers)

GET /v1/hosts/{hostId}/offer

Read a machine’s offer.

Authentication: A console session.

Name	In	Type	Required	Rules
`hostId`	path	UUID	Yes

curl "https://nodelodge.com/v1/hosts/$HOST_ID/offer" \
  -b cookies.txt

PUT /v1/hosts/{hostId}/offer

Set a machine’s hourly rate, region and booking limits.

Authentication: A console session.

Name	In	Type	Required	Rules
`hostId`	path	UUID	Yes

Request body (JSON):

Field	Type	Required	Rules
`pricePerHourCents`	integer	Yes	1 to 1000000
`regionCode`	string	Yes
`minHours`	integer	No	1 to 720, default `1`
`maxHours`	integer	No	1 to 720, default `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}

Publish or unpublish a machine’s offer.

Authentication: A console session.

Name	In	Type	Required	Rules
`hostId`	path	UUID	Yes
`action`	path	`publish`, `unpublish`	Yes

curl -X POST "https://nodelodge.com/v1/hosts/$HOST_ID/offer/publish" \
  -b cookies.txt

Notifications

GET /v1/notifications

List your notifications.

Authentication: A console session.

Name	In	Type	Required	Rules
`limit`	query	integer	No	1 to 100, default `20`
`cursor`	query	string	No	up to 200 characters
`unread`	query	`true`, `false`	No	default `"false"`

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

GET /v1/notifications/preferences

Read your notification settings.

Authentication: A console session.

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

PUT /v1/notifications/preferences

Change your notification settings.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`types`	array of object	No	up to 31 items
`creditLowThresholdCents`	integer	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

Mark every notification as read.

Authentication: A console session.

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

GET /v1/notifications/unread-count

Count your unread notifications.

Authentication: A console session.

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

POST /v1/notifications/unsubscribe

Stop a type of email, from the link in that email.

Authentication: None.

Name	In	Type	Required	Rules
`token`	query	string	No	up to 100 characters

Request body (JSON):

Field	Type	Required	Rules
`token`	string	No	up to 100 characters
`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

Mark one notification as read.

Authentication: A console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

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

Activity

GET /v1/audit-events

List your organization’s activity.

Authentication: A console session.

Name	In	Type	Required	Rules
`limit`	query	integer	No	1 to 200, default `50`

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

Support

POST /v1/public/abuse-reports

Report abuse of a Node Lodge machine, without an account.

Authentication: None.

Request body (JSON):

Field	Type	Required	Rules
`email`	email address	Yes	up to 254 characters
`name`	string	No	up to 120 characters
`kind`	`malware`, `phishing`, `spam`, `network_attack`, `copyright`, `illegal_content`, `other`	Yes
`target`	string	Yes	3 characters or more, up to 500 characters
`description`	string	Yes	20 characters or more, up to 5000 characters
`evidence`	string	No	up to 2000 characters
`website`	string	No	up to 500 characters
`elapsedMs`	integer	Yes	0 to 86400000
`proof`	object	Yes

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

Get the proof-of-work challenge the abuse report form solves before sending.

Authentication: None.

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

POST /v1/support/attachments

Get a 5-minute upload link for a file to attach (PNG, JPEG, WebP, PDF, text, JSON, CSV, 10 MB at most).

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`ticketId`	UUID	No
`fileName`	string	Yes	up to 255 characters
`contentType`	string	Yes	up to 100 characters
`sizeBytes`	integer	Yes	1 to 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}

Get a 60-second download link for an attachment.

Authentication: A console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

curl "https://nodelodge.com/v1/support/attachments/$ATTACHMENT_ID" \
  -b cookies.txt

GET /v1/support/options

List the sessions and payments a support request can point at.

Authentication: A console session.

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

GET /v1/support/tickets

List your support requests, most recently active first. Owners and admins see every request of the organization.

Authentication: A console session.

Name	In	Type	Required	Rules
`limit`	query	integer	No	1 to 100, default `50`
`cursor`	query	string	No	up to 200 characters
`status`	query	`open`, `waiting_on_customer`, `resolved`, `closed`	No

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

POST /v1/support/tickets

Open a support request, optionally about a session or a payment of your organization.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`category`	`limit_increase`, `billing`, `technical`, `account_security`, `abuse`	Yes
`subject`	string	Yes	3 characters or more, up to 200 characters
`body`	string	Yes	up to 10000 characters
`sessionId`	UUID	No
`paymentId`	UUID	No
`errorReference`	string	No	up to 64 characters
`requestedTier`	`1` or `2` or `3`	No
`attachmentIds`	array of UUID	No	up to 5 items
`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}

Read a support request and its messages.

Authentication: A console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

curl "https://nodelodge.com/v1/support/tickets/$TICKET_ID" \
  -b cookies.txt

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

Reply to a support request. A reply to a resolved request reopens it within 14 days.

Authentication: A console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

Request body (JSON):

Field	Type	Required	Rules
`body`	string	Yes	up to 10000 characters
`attachmentIds`	array of UUID	No	up to 5 items

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

Rate the answer to a resolved request.

Authentication: A console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

Request body (JSON):

Field	Type	Required	Rules
`rating`	`good`, `bad`	Yes
`comment`	string	No	up to 1000 characters

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

Reopen a resolved request, within 14 days of its resolution.

Authentication: A console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

curl -X POST "https://nodelodge.com/v1/support/tickets/$TICKET_ID/reopen" \
  -b cookies.txt

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

Mark a support request as resolved.

Authentication: A console session.

Name	In	Type	Required	Rules
`id`	path	UUID	Yes

curl -X POST "https://nodelodge.com/v1/support/tickets/$TICKET_ID/resolve" \
  -b cookies.txt

Public site

POST /v1/access-requests

Request access to Node Lodge.

Authentication: None.

Request body (JSON):

Field	Type	Required	Rules
`email`	email address	Yes	up to 254 characters
`company`	string	No	up to 120 characters
`role`	`renter`, `provider`	Yes
`useCase`	string	Yes
`website`	string	No	up to 500 characters

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

Subscribe to the newsletter.

Authentication: None.

Request body (JSON):

Field	Type	Required	Rules
`email`	string	Yes	up to 254 characters
`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

Confirm a newsletter subscription.

Authentication: None.

Request body (JSON):

Field	Type	Required	Rules
`token`	string	Yes	up to 200 characters

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

Unsubscribe from the newsletter.

Authentication: None.

Name	In	Type	Required	Rules
`token`	query	string	No	up to 200 characters

Request body (JSON):

Field	Type	Required	Rules
`token`	string	No	up to 200 characters
`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

List the GPU models on offer, as the public site shows them.

Authentication: None.

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

Other

POST /v1/smart-launch/recommend

Recommend machines for a workload, with the reasons and their limits.

Authentication: A console session.

Request body (JSON):

Field	Type	Required	Rules
`useCase`	`run_model`, `fine_tune`, `generate_images`, `notebook`	Yes
`modelId`	string	No	up to 80 characters
`quantization`	`fp16`, `int8`, `int4`	No	default `"fp16"`
`contextTokens`	integer	No	1 to 1048576, default `4096`
`concurrency`	integer	No	1 to 256, default `1`
`minVramGb`	integer	No	1 to 1024
`budgetUsd`	number	No	at most 1000000
`maxPricePerHourUsd`	number	No	at most 10000
`tier`	`secure`, `community`, `either`	No	default `"either"`
`countries`	array of string	No	up to 40 items, default `[]`

curl -X POST "https://nodelodge.com/v1/smart-launch/recommend" \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"useCase":"run_model"}'

Authentication

Sign-in and account

POST /v1/account/close

GET /v1/account/closure

GET /v1/account/credit

GET /v1/account/funds

POST /v1/account/terms

POST /v1/auth/login

POST /v1/auth/logout

GET /v1/auth/mfa

POST /v1/auth/mfa/disable

POST /v1/auth/mfa/recovery-codes

POST /v1/auth/mfa/step-up

POST /v1/auth/mfa/totp/confirm

POST /v1/auth/mfa/totp/setup

POST /v1/auth/mfa/verify

POST /v1/auth/password

POST /v1/auth/password-reset/confirm

POST /v1/auth/password-reset/request

POST /v1/auth/sessions/revoke-all

POST /v1/auth/signup

POST /v1/auth/verify-email

POST /v1/auth/verify-email/resend

GET /v1/client-config

GET /v1/me

API keys

GET /v1/api-keys

POST /v1/api-keys

PATCH /v1/api-keys/{id}

DELETE /v1/api-keys/{id}

GET /v1/whoami

Community catalog

GET /v1/catalog/offers

GET /v1/catalog/offers/{id}

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

Secure catalog

GET /v1/catalog/partner-offers

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

Compute sessions

GET /v1/client-address

GET /v1/environments

GET /v1/sessions

POST /v1/sessions

GET /v1/sessions/{id}

GET /v1/sessions/{id}/access

POST /v1/sessions/{id}/budget

GET /v1/sessions/{id}/receipt

POST /v1/sessions/{id}/stop

SSH keys

GET /v1/ssh-keys

POST /v1/ssh-keys

DELETE /v1/ssh-keys/{id}

Rentals

GET /v1/reservations

POST /v1/reservations

GET /v1/reservations/summary

GET /v1/reservations/{id}

POST /v1/reservations/{id}/cancel

POST /v1/reservations/{id}/complete

POST /v1/reservations/{id}/start

Billing and credit

GET /v1/billing

PUT /v1/billing/auto-topup

DELETE /v1/billing/auto-topup

POST /v1/billing/card

DELETE /v1/billing/card

POST /v1/billing/credit

GET /v1/limits

Machines (providers)

GET /v1/hosts

POST /v1/hosts/enrollment-codes

GET /v1/hosts/{hostId}

DELETE /v1/hosts/{hostId}

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

Offers (providers)

GET /v1/hosts/{hostId}/offer

PUT /v1/hosts/{hostId}/offer

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

Notifications