Nodana API Reference

Welcome to the API reference for Nodana. This reference will be moved to a more suitable home in the future but for now you should have everything you need to deploying apps on Nodana programmatically.

Jump to Endpoint

Create a project

Retrieve a project

Update a project

Delete a project

List projects

List project apps

Create an app

Retrieve an app

Start an app

Stop an app

Delete an app

List app services

Update app service

Getting Started

You will need to create a token to be able to use this API. This can be done on the Nodana website from the account section. Please be very careful with your tokens as they provide full read/write access to your apps.

If you find an issue with any of this documentation then feel free to raise an issue here. If an endpoint does not work as expected then please get in touch. Contact details are available on Nodana.

Concepts

The API should be very easy to use but there are a few things to know:

• Only GET and POST methods are supported
• Uses method name in the route (/update, /delete etc)
• All responses are 200

See endpoint documentation below for a more detailed explanation.

Base Url

https://api.nodana.io

Authentication

You will need an api key to make requests. Please add this key to the password part of the Basic Authentication header. You should leave the username part of the header empty.

All calls should be made over https.

Keep your keys safe as they provide access to your projects and apps.

Rate Limiting

In general, requests are limited to 1 per second. Some endpoints may enforce stricter rates. Please do not repeatedly abuse the rate limits or keys will be banned.

Errors

If there is an internal error with the api (which shouldn't be very often) then there will be a 500 response so ensure you requests logic can catch unexpected errors.

All other responses are considered successfull (200) so you need to examine the response payload to understand the outcome of the request:

Here's an example response:

{
  "message": "Request is forbidden",
  "error": "ForbiddenError",
  "statusCode": 403
}

Always check for the existence of error on the response object. If it exists then your request hasn't been successful. If there isn't an error property then your request has been successful and there will be a data property instead. Responses never include both data and error properties.

Projects

Consider projects as groups for your apps. They allow you to group together related apps for your convenience. Billing is applied to projects and you will be able to scope API keys to a project in the future. You can currently create a maximum of four projects (get in touch if you need to increase this limit).

Create Project

Create a project

POST /projects

Request

curl -i -X POST \\
  -H "Authorization: Basic :${API_KEY}" -H "Content-Type: application/json" \\
  "${BASE_URL}/v1/projects" \\
  -d '{
    "name"="My Project",
  }'

Response

{
  "data": {
    "id": "<project-id>",
    "name": "My Project"
  }
}

Retrieve Project

Retrieve details about a project

GET /projects/:id

Request

curl -i -X GET \\
  -H "Authorization: Basic :${API_KEY}" -H "Content-Type: application/json" \\
  "${BASE_URL}/v1/projects/:id"

Response

{
  "data": {
    "id": "<project-id>",
    "userId": "<user-id>",
    "name": "New Project",
    "deleted": false,
    "createdAt": "2025-05-01T07:46:12.368Z",
    "updatedAt": "2025-05-01T07:46:12.368Z"
  }
}

Update Project

Update details about a project

POST /projects/:id/update

Request

curl -i -X POST \\
  -H "Authorization: Basic :${API_KEY}" -H "Content-Type: application/json" \\
  "${BASE_URL}/v1/projects/:id/update" \\
  -d '{
    "name"="My Updated Project",
  }'

Response

{
  "data": {
    "id": "<project-id>",
    "updated": true
  }
}

Delete Project

Delete a project. Note that only empty projects can be deleted so please ensure you delete all the apps from the project first.

POST /projects/:id/delete

Request

curl -i -X POST \\
  -H "Authorization: Basic :${API_KEY}" -H "Content-Type: application/json" \\
  "${BASE_URL}/v1/projects/:id/delete"

Response

{
  "data": {
    "id": "<project-id>",
    "deleted": true
  }
}

List Projects

List all projects.

GET /projects

Request

curl -i -X GET \\
  -H "Authorization: Basic :${API_KEY}" -H "Content-Type: application/json" \\
  "${BASE_URL}/v1/projects" \\

Response

{
  "data": [
    {
      "id": "<project-id>",
      "userId": "<user-id>",
      "name": "New Project 1",
      "deleted": false,
      "createdAt": "2025-05-01T07:46:12.368Z",
      "updatedAt": "2025-05-01T07:46:12.368Z"
    },
    {
      "id": "<project-id>",
      "userId": "<user-id>",
      "name": "New Project 2",
      "deleted": false,
      "createdAt": "2025-05-01T07:46:12.368Z",
      "updatedAt": "2025-05-01T07:46:12.368Z"
    }
  ]
}

List Project Apps

List all apps within a project.

GET /projects/:id/apps

Request

curl -i -X GET \\
  -H "Authorization: Basic :${API_KEY}" -H "Content-Type: application/json" \\
  "${BASE_URL}/v1/projects/:id/apps" \\

Response

