Skip to main content

HTTP API Integration

The HTTP API provides a REST-based alternative to MQTT for devices that cannot maintain persistent connections or operate behind restrictive firewalls.

Authentication​

All HTTP API requests require authentication using the Device Access Token.

Header:

Authorization: Bearer {DEVICE_ACCESS_TOKEN}

Getting Your Token:

  1. Navigate to Device Details in the platform dashboard.
  2. Go to the "Credentials" tab.
  3. Copy the Access Token.

Endpoints​

Base URL​

https://api.sensocan.com/api/v1

1. Single Sensor Reading​

Send a single data point for a specific sensor.

Endpoint:

POST /devices/{device_uuid}/sensors/{sensor_uuid}/readings

Headers:

Authorization: Bearer {DEVICE_ACCESS_TOKEN}
Content-Type: application/json

Request Body:

{
  "data": {
    "value": 25.5,
    "timestamp": "2023-10-27T10:00:00Z"
  },
  "battery_voltage": 3.7
}

Field Descriptions:

  • data (required, object): Container for sensor reading.
    • value (required, numeric): The sensor reading value.
    • timestamp (optional, ISO 8601 string): Reading timestamp. Defaults to server time if omitted.
  • battery_voltage (optional, numeric): Device battery level in volts (0-100).

Success Response (201 Created):

{
  "message": "Reading stored successfully.",
  "sensor": "7a8b9c0d-1234-5678-90ab-cdef12345678"
}

cURL Example:

curl -X POST https://api.sensocan.com/api/v1/devices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/sensors/7a8b9c0d-1234-5678-90ab-cdef12345678/readings \
  -H "Authorization: Bearer your-device-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "value": 25.5,
      "timestamp": "2023-10-27T10:00:00Z"
    },
    "battery_voltage": 3.7
  }'

2. Bulk Sensor Readings​

Upload multiple historical readings for a single sensor (e.g., offline data sync).

Endpoint:

POST /devices/{device_uuid}/sensors/{sensor_uuid}/readings/bulk

Headers:

Authorization: Bearer {DEVICE_ACCESS_TOKEN}
Content-Type: application/json

Request Body:

{
  "data": [
    { "value": 22.1, "timestamp": "2023-10-27T09:00:00Z" },
    { "value": 22.4, "timestamp": "2023-10-27T09:15:00Z" },
    { "value": 22.8, "timestamp": "2023-10-27T09:30:00Z" }
  ],
  "battery_voltage": 3.6
}

Field Descriptions:

  • data (required, array): Array of reading objects. Must contain at least 1 item.
    • value (required, numeric): The sensor reading value.
    • timestamp (optional, ISO 8601 string): Reading timestamp.
  • battery_voltage (optional, numeric): Device battery level in volts (0-100).

Success Response (201 Created):

{
  "message": "Successfully stored 3 readings.",
  "sensor": "7a8b9c0d-1234-5678-90ab-cdef12345678",
  "count": 3
}

3. Batch Readings (Multiple Sensors)​

Send readings for multiple sensors in a single request. This is the most bandwidth-efficient method.

Endpoint:

POST /devices/{device_uuid}/readings

Headers:

Authorization: Bearer {DEVICE_ACCESS_TOKEN}
Content-Type: application/json

Request Body:

{
  "data": [
    {
      "sensor_slug": "temp_01",
      "value": 25.5,
      "timestamp": "2023-10-27T10:00:00Z"
    },
    {
      "sensor_uuid": "7a8b9c0d-1234-5678-90ab-cdef12345678",
      "value": 60.2
    },
    {
      "sensor_slug": "battery_level",
      "value": 95
    }
  ],
  "battery_voltage": 3.7
}

Field Descriptions:

  • data (required, array): Array of multi-sensor readings. Must contain at least 1 item.
    • sensor_slug (conditionally required): Sensor identifier slug. Required if sensor_uuid is not provided.
    • sensor_uuid (conditionally required): Sensor identifier UUID. Required if sensor_slug is not provided.
    • value (required, numeric): The sensor reading value.
    • timestamp (optional, ISO 8601 string): Reading timestamp.
  • battery_voltage (optional, numeric): Device battery level in volts (0-100).

Success Response (201 Created):

{
  "message": "Successfully processed 3 readings.",
  "count": 3
}

Error Responses​

401 Unauthorized​

Cause: Invalid or missing Access Token.

{
  "message": "Unauthenticated."
}

Solution: Verify the token in the Authorization header matches the Device Access Token exactly.

404 Not Found​

Cause: Device UUID or Sensor UUID does not exist.

{
  "message": "Device not found."
}

Solution:

  • Verify the device_uuid in the URL matches your Device UUID.
  • Verify the sensor_uuid in the URL matches a sensor configured on that device.

422 Unprocessable Entity​

Cause: Validation failed (invalid payload structure).

{
  "message": "Validation failed.",
  "errors": {
    "data.value": ["The sensor value is required."],
    "data.timestamp": ["The data.timestamp field must be a valid date."]
  }
}

Common Validation Errors:

  • Missing data.value field
  • value is not numeric
  • timestamp is not in ISO 8601 format
  • Missing both sensor_slug and sensor_uuid in batch requests
  • battery_voltage is outside the 0-100 range

429 Too Many Requests​

Cause: Rate limit exceeded (1000 requests per minute per device).

{
  "message": "Too Many Requests"
}

Solution: Implement exponential backoff or reduce request frequency.

Best Practices​

1. Use Batch Endpoint for Multiple Sensors​

Instead of making 3 separate requests for 3 sensors, use the batch endpoint:

❌ Don't:

POST /devices/{uuid}/sensors/{sensor_uuid_1}/readings
POST /devices/{uuid}/sensors/{sensor_uuid_2}/readings
POST /devices/{uuid}/sensors/{sensor_uuid_3}/readings

✅ Do:

POST /devices/{uuid}/readings
# With all 3 sensors in the payload

2. Include Timestamps for Offline Data​

If your device collects data while offline, include the actual measurement timestamp:

{
  "data": {
    "value": 25.5,
    "timestamp": "2023-10-27T08:00:00Z"
  }
}

3. Handle Errors Gracefully​

  • 401/404: Log error and alert administrator.
  • 422: Log validation errors for debugging.
  • 429: Implement retry with exponential backoff.

Rate Limiting​

  • Limit: 1000 requests per minute per device
  • Header: X-RateLimit-Remaining shows remaining requests
  • Response Code: 429 Too Many Requests when exceeded

Getting URL Parameters​

Device UUID​

  • Found in Device Details page under "Overview" tab.
  • Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Sensor UUID​

  • Found in Device Details > Sensors tab.
  • Example: 7a8b9c0d-1234-5678-90ab-cdef12345678

Sensor Slug​

  • Used in batch endpoint payloads if UUID is not provided.
  • Found in Device Details > Sensors tab.
  • Example: temp_01, humidity_sensor, gps_lat