Cloud API

Manage Utexo Cloud RLN nodes programmatically over a REST JSON API.

Overview

The Utexo Cloud API allows you to manage RGB Lightning Node instances programmatically — creating, querying, upgrading, destroying nodes, and managing their settings.

Base URL

https://cloud-api.thunderstack.org

Authentication

All endpoints require bearer token authentication. First create an API token, then export it:

export CLOUD_API_TOKEN="<your_token>"

Include the token in every request:

-H "Authorization: Bearer ${CLOUD_API_TOKEN}"

Endpoints

List Nodes

GET /api/nodes

Returns all nodes and their build history.

curl -s \
  -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \
  "https://cloud-api.thunderstack.org/api/nodes"

Example response

{
  "nodes": [
    {
      "nodeId": "<node_id>",
      "name": "<name>",
      "network": "regtest",
      "status": "RUNNING",
      "initialized": true,
      "invoke_url": "<url>",
      "settings": {
        "webhookUrl": "<url>"
      },
      "builds": [{
        "buildNumber": 1,
        "buildStatus": "SUCCESS",
        "buildComplete": true,
        "timestamp": "<timestamp>"
      }]
    }
  ]
}

Create a Node

POST /api/nodes

Parameter	Type	Required	Description
name	string	Yes	Unique name for the node
network	string	Yes	regtest or testnet
settings.webhookUrl	string	No	URL to receive webhook events

curl -s \
  -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-node","network":"regtest","settings":{"webhookUrl":"https://example.com/webhooks/thunderstack"}}' \
  "https://cloud-api.thunderstack.org/api/nodes"

Example response

{
  "data": {
    "nodeId": "<node_id>",
    "name": "my-node",
    "network": "regtest",
    "status": "STARTING"
  },
  "message": ""
}

Get a Node

GET /api/nodes/{id}

curl -s \
  -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \
  "https://cloud-api.thunderstack.org/api/nodes/<node_id>"

Destroy a Node

DELETE /api/nodes

This action is irreversible. Ensure you have a backup before destroying a node.

curl -s -X DELETE \
  -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "destroyNodeId": "<node_id>" }' \
  "https://cloud-api.thunderstack.org/api/nodes"

Update Node Settings

POST /api/nodes/{id}/settings

Update node settings, such as the webhook URL.

curl -s -X POST \
  -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "settings": { "webhookUrl": "https://example.com/webhooks/thunderstack" } }' \
  "https://cloud-api.thunderstack.org/api/nodes/<node_id>/settings"

Node Lifecycle: Start

POST /api/nodes/{id}/start

curl -s -X POST \
  -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \
  "https://cloud-api.thunderstack.org/api/nodes/<node_id>/start"

Node Lifecycle: Stop

POST /api/nodes/{id}/stop

curl -s -X POST \
  -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \
  "https://cloud-api.thunderstack.org/api/nodes/<node_id>/stop"

Upgrade Node

POST /api/nodes/{id}/upgrade

Upgrades the node to the latest RLN image version.

curl -s -X POST \
  -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \
  "https://cloud-api.thunderstack.org/api/nodes/<node_id>/upgrade"

Get Latest RLN Image Version

GET /api/nodes/latest-rln-image

curl -s \
  -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \
  "https://cloud-api.thunderstack.org/api/nodes/latest-rln-image"

Webhooks: Get Public Key

GET /api/webhook-public-key

Returns the public key used to verify webhook signatures. See Webhooks for details.

curl -s \
  -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \
  "https://cloud-api.thunderstack.org/api/webhook-public-key"

Logs: Trigger Export

POST /api/nodes/{id}/logs

Starts a log export job for a node. Returns a taskId.

curl -s -X POST \
  -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \
  "https://cloud-api.thunderstack.org/api/nodes/<node_id>/logs"

Logs: Get Download URLs

GET /api/nodes/{id}/logs?taskId={taskId}

curl -s \
  -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \
  "https://cloud-api.thunderstack.org/api/nodes/<node_id>/logs?taskId=<task_id>"