External API

The External API (/external/api/v1/*) is designed for machine-to-machine (M2M) integrations where third-party services push data to VWire or read device values without acting as a user dashboard.

Typical use cases:

• Webhook receivers from cloud IoT platforms
• Home automation bridges (Home Assistant, Node-RED)
• Custom mobile apps
• Third-party analytics pulling time-series data

---

Base URL

https://app.vwire.io/external/api/v1

---

Authentication

Use an External API Key (distinct from user API keys):

1. Go to Dashboard → Settings → External API Keys → New Key
2. Optionally scope the key to specific devices
3. Use in requests:

Authorization: Bearer <external-api-key>

External keys are prefixed with vwx_:

vwx_7f3a1c9e2b844d6fa913c5e28f01b774

---

Push data to a device pin

POST /external/api/v1/devices/{deviceId}/pins/{pin}
Authorization: Bearer vwx_...
Content-Type: application/json

{
  "value": "23.5"
}

This writes the value to the pin exactly as if the device had published it via MQTT:

• Value recorded with timestamp
• Real-time update delivered to open dashboards
• Notification rules evaluated

---

Read latest pin value

GET /external/api/v1/devices/{deviceId}/pins/{pin}
Authorization: Bearer vwx_...

Response:

{
  "pin": 0,
  "value": "23.5",
  "deviceId": "uuid",
  "timestamp": "2024-03-15T10:30:00.000Z"
}

---

Get device status

GET /external/api/v1/devices/{deviceId}/status
Authorization: Bearer vwx_...

Response:

{
  "deviceId": "uuid",
  "name": "Greenhouse Sensor",
  "status": "online",
  "lastSeen": "2024-03-15T10:30:00.000Z"
}

---

Webhook integration example

Receive data from a third-party platform and forward to VWire:

// Node.js webhook handler
app.post('/webhook/sensor', async (req, res) => {
  const { deviceId, temperature, humidity } = req.body;

  await fetch(`https://app.vwire.io/external/api/v1/devices/${deviceId}/pins/0`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.VWIRE_EXTERNAL_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ value: String(temperature) }),
  });

  res.json({ ok: true });
});

---

Rate limits

External API keys share the same rate limits as standard API keys but are tracked separately per key, allowing higher burst rates for integrations.

Plan	External API limit
Free	60 req/min per key
Pro	600 req/min per key
Enterprise	Custom