API Documentation - PushingBox IoT Notifications API (GET & POST)

HTTP(S) API

Trigger a scenario by sending a GET or POST request to the API endpoint.

Endpoint

GET https://api.pushingbox.com/pushingbox?devid=YOUR_DEVID

POST https://api.pushingbox.com/pushingbox

The same endpoint is also available over plain HTTP (http://api.pushingbox.com/pushingbox) for devices with limited or incomplete SSL/TLS support that have trouble validating certificates.

Parameters

Parameter	Required	Description
devid	Yes	Your scenario DeviceID (16 characters)
[custom]	No	Any additional parameter will be used for variable substitution

Response Codes

Code	Status	Meaning
200	OK	All scenario actions executed successfully
207	Multi-Status	Partial success (some actions succeeded, some failed)
400	Bad Request	Missing or invalid DeviceID format
403	Forbidden	Scenario deactivated/blocked, account blocked, or IP blocked
404	Not Found	DeviceID does not exist
429	Too Many Requests	Daily notification quota exceeded
502	Bad Gateway	All actions failed to execute to downstream services

JSON Response Format

All API responses return structured JSON with action statuses, latencies, and quota information.

{
  "success": true,
  "status": "success",
  "message": "Scenario executed successfully",
  "scenario": {
    "name": "Temperature Alert"
  },
  "summary": {
    "total_actions": 2,
    "successful_actions": 2,
    "failed_actions": 0
  },
  "actions": [
    {
      "order": 1,
      "service": "ntfy",
      "service_name": "Living Room Alerts",
      "status": "success",
      "duration_ms": 142
    },
    {
      "order": 2,
      "service": "email",
      "service_name": "Backup Email",
      "status": "success",
      "duration_ms": 310
    }
  ],
  "quota": {
    "remaining": 94,
    "limit": 100,
    "resets_at": "2026-08-23T00:00:00Z"
  },
  "metadata": {
    "execution_time_ms": 456,
    "timestamp": "2026-08-22T14:30:00Z"
  }
}

{
  "success": false,
  "status": "partial",
  "message": "1 of 2 actions failed to execute",
  "scenario": {
    "name": "Temperature Alert"
  },
  "summary": {
    "total_actions": 2,
    "successful_actions": 1,
    "failed_actions": 1
  },
  "actions": [
    {
      "order": 1,
      "service": "ntfy",
      "service_name": "Living Room Alerts",
      "status": "success",
      "duration_ms": 115
    },
    {
      "order": 2,
      "service": "customurl",
      "service_name": "Home Assistant Webhook",
      "status": "failed",
      "error": {
        "code": "HTTP_ERROR",
        "message": "Target server responded with HTTP 504"
      },
      "duration_ms": 5012
    }
  ],
  "quota": {
    "remaining": 93,
    "limit": 100,
    "resets_at": "2026-08-23T00:00:00Z"
  },
  "metadata": {
    "execution_time_ms": 5130,
    "timestamp": "2026-08-22T14:30:00Z"
  }
}

{
  "success": false,
  "status": "failed",
  "message": "All actions failed to execute",
  "scenario": {
    "name": "Temperature Alert"
  },
  "summary": {
    "total_actions": 1,
    "successful_actions": 0,
    "failed_actions": 1
  },
  "actions": [
    {
      "order": 1,
      "service": "customurl",
      "service_name": "Home Assistant Webhook",
      "status": "failed",
      "error": {
        "code": "CONNECTION_FAILED",
        "message": "Connection timed out or host unreachable"
      },
      "duration_ms": 5003
    }
  ],
  "quota": {
    "remaining": 93,
    "limit": 100,
    "resets_at": "2026-08-23T00:00:00Z"
  },
  "metadata": {
    "execution_time_ms": 5005,
    "timestamp": "2026-08-22T14:30:00Z"
  }
}

{
  "success": false,
  "error": {
    "code": "DAILY_LIMIT_EXCEEDED",
    "message": "Daily notification quota exceeded"
  },
  "quota": {
    "remaining": 0,
    "limit": 100,
    "resets_at": "2026-08-23T00:00:00Z"
  }
}

Custom Variables

You can use custom variables in your notification templates. Any parameter sent in your API request (except devid) will replace its corresponding $variable$ placeholder.

Example

# API call

GET /pushingbox?devid=vABC123&temperature=23&room=kitchen

# Template

The temperature in $room$ is $temperature$°C

# Result

The temperature in kitchen is 23°C

Email API

You can also trigger scenarios by sending an email, using one of two methods:

First method

Send an email to this address with your DeviceID set in the Subject:

# Email address

api@api.pushingbox.com

# Subject

YOUR_DEVID

Second method

In case you can't define the Subject (like a generated email from a web service), put the DeviceID in the email address:

# Email address

api+YOUR_DEVID@api.pushingbox.com

The email subject and body can be used as variables ( $subject$ and $body$ ).

Code Examples

Copy-paste ready examples for your favorite language or platform.

GET request

curl "https://api.pushingbox.com/pushingbox?devid=vABC123&temperature=23&room=kitchen"

POST request

curl -d "devid=vABC123&temperature=23&room=kitchen" https://api.pushingbox.com/pushingbox

Using requests (GET)

import requests

params = {
    "devid": "vABC123",
    "temperature": "23",
    "room": "kitchen"
}

response = requests.get("https://api.pushingbox.com/pushingbox", params=params)
print(response.json())

Using requests (POST)

import requests

data = {
    "devid": "vABC123",
    "temperature": "23",
    "room": "kitchen"
}

response = requests.post("https://api.pushingbox.com/pushingbox", data=data)
print(response.json())

MicroPython (ESP32 / ESP8266 / Pico W)

import urequests

devid = "vABC123"
temperature = "23"
room = "kitchen"

url = f"https://api.pushingbox.com/pushingbox?devid={devid}&temperature={temperature}&room={room}"
response = urequests.get(url)
print(response.json())
response.close()

Home Assistant REST Command (configuration.yaml)

rest_command:
  pushingbox_alert:
    url: "https://api.pushingbox.com/pushingbox?devid={{ devid }}&temperature={{ temperature }}&room={{ room }}"
    method: GET

# In automations.yaml:
# action:
#   - service: rest_command.pushingbox_alert
#     data:
#       devid: "vABC123"
#       temperature: "23"
#       room: "kitchen"

Using cURL

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.pushingbox.com/pushingbox?devid=vABC123&temperature=23&room=kitchen");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
print_r($result);

ESP8266 / ESP32 (WiFi)

#include <WiFi.h>
#include <HTTPClient.h>

const char* ssid = "YOUR_WIFI";
const char* password = "YOUR_PASSWORD";
const char* devid = "vABC123";

void sendNotification(String temperature, String room) {
    HTTPClient http;
    String url = "https://api.pushingbox.com/pushingbox?devid=";
    url += devid;
    url += "&temperature=" + temperature;
    url += "&room=" + room;

    http.begin(url);
    int httpCode = http.GET();
    http.end();
}

void setup() {
    WiFi.begin(ssid, password);
    while (WiFi.status() != WL_CONNECTED) delay(500);
    sendNotification("23", "kitchen");
}

void loop() {}

Arduino Ethernet Shield

#include <SPI.h>
#include <Ethernet.h>

byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
char server[] = "api.pushingbox.com";
EthernetClient client;

void setup() {
    Ethernet.begin(mac);
    delay(1000);

    if (client.connect(server, 80)) {
        client.println("GET /pushingbox?devid=vABC123&temperature=23 HTTP/1.1");
        client.println("Host: api.pushingbox.com");
        client.println("Connection: close");
        client.println();
    }
}

void loop() {}

Using fetch (browser)

const params = new URLSearchParams({
    devid: "vABC123",
    temperature: "23",
    room: "kitchen"
});

fetch(`https://api.pushingbox.com/pushingbox?${params}`)
    .then(response => response.json())
    .then(data => console.log(data));

Using built-in fetch (Node 18+)

const params = new URLSearchParams({
    devid: "vABC123",
    temperature: "23",
    room: "kitchen"
});

const response = await fetch(`https://api.pushingbox.com/pushingbox?${params}`);
const data = await response.json();
console.log(data);

Using http module (older Node.js)

const http = require("http");

const url = "https://api.pushingbox.com/pushingbox?devid=vABC123&temperature=23&room=kitchen";

http.get(url, (res) => {
    let data = "";
    res.on("data", chunk => data += chunk);
    res.on("end", () => console.log(JSON.parse(data)));
});

Limits

• Daily quota: 100 requests/day
• Quota resets every day at midnight UTC