Cloud Api

Manage Cloud nodes over a REST JSON API.

Base URL

[https://cloud-api.thunderstack.org]

Authentication

All endpoints use bearer auth.

export CLOUD_API_TOKEN="<your_token>"

Each request must include:

-H "Authorization: Bearer ${CLOUD_API_TOKEN}"

Examples below use curl and show paths relative to the base URL.

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": "<iso8601>" }]
    }
  ]
}

Create a node

POST /api/nodes

Body fields:

• name (string, required)
• network (string, required): regtest or testnet
• settings (object, optional)
  • webhookUrl (string, optional)

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": "<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

Body: destroyNodeId (string, required).

This endpoint expects a JSON body on a DELETE request.

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"

Example response:

{ "message": "<message>" }

Webhooks: public key

GET /api/webhook-public-key — Returns the public key used to verify webhook signatures.

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

Example response:

{ "data": "<public_key>" }

RLN images: latest 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"

Example response:

{ "data": "<rln_version>" }

RLN images: upgrade node

POST /api/nodes/{id}/upgrade

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

Example response:

{ "message": "<message>" }

Node settings: update

POST /api/nodes/{id}/settings

Use this to change node settings like webhookUrl.

curl -s -X POST \
  -H "Authorization: Bearer ${THUNDERSTACK_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"

Example response:

{ "message": "<message>" }

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"

Logs: trigger export

POST /api/nodes/{id}/logs

Starts a log export job for a node.

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

Example response:

{ "taskId": "<task_id>" }

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

Example response:

{ "data": ["<presigned_url>"] }