{
  "data": [
    {
      "id": "<app-id>",
      "userId": "<user-id>",
      "projectId": "<project-id>",
      "template": "template-name",
      "rate": 0.000233,
      "url": "https://app-url.nodana.app:8000",
      "status": "running",
      "createdAt": "2025-05-24T08:07:10.509Z",
      "updatedAt": "2025-05-24T08:07:10.509Z"
    }
  ]
}

Apps

Templates consist of one or more services and an App is an instance of a template. This means that Apps can consist of one or more services.

Create App

Create an app. You can provide a project_id if you want the app to be assigned to an existing project. If you don't provide a project_id then a new project will be created automatically.

POST /apps

Request

curl -i -X POST \\
    -H "Authorization: Basic :${API_KEY}" -H "Content-Type: application/json" \\
    "${BASE_URL}/v1/apps" \\
  -d '{
    "project_id"="prj-5fd3",
    "template": "template-name",
    "params": {
      "prop-1": "value-1",
      "prop-2": "value-2,
    },
  }'

params is an object but the properties differ for each template. If the template isn't listed below then it doesn't accept config values.

You will receive a response to the Create App request immediately but it doesn't mean the app is running. It usually takes about 10 seconds for an app to start (but this can vary). You should use the Retrieve App endpoint to know when the status is "available".

alby-hub-phoenixd

Property	Type	Possible Values
auto_liquidity	string	2m, 5m, 10m

cdk-mintd

Property	Type	Possible Values
mint_name	string
mint_description	string

lnbits-phoenixd

Property	Type	Possible Values
auto_liquidity	string	2m, 5m, 10m

nutshell

Property	Type	Possible Values
mint_name	string
mint_description	string
mint_lnd_rest_url	string
mint_lnd_macaroon	string

phoenixd

Property	Type	Possible Values
auto_liquidity	string	2m, 5m, 10m
webhook	string

Response

{
  "projectId": "<project-id>",
  "id": "<app-id>",
  "url": "https://app-url-1234.nodana.app:8080"
}

The full response will differ depending on the template provided. For example, if you create a phoenixd node then the response will include a seed phrase, passwords etc.

Retrieve App

Retrieve details about an app

GET /apps/:id

Request

curl -i -X GET \\
  -H "Authorization: Basic :${API_KEY}" -H "Content-Type: application/json" \\
  "${BASE_URL}/v1/apps/:id"

Response

{
  "data": {
    "id": "<app-id>",
    "userId": "<user-id>",
    "projectId": "<project-id>",
    "template": "template-name",
    "rate": 0.000233,
    "url": "https://template-id-ad4f.nodana.app:8000",
    "status": "available",
    "createdAt": "2025-05-24T08:07:10.509Z",
    "updatedAt": "2025-05-24T08:07:10.509Z"
  }
}

App status can either be "available", "cordoned" or "deleted".

Start App

This endpoint will start all of the apps services.

POST /apps/:id/start

Request

curl -i -X POST \\
    -H "Authorization: Basic :${API_KEY}" -H "Content-Type: application/json" \\
    "${BASE_URL}/v1/apps/:id/start"

Response

{
  "data": {
    "id": "<app-id>"
  }
}

Stop App

This endpoint will stop all of the apps services.

POST /apps/:id/stop

Request

curl -i -X POST \\
    -H "Authorization: Basic :${API_KEY}" -H "Content-Type: application/json" \\
    "${BASE_URL}/v1/apps/:id/stop"

Response

{
  "data": {
    "id": "<app-id>"
  }
}

Delete App

This endpoint will delete an app and all of the apps services.

POST /apps/:id/delete

Request

curl -i -X POST \\
    -H "Authorization: Basic :${API_KEY}" -H "Content-Type: application/json" \\
    "${BASE_URL}/v1/apps/:id/delete"

{
  "data": {
    "id": "<app-id>"
  }
}

List App Services

List services within an app.

GET /apps/:id/services

Request

curl -i -X GET \\
  -H "Authorization: Basic :${API_KEY}" -H "Content-Type: application/json" \\
  "${BASE_URL}/v1/apps/:id/services"

Response

{
  "data": [
    {
      "id": "svc-1234",
      "appId": "app-1234",
      "service": "service-name",
      "slug": "slug-sdh3",
      "region": "ewr",
      "status": "running",
      "version": "0.1.0",
      "createdAt": "2025-07-01T07:46:12.368Z",
      "updatedAt": "2025-07-01T07:46:12.368Z"
    }
  ]
}

Update App Service

Update a service to use a newer version

POST /apps/:id/services/:serviceId/update

Request

curl -i -X POST \\
  -H "Authorization: Basic :${API_KEY}" -H "Content-Type: application/json" \\
  "${BASE_URL}/v1/apps/:id/services/:serviceId/update"

Response

{
  "data": {
    "id": "app-1234",
    "serviceId": "svc-1234",
    "version": "0.1.1",
    "updated": true
  }
}