# 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](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](https://nodelodge.com/docs/api) 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": "..." } }`.

## Sign-in and account

### 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 |  |

```bash
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.

```bash
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.

```bash
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.

```bash
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 |

```bash
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

Sign in and receive a session cookie.

**Authentication:** None.

Request body (JSON):

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

```bash
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.

```bash
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.

```bash
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 |

```bash
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 |

```bash
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 |

```bash
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 |

```bash
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 |

```bash
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 |

```bash
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 |

```bash
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 |

```bash
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 |

```bash
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.

```bash
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 |

```bash
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 |

```bash
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.

```bash
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.

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

### GET /v1/me

Read your profile, organization and access.

**Authentication:** A console session.

```bash
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.

```bash
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` |

```bash
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 | Rules |
|---|---|---|---|
| `monthlySpendCapCents` | integer | No |  |
| `maxConcurrentWorkloads` | integer | No |  |
| `maxTotalSpendCents` | integer | No |  |
| `maxSessionSpendCents` | integer | No |  |

```bash
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 |  |

```bash
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.

```bash
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` |

```bash
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 |  |

```bash
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 |  |

```bash
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"` |

```bash
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 |  |

```bash
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.

```bash
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 |  |

```bash
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` |

```bash
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 |

```bash
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 |  |

```bash
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 |  |

```bash
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 |

```bash
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 |  |

```bash
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 |  |

```bash
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.

```bash
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 |

```bash
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 |  |

```bash
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` |

```bash
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 |  |

```bash
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"` |

```bash
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 |  |

```bash
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 |  |

```bash
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 |  |

```bash
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 |

```bash
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.

```bash
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 |

```bash
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.

```bash
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.

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

### DELETE /v1/billing/card

Remove your saved card.

**Authentication:** A console session.

```bash
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 |

```bash
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.

```bash
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 |

```bash
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 |

```bash
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 |  |

```bash
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 |  |

```bash
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 |  |

```bash
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 |  |

```bash
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` |

```bash
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 |  |

```bash
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"` |

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

### GET /v1/notifications/preferences

Read your notification settings.

**Authentication:** A console session.

```bash
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 |  |

```bash
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.

```bash
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.

```bash
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 |  |

```bash
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 |  |

```bash
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` |

```bash
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 |  |

```bash
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.

```bash
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 |

```bash
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 |  |

```bash
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.

```bash
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 |  |

```bash
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 |  |

```bash
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 |  |

```bash
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 |

```bash
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 |

```bash
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 |  |

```bash
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 |  |

```bash
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 |

```bash
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 |  |

```bash
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 |

```bash
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 |  |

```bash
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.

```bash
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 `[]` |

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