> ## Documentation Index
> Fetch the complete documentation index at: https://utexo-e7ed9bd0-update.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud Api

Manage Cloud nodes over a REST JSON API.

## Base URL

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

## Authentication

All endpoints use bearer auth.

```text theme={null}
export CLOUD_API_TOKEN="<your_token>"
```

Each request must include:

```text theme={null}
-H "Authorization: Bearer ${CLOUD_API_TOKEN}"
```

<Info>
  Examples below use `curl` and show paths relative to the base URL.
</Info>

## List nodes

`GET /api/nodes`

Returns all nodes and their build history.

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

Example response:

```text theme={null}
{
  "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)

```text theme={null}
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:

```text theme={null}
{ 
 "data": { 
	"nodeId": "<node_id>", 
	"name": "my-node", 
	"network": "regtest", 
	"status": "STARTING" 
 }, 
 "message": "<message>" 
}
```

## Get a node

**GET** `/api/nodes/{id}`

```text theme={null}
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).

<Warning>
  This endpoint expects a JSON body on a DELETE request.
</Warning>

```text theme={null}
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:

```text theme={null}
{ "message": "<message>" }
```

## Webhooks: public key

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

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

Example response:

```text theme={null}
{ "data": "<public_key>" }
```

## RLN images: latest version

**GET** `/api/nodes/latest-rln-image`

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

Example response:

```text theme={null}
{ "data": "<rln_version>" }
```

## RLN images: upgrade node

**POST** `/api/nodes/{id}/upgrade`

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

Example response:

```text theme={null}
{ "message": "<message>" }
```

## Node settings: update

**POST** `/api/nodes/{id}/settings`

Use this to change node settings like `webhookUrl`.

```text theme={null}
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:

```text theme={null}
{ "message": "<message>" }
```

## Node lifecycle: start

**POST** `/api/nodes/{id}/start`

```text theme={null}
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`

```text theme={null}
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.

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

Example response:

```text theme={null}
{ "taskId": "<task_id>" }
```

## Logs: get download URLs

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

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

Example response:

```text theme={null}
{ "data": ["<presigned_url>"] }
```