Skip to main content
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>"] }