Node Management

This page covers only node management operations supported by third-party API Keys. The deployment supplies the API base URL, for example https://api.stashcloud.net; the network is not a URL prefix.

Authentication and request identifiers

Use Authorization: Bearer <API_KEY>. Every node management request requires X-Network: regtest|testnet|mainnet, matching the key and resource. Reads require nodes:read; creation, start, stop, deletion and P2P allocation require nodes:write. There is no separate deletion scope.

Creation, start, stop and deletion accept a UUID in Request-Id or X-Request-Id; supplying and retaining it is recommended. If both are supplied they must match; invalid, zero or conflicting UUIDs return 400. The server generates a UUID if omitted, but retries must reuse the original UUID to reuse the idempotent result. Responses include X-Request-Id, and cache hits include X-Idempotent-Cached: true. Do not reuse an identifier for a different request. P2P allocation is repeatable and does not use this idempotency cache.

Create a node

POST /v3/nodes — createNode, success 202 Accepted.

The body contains only optional name (maximum 64 characters), or {}. Bodies are limited to 4096 bytes; invalid JSON, null, non-objects, or any field other than name return 400. Node type selection, resource sizing and synchronous waiting are not supported.

curl --fail-with-body -sS -X POST "$BASE_URL/v3/nodes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Network: $NETWORK" \
  -H "Request-Id: $REQUEST_ID" \
  -H 'Content-Type: application/json' \
  -d '{"name":"demo-node"}'

The response is directly NodeDetails, not a data wrapper. This example illustrates the fields, not default deployment resources:

{
  "id": "example-node",
  "network": "regtest",
  "name": "demo-node",
  "status": "pending",
  "public_dns": "example-node-regtest.stashcloud.net",
  "api_base_url": "https://example-node-regtest.stashcloud.net",
  "provision_retryable": false,
  "version": 0,
  "cpu_cores": "1.0",
  "memory_mb": 1024,
  "storage_gb": 1,
  "created_at": "2026-10-01T00:00:00Z"
}

These fields are required; identity_pubkey, provision_failure, provisioned_at, stopped_at and held p2p_host / p2p_port / p2p_address are optional. Reading details does not allocate a P2P port. public_dns / api_base_url are HTTPS API addresses, not Lightning P2P connection addresses, and do not grant API Key access to the node runtime.

status is a string, not a closed enum. An allocated hostname does not indicate readiness; query details for state and failure information and do not treat 202 as a node-availability promise.

Query and pagination

• GET /v3/nodes — listNodes, 200, returns { "nodes": [...], "next_cursor": "..." }; nodes may be null, so clients may normalize it to an empty array.
• Optional query: cursor (maximum 64 characters), limit (default 20, range 1–100). Pass the returned next_cursor unchanged for the next page; an empty string means no next page.
• GET /v3/nodes/{id} — getNode, 200, returns NodeDetails directly.

curl --fail-with-body -sS "$BASE_URL/v3/nodes?limit=20" \
  -H "Authorization: Bearer $API_KEY" -H "X-Network: $NETWORK"
curl --fail-with-body -sS "$BASE_URL/v3/nodes/$NODE_ID" \
  -H "Authorization: Bearer $API_KEY" -H "X-Network: $NETWORK"

Start, stop and delete

• POST /v3/nodes/{id}/start — startNode, 200, NodeDetails.
• POST /v3/nodes/{id}/stop — stopNode, 200, NodeDetails.
• DELETE /v3/nodes/{id} — deleteNode, 200, { "id": "...", "network": "regtest", "deleted": true }.

These have no JSON body; the key and X-Network remain required, and a stable request UUID is recommended. Different operations need different UUIDs. State/idempotency conflicts may return 409; responses are not 202 or 204. There is no third-party recovery/undelete operation; confirm backups and migration arrangements first.

curl --fail-with-body -sS -X POST "$BASE_URL/v3/nodes/$NODE_ID/stop" \
  -H "Authorization: Bearer $API_KEY" -H "X-Network: $NETWORK" \
  -H "Request-Id: $STOP_REQUEST_ID"

P2P address allocation

POST /v3/nodes/{id}/p2p — applyNodeP2P, requires nodes:write and X-Network, no JSON body, success 200.

The node must be a running user node, otherwise 409. A target node that does not exist or is outside the current user/network scope returns 404. Disabled P2P, exhausted port pools or allocation failures return 503. Calls are repeatable and do not use the request UUID idempotency cache for creation, start, stop and deletion.

Success returns directly:

{
  "id": "example-node",
  "network": "regtest",
  "p2p_host": "example-node-regtest-p2p.example.net",
  "p2p_port": 9735,
  "p2p_address": "example-node-regtest-p2p.example.net:9735"
}

p2p_address is a Lightning P2P connection address, not an HTTPS API address.

Errors and capability boundaries

See Authentication for the common error structure, authentication and permission errors, and rate limiting. The third-party API does not provide node renaming, resizing, node type selection or one-click backup restoration. Node runtime access is outside this page's scope; an API Key alone does not grant it.