NODANA NODE API — AGENT REFERENCE

Base URL: https://api.nodana.io/v1
Full documentation: https://nodana.io/docs/api

This file covers the public bearer-key API for managing Nodana-hosted
Phoenixd nodes. Paths below are relative to the base URL. It does not
describe dashboard session routes or the Phoenixd payment API.

AUTHENTICATION

Send Authorization: Bearer <NODANA_API_KEY> over HTTPS. API keys are created
by a person in the Nodana dashboard under Developers > API Keys; a bearer
key cannot create another key. Keep keys out of chat, logs, and source code.

Scopes:
  nodes:read   Required for every key; list/read nodes and check updates
  nodes:write  Create, rename, start, stop, restart, update, and delete nodes

The key determines the account. Do not send an account ID with the paths
below. The Nodana API key does not authenticate to a node's Phoenixd API.
Use the node endpoint and Phoenixd password for balances, invoices, and
Lightning payments. See https://nodana.io/docs/api/phoenixd-api

ENDPOINTS

GET /api-key
  Auth: Any valid Nodana API key.
  200: {"id": string, "accountId": string, "scopes": string[]}
  Inspects the current key; does not reveal its secret or create keys.

GET /nodes
  Scope: nodes:read
  200: {"nodes": [node, ...]}; deleted nodes are excluded.

POST /nodes
  Scope: nodes:write
  JSON body: {"name"?: string, "autoLiquidity"?: "2m"|"5m"|"10m"}
  name: At most 16 characters after trimming; omitted/blank uses Node n.
  autoLiquidity: Defaults to 2m.
  202: {"node": node, "credentials": {"seed": string,
        "password": string, "restrictedPassword": string}}
  Provisioning continues after 202. The recovery words and passwords are
  returned only here. Capture them directly into an approved secret store;
  never print the raw response in an agent transcript or log. Wait for the
  node status to become ready before using its Phoenixd API. Creation may
  return 402 when account credit or billing prevents it.

GET /nodes/{nodeId}
  Scope: nodes:read
  200: node; never returns passwords or recovery words.

PATCH /nodes/{nodeId}
  Scope: nodes:write
  JSON body: {"name": string}; at most 16 characters after trimming.
  200: renamed node.

POST /nodes/{nodeId}/start
  Scope: nodes:write
  Allowed when status is stopped or failed.
  200: node after Phoenixd is ready.

POST /nodes/{nodeId}/stop
  Scope: nodes:write
  Allowed when status is ready.
  200: stopped node. Payment API becomes unavailable; billing continues.

POST /nodes/{nodeId}/restart
  Scope: nodes:write
  Allowed when status is ready.
  200: ready node. Payment API is unavailable during restart.

GET /nodes/{nodeId}/update
  Scope: nodes:read
  200: {"currentVersion": string|null,
        "availableUpdate": {"version": string}|null}

POST /nodes/{nodeId}/update
  Scope: nodes:write
  Requires a ready node with an available update.
  200: node with status updating; update continues in the background.
  Read the node again to determine the final outcome.

DELETE /nodes/{nodeId}
  Scope: nodes:write
  204: No response body. Deletion is permanent. Reconcile outstanding
  payments, remaining funds, and recovery information first. Bearer-key
  requests do not require a second-factor code.

RESPONSES AND RETRIES

node fields: id, name, status, endpointUrl, failureMessage,
             updateStatus, updateCompletedAt, createdAt, updatedAt.
Node statuses include provisioning, ready, stopped, cordoned, updating,
failed, deleting, and deleted. Timestamps are Unix seconds.

Errors normally contain {"error":{"code":string,"message":string}}.
400: Invalid input or node state. 401: Missing/invalid key or scope.
402: Nodana account credit or billing issue, not a Lightning/L402 challenge.
404: Node not found. 429: Rate limited; honor Retry-After seconds.
500/502/503: Server or dependency failure; retry reads with bounded backoff.

The default limit is 180 requests per 60 seconds per client IP, but the
deployment may change it. Avoid tight polling. A timeout on a mutation
does not mean it failed: read the node state before repeating it. After
an uncertain create request, list nodes before creating another one;
POST /nodes has no idempotency key.

Detailed errors: https://nodana.io/docs/api/errors
Rate limits: https://nodana.io/docs/api/rate-limits