Helium Console API

This page has not been fully updated to represent the latest state of the Helium Network following the migration to Solana on April 18, 2023.

The Console API is a set of HTTP Request that allows you to programatically interact with Console. It's the lowest level building block and is ideal for integrating with back-end services, for example.

Base URL

https://console.helium.com/

Authentication

All Console API requests require an API Key which provides access to devices owned by the organization which owns the device. Devices are never associated to a single user, but instead to an organization.

To create an account key, go to your profile on Helium Console. From the top right corner, click: Account -> Profile.

From there, you may generate a key for your organization. The key will only display once.

You must confirm the API key creation by clicking a link that is emailed to the account that created the API key.

From then on, you will want to include the API key in all of your API requests. You do this by placing your API key in an HTTP header field called "key.

Headers

Parameter Name	Type	Description
key (required)	string	your API key

Data Credit Balance

GET https://console.helium.com/api/v1/organization

Response

200: OK

[
    {
       "dc_balance": 731686
        "id": "07273bc4-4bc9-44ec-b4d5-ad320f162e15",
        "name": "Acme",
    },
]

Devices List

GET https://console.helium.com/api/v1/devices

Response

200: OK

[
    Device {
        "active": false,
        "adr_allowed": null,
        "app_eui": "70B3D57ED0008E64",
        "app_key": "30EACA8A2CAF0C5315D0E4A1B7F7B55B",
        "dev_eui": "008000000401261D",
        "cf_list_enabled": null,
        "config_profile_id": null,
        "dc_usage": 606837,
        "id": "747246dd-d9b6-4e68-96c1-2c489ab33280",
        "in_xor_filter": true,
        "labels": [],
        "last_connected": "2022-03-03T22:37:33",
        "name": "Basement Temp",
        "organization_id": "07273bc4-4bc9-44ec-b4d5-ad320f162e15",
        "oui": 1,
        "rx_delay": 1,
        "total_packets": 303442
    },
    Device {
        "active": true,
        "adr_allowed": null,
        "app_eui": "CE1BAF8A8824FD1D",
        "app_key": "2A37E7FACF2F0B7833413E9F8988C4EF",
        "dev_eui": "008000000401261D",
        "cf_list_enabled": null,
        "config_profile_id": null,
        "dc_usage": 606925,
        "id": "916fc471-87f1-43a8-939e-c36589f33232",
        "in_xor_filter": true,
         "labels": [
            {
                "adr_allowed": null,
                "cf_list_enabled": null,
                "config_profile_id": null,
                "id": "20865d14-bd90-4cbb-80e5-401c2c71fdab",
                "name": "Device group",
                "rx_delay": null
        "last_connected": "2022-03-03T22:37:33",
        "name": "Water Level North",
        "organization_id": "07273bc4-4bc9-44ec-b4d5-ad320f162e15",
        "oui": 1,
        "rx_delay": 1,
        "total_packets": 303486
    },
]

Devices by AppEui, AppKey, DevEui

GET https://console.helium.com/api/v1/devices?app_eui={app_eui}&app_key={app_key}&dev_eui={dev_eui}

Returns a device descriptor if device is found.

Request
Response

Path Parameters

Parameter Name	Type	Description
dev_eui (required)	string	LoRaWAN Device EUI uniquely identifies a device
app_eui (required)	string	LoRaWAN App EUI uniquely identifies the application of the device
app_key (required)	string	LoRaWAN App Key is a shared secret key which is used to derive secure sessions via the Join mechanism

Device {
    app_eui: "70B3D57ED0008E64",
    app_key: "30EACA8A2CAF0C5315D0E4A1B7F7B55B",
    dev_eui: "008000000401261D",
    id: "747246dd-d9b6-4e68-96c1-2c489ab33280",
    name: "Basement Temp",
    organization_id: "07273bc4-4bc9-44ec-b4d5-ad320f162e15",
    oui: 1,
}

Device by UUID

GET https://console.helium.com/api/v1/devices/:device_id

Returns a device descriptor if device is found.

Request
Response

Path Parameters

Parameter Name	Type	Description
device_id (required)	string	UUID of the device

Device {
    "adr_allowed":(true/false),
    "app_eui": (app_eui),
    "app_key": (app_key),
    "cf_list_enabled":(true/false),
    "dc_usage": (dc_amount_used),
    "dev_eui": (dev_eui),
    "id": (device_id),
    "in_xor_filter":(true/false)
    "labels": (labels)
    "last_connected": (time_UTC)
    "name": (device_name)
    "organization_id": (org_id)
    "oui": (oui_number)
    "total_packets":(packets_sent)
}

Device Events

GET https://console.helium.com/api/v1/devices/:device_id/events

Returns the previous 100 events for the device if found.

Request
Response

Path Parameters

Parameter Name	Type	Description
device_id (required)	string	UUID of the device

Device {
"category": "uplink",
        "data": {
            "dc": {
                "balance": 7944423,
                "nonce": 2,
                "used": 2
            },
            "devaddr": (devaddr),
            "fcnt": 33032,
            "hold_time": 30,
            "hotspot": {
                "channel": 15,
                "frequency": 905.2999877929688,
                "id": ("hotspot_id"),
                "lat": (lat),
                "long": (long),
                "name": ("hotspot_name"),
                "rssi": -57.0,
                "snr": 12.800000190734863,
                "spreading": "SF9BW125"
            },
            "mac": [],
            "payload": ("payload"),
            "payload_size": 27,
            "port": 1
        },
        "description": "Confirmed data up received",
        "device_id": ("device_id"),
        "frame_down": null,
        "frame_up": 33032,
        "organization_id": ("org_id"),
        "reported_at": "1632352528562",
        "router_uuid": ("router_id"),
        "sub_category": "uplink_confirmed"
}

Device Integration Events

GET https://console.helium.com/api/v1/devices/:device_id/events?sub_category=uplink_integration_req

Returns the previous 10 Integration events for the device if found.

Request
Response

Path Parameters

Parameter Name	Type	Description
device_id (required)	string	UUID of the device

Device {
      "category": "uplink",
        "data": {
            "integration": {
                "id": ("integration_id"),
                "name": "azure-int",
                "status": "success"
            },
            "req": {
                "body": {
                    "app_eui": ("app_eui)",
                    "dev_eui": ("dev_eui",
                    "devaddr": ("devaddr"),
                    "fcnt": 33072,
                    "hotspots": [
                        {
                            "channel": 12,
                            "frequency": 904.7000122070313,
                            "hold_time": 31,
                            "id": ("hotspot_id)",
                            "lat": ("lat"),
                            "long": ("long",
                            "name": ("hotspot_name"),
                            "reported_at": 1632353389723,
                            "rssi": -57.0,
                            "snr": 12.5,
                            "spreading": "SF9BW125",
                            "status": "success"
                        },
                    ],
                    "id": ("device_id"),
                    "metadata": {
                        "adr_allowed": false,
                        "cf_list_enabled": false,
                        "multi_buy": 1,
                        "organization_id": ("org_id")
                    },
                    "name": ("device_name"),
                    "payload": ("device_payload"),
                    "payload_size": 27,
                    "port": 1,
                    "reported_at": 1632353389723,
                    "uuid": ("device_id")
                },
                "qos": 0
            }
        },
        "description": "Request sent to <<\"azure-int\">>",
        "device_id": ("device_id"),
        "frame_down": null,
        "frame_up": null,
        "organization_id": ("org_id"),
        "reported_at": "1632353390125",
        "router_uuid": ("router_id"),
        "sub_category": "uplink_integration_req"
    },
}

Create Device

POST https://console.helium.com/api/v1/devices

info

This endpoint is disabled for Helium Foundation Console.

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key
content-type (required)	string	application/json

Body Parameters

Parameter Name	Type	Description
name (required)	string	A human-friendly name for the device
app_eui (required)	string	LoRaWAN Application EUI
app_key (required)	string	LoRaWAN Application Key
dev_eui (required)	string	LoRaWAN Device EUI
config_profile_id (optional)	string	Config profile uuid to attach
label_ids (optional)	Array of strings	Array of label uuids to attach to device

Create Multiple Devices

POST https://console.helium.com/api/v1/devices

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key
content-type (required)	string	application/json

Body Parameters

Parameter Name	Type	Description
devices (required)	Array of objects	Array of up to 1,000 device objects as defined below

Device Object

Key	Value Type	Description
name (required)	string	A human-friendly name for the device
app_eui (required)	string	LoRaWAN Application EUI
app_key (required)	string	LoRaWAN Application Key
dev_eui (required)	string	LoRaWAN Device EUI
config_profile_id (optional)	string	Config profile uuid to attach
label_ids (optional)	Array of strings	Array of label uuids to attach to device

200: ok

{
  "failure": [
    {
      "app_eui": "2111111111111111",
      "app_key": "21111111111111111111111111111111",
      "dev_eui": "2111111111111111",
      "error": "name: Name cannot be blank",
      "organization_id": "b31295c0-7164-4f45-b634-d21d498737cd",
      "oui": 1
    }
  ],
  "success": [
    {
      "app_eui": "1111111111111111",
      "app_key": "11111111111111111111111111111111",
      "config_profile_id": null,
      "dev_eui": "1111111111111111",
      "id": "c13e435e-a122-44c1-8ebb-882d5cf84e8c",
      "labels": [],
      "name": "Test 1"
    }
  ]
}

Delete Device by UUID

DELETE https://console.helium.com/api/v1/devices/:id

Deletes device record by UUID.

Request
Response

Path Parameters

Parameter Name	Type	Description
id (required)	string	UUID of the device to be deleted

200: OK

Device deleted

Labels

GET https://console.helium.com/api/v1/labels

Returns a list of label descriptors associated with the organization.

Response

200: OK

[
    Label {
        id: "20515fce-2f7c-4025-8841-4be47cb9ec3c",
        name: "Test LoRaWAN",
    },
    Label {
        id: "d20d5d32-f699-40a7-a5a7-b9a49dfe2b4a",
        name: "AWS",
    },
    Label {
        id: "a332bb1e-888e-43d9-ad38-f4043fff791f",
        name: "RequestBinDownlink",
    },
    Label {
        id: "19bee2e7-b222-461f-a271-15b3c52d5532",
        name: "MQTT-Test",
    },
]

Create Label

POST https://console.helium.com/api/v1/labels

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key
content-type (required)	string	application/json

Body Parameters

Parameter Name	Type	Description
name (required)	string	A human-friendly name for the device
config_profile_id (optional)	string	Config profile uuid to attach

Delete Label

DELETE https://console.helium.com/api/v1/labels/:label_id

Delete a device label, along with all of its device links.

Request
Response

Path Parameters

Parameter Name	Type	Description
label_id (required)	string	The UUID of the label being searched for

200: OK

Label deleted

404: Not Found

{ "errors": { "error": ["Label not found"] } }

Search for Label

GET https://console.helium.com/api/v1/labels/:label_id

Search for a label by UUID.

Request
Response

Path Parameters

Parameter Name	Type	Description
label_id (required)	string	UUID of label

200: OK

{
  "id": "868ea783-f252-4fc4-b724-a155680c0bc9",
  "multi_buy": 1,
  "name": "Blue Label"
}

404: Not Found

{ "errors": { "error": ["Label not found"] } }

GET https://console.helium.com/api/v1/labels

Search for label by name.

Request
Response

Path Parameters

Parameter Name	Type	Description
name (required)	string	name of label

200: OK

{
  "id": "868ea783-f252-4fc4-b724-a155680c0bc9",
  "multi_buy": 1,
  "name": "Blue Label"
}

404: Not Found

{ "errors": { "error": ["Label not found"] } }

Add Device Label

POST  https://console.helium.com/api/v1/devices/:device_id/labels

Add Device to Label

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key
content-type (required)	string	application/json

Path Parameters

Parameter Name	Type	Description
device_id (required)	string	UUID of device

Body Parameters

Parameter Name	Type	Description
label (required)	string	UUID of label

200: OK

Device added to label successfully

Remove Device Label

DELETE  https://console.helium.com/api/v1/devices/:device_id/labels/:label_id

Remove Device Label

Request
Response

Path Parameters

Parameter Name	Type	Description
device_id (required)	string	UUID of device
label_id (required)	string	UUID of label

200: OK

Device removed from label successfully

Create a Prebuilt Integration

Create prebuilt integration for integration providers planning to offer connectivity as a service.

POST https://console.helium.com/api/v1/integrations/prebuilt

Creates a device with corresponding name, Application EUI, Application Key, and Device EUI.

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key
content-type (required)	string	application/json

Body Parameters

Parameter Name	Type	Description
token (required)	string	Your token, authorization key, uplink secret depending on pre-built integration.
name (required)	string	A unique name for the Integration
type (required)	string	“akenza” “ubidots” “tago” “datacake”

201: Created

{
    "devices": [],
    "id": "8bcf235a-0ee7-4e74-9856-e07c13a863b6",
    "labels": [],
    "name": "name"
}

Create a Custom HTTP Integration

POST https://console.helium.com/api/v1/integrations

Creates a custom HTTP integration. Use the Console UI for JSON message templates.

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	Your API key
content-type (required)	string	application/json

Body Parameters

Parameter Name	Type	Description
name (required)	string	A unique human-friendly name
type (required)	string	“http”
endpoint (required)	string	endpoint
method (required)	string	HTTP method
headers (optional)	map	Map of header keys and values `{ “content-type”: “application/json” }`
url_params (optional)	map	Map for payload interpolation `{ "id": "{{device.id}}"}`

201: Created

{
    "devices": [],
    "id": "8bcf235a-0ee7-4e74-9856-e07c13a863b6",
    "labels": [],
    "name": "name",
    "type": "http"
    "credentials": { … }
}

Create a Custom MQTT Integration

POST https://console.helium.com/api/v1/integrations

Creates a custom MQTT integration.

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	Your API key
content-type (required)	string	application/json

Body Parameters

Parameter Name	Type	Description
name (required)	string	A unique human-friendly name
type (required)	string	“mqtt”
endpoint (required)	string	endpoint
uplink_topic (required)	string	Uplink topic
downlink_topic (required)	string	Downlink topic

201: Created

{
    "devices": [],
    "id": "8bcf235a-0ee7-4e74-9856-e07c13a863b6",
    "labels": [],
    "name": "name",
    "type": "mqtt"
    "credentials": { … }
}

Create a Custom Azure IoT Hub Integration

POST https://console.helium.com/api/v1/integrations

Creates a custom Azure IoT Hub integration.

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	Your API key
content-type (required)	string	application/json

Body Parameters

Parameter Name	Type	Description
name (required)	string	A unique human-friendly name
type (required)	string	“azure”
azure_policy_name (required)	string	Azure IoT Hub policy name
azure_hub_name (required)	string	Azure IoT Hub name
azure_primary_key (required)	string	Azure IoT Hub primary key

201: Created

{
    "devices": [],
    "id": "8bcf235a-0ee7-4e74-9856-e07c13a863b6",
    "labels": [],
    "name": "name",
    "type": "azure"
    "credentials": { … }
}

Create a Custom AWS IoT Core Integration

POST https://console.helium.com/api/v1/integrations

Creates a custom AWS IoT Core integration.

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	Your API key
content-type (required)	string	application/json

Body Parameters

Parameter Name	Type	Description
name (required)	string	A unique human-friendly name
type (required)	string	“aws”
topic (required)	string	AWS topic
aws_access_key (required)	string	AWS access key
aws_secret_key (required)	string	AWS secret key
aws_region (required)	string	AWS region

201: Created

{
    "devices": [],
    "id": "8bcf235a-0ee7-4e74-9856-e07c13a863b6",
    "labels": [],
    "name": "name"
    "type": "aws"
    "credentials": { … }
}

Delete an Integration

DELETE https://console.helium.com/api/v1/integrations/:integration_id

Delete an Integration along with any links to labels.

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key

Path Parameters

Parameter Name	Type	Description
integration_id (required)	string	UUID for removed integration

200: OK

Integration {
    id: "868ea783-f252-4fc4-b724-a155680c0bc9",
    name: "Terry Fox",
    }

404: Not Found

{ "errors": { "error": ["Integration not found"] } }

List Integrations

GET https://console.helium.com/api/v1/integrations/

Returns a list of integrations associated with the organization.

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key

200: OK

    Integration {
        id: "20515fce-2f7c-4025-8841-4be47cb9ec3c",
        name: "Terry Fox"
        labels: [],
        devices: [],
    },
    Integration {
        id: "d20d5d32-f699-40a7-a5a7-b9a49dfe2b4a",
        name: "Tommy Douglas",
        labels: [],
        devices: [],
    },

Search for an Integration by UUID

GET https://console.helium.com/api/v1/integrations/:integration_id

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key

Path Parameters

Parameter Name	Type	Description
integration_id (required)	string	UUID of integration

200: OK

Integration {
    id: "868ea783-f252-4fc4-b724-a155680c0bc9",
    name: "Terry Fox",
     labels: [],
     devices: [],
},

404: Not Found

{ "errors": { "error": ["Integration not found"] } }

Search for an Integration by Name

GET https://console.helium.com/api/v1/integrations?name=your_integration_name

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key

Query Parameters

Parameter Name	Type	Description
name (required)	string	name of integration

200: OK

Integration {
    id: "868ea783-f252-4fc4-b724-a155680c0bc9",
    name: "Terry Fox",
     labels: [],
     devices: [],
},

404: Not Found

{ "errors": { "error": ["Integration not found"] } }

View all Flows for an Integration

GET https://console.helium.com/api/v1/flows?integration_id=your_integration_id

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key

Query Parameters

Parameter Name	Type	Description
integration_id (required)	string	UUID of integration

200: OK

[
{
        "device_id": null,
        "function_id": "7591901a-1299-4893-b0b5-65786c481bcc",
        "id": "1f99c35c-20c5-42f6-b3e4-984bba68ade1",
        "integration_id": "c23f1419-47af-4673-931a-7acdae1ddee5",
        "label_id": "d7c095cb-4923-42c1-967a-5574eedc2dc4",
        "organization_id": "e9ea354a-cf4d-492a-b332-3d2ee4fe177e"
    },
{
        "device_id": null,
        "function_id": "7591901a-1299-4893-b0b5-65786c481bcc",
        "id": "1f99c35c-20c5-42f6-b3e4-984bba68ade1",
        "integration_id": "c23f1419-47af-4673-931a-7acdae1ddee5",
        "label_id": "d7c095cb-4923-42c1-967a-5574eedc2dc4",
        "organization_id": "e9ea354a-cf4d-492a-b332-3d2ee4fe177e"
    }

]

Create a Flow for an Integration

Create a prebuilt integration for partners providing a connectivity as a service solution.

POST https://console.helium.com/api/v1/flows

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key
content-type (required)	string	application/json

Body Parameters

Parameter Name	Type	Description
integration_id (required)	string	UUID of integration
label_id / device_id (required)	string	UUID
function_id (optional)	string	UUID

200: OK

Flow with integration created successfully

{
    "devices": [],
    "id": "8bcf235a-0ee7-4e74-9856-e07c13a863b6",
    "labels": [],
    "name": "name"
}

Delete flow

DELETE https://console.helium.com/api/v1/flows/:flow_id

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key

Path Parameters

Parameter Name	Type	Description
flow_id (required)	string	UUID of flow

200: OK

Flow deleted successfully

Update Device Config Profile

PUT https://console.helium.com/api/v1/devices/:device_id

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key

Path Parameters

Parameter Name	Type	Description
device_id (required)	string	UUID of device

Body Parameters

Parameter Name	Type	Description
config_profile_id (required)	string / null	Config profile uuid to attach or set to null to remove

Update Label Config Profile

PUT https://console.helium.com/api/v1/labels/:label_id

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key

Path Parameters

Parameter Name	Type	Description
label_id (required)	string	UUID of label

Body Parameters

Parameter Name	Type	Description
config_profile_id (required)	string	Config profile uuid to attach or set to null to remove

Update Device Active Status

PUT https://console.helium.com/api/v1/devices/:device_id

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key

Path Parameters

Parameter Name	Type	Description
device_id (required)	string	UUID of device

Body Parameters

Parameter Name	Type	Description
active (required)	string	boolean

Update Devices Active Status

PUT https://console.helium.com/api/v1/devices/active?dev_eui=your_dev_eui

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key

Query Parameters

Parameter Name	Type	Description
dev_eui (required)	string	Device dev_eui
app_eui (optional)	string	Device app_eui
app key (optional)	string	Device app_key

Body Parameters

Parameter Name	Type	Description
active (required)	string	boolean

Update Devices attached to label Active Status

PUT https://console.helium.com/api/v1/labels/:label_id/active

Request
Response

Headers

Parameter Name	Type	Description
key (required)	string	your API key

Path Parameters

Parameter Name	Type	Description
label_id (required) (required)	string	Label uuid

Body Parameters

Parameter Name	Type	Description
active (required)	string	boolean

Base URL​

Authentication​

Data Credit Balance​

Response​

Devices List​

Response​

Devices by AppEui, AppKey, DevEui​

Device by UUID​

Device Events​

Device Integration Events​

Create Device​

Create Multiple Devices​

Delete Device by UUID​

Labels​

Response​

Create Label​

Delete Label​

Search for Label​

Add Device Label​

Remove Device Label​

Create a Prebuilt Integration​

Create a Custom HTTP Integration​

Create a Custom MQTT Integration​

Create a Custom Azure IoT Hub Integration​

Create a Custom AWS IoT Core Integration​

Delete an Integration​

List Integrations​

Search for an Integration by UUID​

Search for an Integration by Name​

View all Flows for an Integration​

Create a Flow for an Integration​

Delete flow​

Update Device Config Profile​

Update Label Config Profile​

Update Device Active Status​

Update Devices Active Status​

Update Devices attached to label Active Status​

Base URL

Authentication

Data Credit Balance

Response

Devices List

Response

Devices by AppEui, AppKey, DevEui

Device by UUID

Device Events

Device Integration Events

Create Device

Create Multiple Devices

Delete Device by UUID

Labels

Response

Create Label

Delete Label

Search for Label

Add Device Label

Remove Device Label

Create a Prebuilt Integration

Create a Custom HTTP Integration

Create a Custom MQTT Integration

Create a Custom Azure IoT Hub Integration

Create a Custom AWS IoT Core Integration

Delete an Integration

List Integrations

Search for an Integration by UUID

Search for an Integration by Name

View all Flows for an Integration

Create a Flow for an Integration

Delete flow

Update Device Config Profile

Update Label Config Profile

Update Device Active Status

Update Devices Active Status

Update Devices attached to label Active Status