Developer Guide

API Quickstart

Connect to the Growbud API in a few minutes

Full API Reference

Multiple languages

Examples in JavaScript, Python, and cURL

Get credentials

Open the Growbud web app to generate API tokens

Full documentation

Open the complete API reference with interactive docs

Before you start

You need:

•A Growbud account (create one in the mobile app)
•API credentials from growbud.app
•At least one Growbud sensor linked to your account

No sensor yet? Email support@growbud.io for simulation options to test the API.

Step-by-step code examples

Use these examples to pull Growbud sensor data into your application. Choose a language and copy the snippets.

1. Install the SDK

Install the dependencies you need for API requests.

npm install axios
# or
yarn add axios

2. Set up authentication

Set your API credentials. Get the API URL and token from the Growbud web app.

// Save these in environment variables or a secure config file
const API_URL = 'YOUR_API_URL'; // Get from Growbud web app
const API_TOKEN = 'YOUR_API_TOKEN'; // Get from Growbud web app
const headers = {
  'Authorization': `Bearer ${API_TOKEN}`,
  'Content-Type': 'application/json'
};

3. Check your API balance

Check your API balance in USD before you make requests.

async function checkBalance() {
  try {
    const response = await axios.get(`${API_URL}/api/balance`, {
      headers: headers
    });
    
    console.log('API Balance remaining: $' + response.data.balanceUsd);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}
checkBalance();

4. List your sensors

List all sensors accessible to your account.

const axios = require('axios');
async function listSensors() {
  try {
    const response = await axios.get(`${API_URL}/api/list-sensors`, {
      headers: headers
    });
    
    console.log('Available sensors:', response.data.serialNumbers);
    console.log('LoRaWAN sensors:', response.data.lorawanSensors);
    console.log('Balance remaining: $' + response.headers['x-api-balance-usd']);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}
listSensors();

5. Query sensor data

Get sensor data for selected devices over a time period.

async function querySensorData() {
  try {
    const params = {
      duration: 24, // Last 24 hours
      serialNumbers: '[E200201B,E2002022]', // Your sensor serial numbers
      format: 'json' // or 'csv'
    };
    
    const response = await axios.get(`${API_URL}/api/query`, {
      headers: headers,
      params: params
    });
    
    // Process the data for each sensor
    for (const [sensorId, sensorData] of Object.entries(response.data)) {
      console.log(`\nSensor ${sensorId}:`);
      console.log('Fields:', sensorData.metadata.fields);
      console.log('Units:', sensorData.metadata.units);
      
      // Get latest reading
      if (sensorData.data && sensorData.data.length > 0) {
        console.log('Latest reading:', sensorData.data[sensorData.data.length - 1]);
      }
    }
    
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}
querySensorData();

6. Get latest sensor readings

Get the most recent data for your sensors.

async function getLatestReadings() {
  try {
    const params = {
      maxAge: 2 // Maximum age in days (1-8)
    };
    
    const response = await axios.get(`${API_URL}/api/latest`, {
      headers: headers,
      params: params
    });
    
    // Process each sensor's latest data
    response.data.forEach(sensor => {
      console.log(`\nSensor: ${sensor.name} (${sensor.serialNumber})`);
      console.log(`Last seen: ${sensor.lastSeen}`);
      console.log(`Online: ${sensor.isOnline}`);
      console.log(`VWC: ${sensor.data.soil_vwc}%`);
      console.log(`EC: ${sensor.data.pore_ec} mS/cm`);
      console.log(`Temperature: ${sensor.data.air_temp}°F`);
      console.log(`VPD: ${sensor.data.vpd} kPa`);
    });
    
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}
getLatestReadings();

7. Get sensor thresholds

Get threshold settings for your sensors and zones. Thresholds are read-only in the cloud API. Change them in the Growbud app or on an Edge Server.

async function getThresholds() {
  try {
    // Get thresholds for specific sensors
    const params = {
      serialNumbers: '[E200201B,E2002022]',
      includeZones: 'true' // Set to 'true' to include zone thresholds
    };
    
    const response = await axios.get(`${API_URL}/api/thresholds`, {
      headers: headers,
      params: params
    });
    
    // Process threshold data
    response.data.forEach(item => {
      if (item.serialNumber) {
        console.log(`\nSensor: ${item.name} (${item.serialNumber})`);
      } else if (item.zoneId) {
        console.log(`\nZone: ${item.zoneName}`);
      }
      console.log('Thresholds:', JSON.stringify(item.thresholds, null, 2));
      console.log('Grow Media:', item.growMedia);
    });
    
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}
getThresholds();

8. Read a Climate or CO2 Sensor

LoRaWAN Climate Sensors (Dragino LHT65N) and CO2 Sensors (Dragino AQS01-L) use a 16-hex DevEUI as their id, not the label serial. Get the DevEUIs from /api/list-sensors, then send them in devEuis. History goes back 7 days.

async function readLorawanSensors() {
  try {
    // DevEUIs are in the lorawanSensors array
    const list = await axios.get(`${API_URL}/api/list-sensors`, { headers });
    const devEuis = list.data.lorawanSensors.map(s => s.devEui);
    if (devEuis.length === 0) return;
    const latest = await axios.get(`${API_URL}/api/latest`, {
      headers: headers,
      params: { devEuis: `[${devEuis.join(',')}]` }
    });
    latest.data.forEach(sensor => {
      console.log(`\n${sensor.name} (${sensor.devEui}, ${sensor.model})`);
      console.log(`Temperature: ${sensor.data.air_temp}°F`);
      console.log(`Humidity: ${sensor.data.humidity}%`);
      console.log(`CO2: ${sensor.data.co2} ppm`); // CO2 Sensor only
      console.log(`Thresholds from: ${sensor.thresholdSource}`);
    });
    // History: 7 days at most. A longer duration is cut to 168 hours.
    const history = await axios.get(`${API_URL}/api/query`, {
      headers: headers,
      params: { duration: 168, devEuis: `[${devEuis.join(',')}]` }
    });
    for (const [devEui, sensorData] of Object.entries(history.data)) {
      console.log(devEui, sensorData.metadata.fields, sensorData.data.length, 'rows');
    }
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}
readLorawanSensors();