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

# 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

```text theme={null}
https://cloud-api.thunderstack.org
```

## Authentication

All endpoints require bearer token authentication. First [create an API token](/access-token-authorization/create-api-token), then export it:

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

Include the token in every request:

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

## Endpoints

### List Nodes

`GET /api/nodes`

Returns all nodes and their build history.

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

<Accordion title="Example response">
  ```json 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": "<timestamp>"
        }]
      }
    ]
  }
  ```
</Accordion>

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

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

<Accordion title="Example response">
  ```json theme={null}
  {
    "data": {
      "nodeId": "<node_id>",
      "name": "my-node",
      "network": "regtest",
      "status": "STARTING"
    },
    "message": ""
  }
  ```
</Accordion>

### Get a Node

`GET /api/nodes/{id}`

```bash 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`

<Warning>
  This action is irreversible. Ensure you have a backup before destroying a node.
</Warning>

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

### Update Node Settings

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

Update node settings, such as the webhook URL.

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

```bash 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`

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

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

```bash theme={null}
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](/cloud/webhooks) for details.

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

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

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