Surfact provides a powerful, API-driven platform to manage and query data from devices belonging to your organization. We support REST, MQTT and Webhooks. This collection will provide you the essentials - from fetching device and variable data to setting up alerts/triggers that can be integrated into your fleet, warehouse, ERP, or transport management system.
200 OK? Drop us a line at: support@surfact.comEvery request to the Surfact API requires a token. A token is a unique key that authorizes your requests.
\nYour API token is available in the My Profile section of your Surfact account.
\nInclude the token in the request header:
\nX-Auth-Token: your_token_here\n\nExample:
\ncurl -X POST 'https://api.surfact.com/api/v2.0/devices/' \\\n -H 'Content-Type: application/json' \\\n -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73' \\\n -d '{}'\n\nFor web and mobile applications, Surfact supports OAuth2 bearer tokens. Contact us for implementation details if you are considering this approach.
\n","_postman_id":"08a02df4-134d-4a04-b4b1-c0edd39fb1cf","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"bb149234-c87f-4bc8-962b-0ecf72fc6904","id":"bb149234-c87f-4bc8-962b-0ecf72fc6904","name":"Getting Started","type":"folder"}}},{"name":"Data Structure Overview","item":[],"id":"014d2dfe-c61d-4416-b4cd-1093a3e6f8ec","description":"Every time a device updates a sensor value in a variable, a data-point or \"dot\" is created. Surfact stores dots that come from your devices inside variables, and these stored dots have corresponding timestamps.
\nEach dot contains these items:
\nA numerical value. Surfact accepts up to 16 floating-point length numbers.
\n{\n \"value\": 34.87654974\n}\n\nA timestamp is a way to track time as a running total of seconds. This count starts at the Unix Epoch on January 1st, 1970 at UTC.
\nWhen you send data to Surfact, you must set the timestamp in milliseconds. If you retrieve a dot's timestamp, it will also be in milliseconds.
\n{\n \"timestamp\": 1537453824000\n}\n\nThe above timestamp corresponds to Thursday, September 20, 2018 2:30:24 PM.
\n💡 Pro Tip: Use Epoch Converter to convert between Unix timestamps and human-readable dates.
\nNumerical values are not the only data type supported. You can also store string or char data types inside what we call context. The context is a key-value object that allows you to store both numerical and string values.
\nExample:
\n{\n \"context\": {\n \"status\": \"on\",\n \"weather\": \"sunny\"\n }\n}\n\nContext is commonly used to store the latitude and longitude coordinates of your device for GPS/tracking applications. All Surfact maps use the lat and lng keys from a dot's context to extract your device's coordinates.
This means you only need to send a single dot with the coordinates in the variable context to plot a map, instead of sending latitude and longitude separately in two different variables.
\nExample with GPS coordinates:
\n{\n \"context\": {\n \"lat\": -6.2,\n \"lng\": 75.4,\n \"weather\": \"sunny\"\n }\n}\n\n⚠️ Note: You can mix both string and numerical values in the context. For geo-localization applications, make sure coordinates are set in decimal degrees.
\n","_postman_id":"014d2dfe-c61d-4416-b4cd-1093a3e6f8ec","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"bb149234-c87f-4bc8-962b-0ecf72fc6904","id":"bb149234-c87f-4bc8-962b-0ecf72fc6904","name":"Getting Started","type":"folder"}}},{"name":"Identifiers - Key vs. ID","item":[],"id":"75f27009-851c-4844-9926-a4a5dbec206f","description":"This section explains the difference between using keys or IDs.
\nA key is an identifier that allows you to identify entities such as Devices or Variables. Entity Key parameters in the path are defined as , e.g. .
\nEntity Keys allow you to identify the entity instance with their corresponding id or label. The label identification should use the prefix ~.
Example:
\n# GET Request to Obtain a Specific Device\n# URL Definition\nhttps://api.surfact.com/api/v2.0/devices/<device_key>/\n# Identification using Device Id\nhttps://api.surfact.com/api/v2.0/devices/4f169cc906d07d65aa7a/\n# Identification using Device Label\nhttps://api.surfact.com/api/v2.0/devices/~first-device/\n\nAn id is an identifier that allows you to identify entities such as Devices or Variables. Entity Id parameters in the path are defined as , e.g. .
\nEntity Ids allow you to identify the entity instance only by their id.
Example:
\n# GET Request to Obtain a Specific Event Log\n# URL Definition\nhttps://api.surfact.com/api/v2.0/events/<event_key>/logs/<log_id>/\n# Identification using Log Id\nhttps://api.surfact.com/api/v2.0/events/<event_key>/logs/6d07d65aa7a4f169cc90/\n\nCertain POST requests have an entity parameter. A good example is the request to Create an Event. This request has organization as an organization_key parameter.
When creating an event, the organization parameter can be sent in any of the following ways:
\n# POST Request to Create an Event\ncurl -X POST 'https://api.surfact.com/api/v2.0/events/' \\\n -H 'Content-Type: application/json' \\\n -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73' \\\n -d '{\n # Sending Organization using the Id\n \"organization\": \"567890ff1d8472686e9abb4f\"\n # Sending Organization using the Label\n \"organization\": \"~first-organization\"\n # Sending Organization as Object\n \"organization\": {\"id\": \"567890ff1d8472686e9abb4f\"}\n }'\n\nIt's simple: all entity parameters in the body are Keys, hence they can be identified with their id, but also as an object or with their label.
When you make an HTTP request, the Surfact API returns standard HTTP status codes to indicate success or failure:
\n","_postman_id":"b47b5a47-48cb-4d62-b8c0-1d80475452b2","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"bb149234-c87f-4bc8-962b-0ecf72fc6904","id":"bb149234-c87f-4bc8-962b-0ecf72fc6904","name":"Getting Started","type":"folder"}}}],"id":"bb149234-c87f-4bc8-962b-0ecf72fc6904","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"396d1ea5-2c09-4a71-a354-9c00687d0f59","type":"text/javascript","packages":{},"requests":{},"exec":[""]}},{"listen":"test","script":{"id":"98e6fc4a-e4a6-465e-98eb-8de26dc9d5a8","type":"text/javascript","packages":{},"requests":{},"exec":["default test this org","//try this one out",""]}}],"_postman_id":"bb149234-c87f-4bc8-962b-0ecf72fc6904","description":""},{"name":"🌡️ Device Data API","item":[{"name":"Variable Data","id":"4a34bc2f-1763-4f38-8f2a-1b74cefc9896","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.surfact.com/api/v1.6/variables/This endpoint retrieves variable data points.
\nWhere variable_ID is the ID of the variable from which data will be retrieved.
\n\n\nDefault Behavior: This endpoint retrieves the last 100 data points by default. Use query parameters to filter the request.
\n
curl -X GET 'https://api.surfact.com/api/v1.6/variables/<variable_id>/values/?page_size=1' \\\n -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73'\n\nResponse:
\n{\n \"count\": true,\n \"next\": \"https://api.surfact.com/api/v1.6/variables/<variable_id>/values/?page_size=1&page=2\",\n \"previous\": null,\n \"results\": [\n {\n \"timestamp\": 1635264014782,\n \"value\": 0,\n \"context\": {},\n \"created_at\": 1635264014782\n }\n ]\n}\n\ncurl -X GET 'https://api.surfact.com/api/v1.6/variables/<variable_id>/values/?page_size=2' \\\n -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73'\n\nResponse:
\n{\n \"count\": true,\n \"next\": \"https://api.surfact.com/api/v1.6/variables/<variable_id>/values/?page_size=2&page=2\",\n \"previous\": null,\n \"results\": [\n {\n \"timestamp\": 1635264014782,\n \"value\": 0,\n \"context\": {},\n \"created_at\": 1635264014782\n },\n {\n \"timestamp\": 1635264000173,\n \"value\": 0,\n \"context\": {},\n \"created_at\": 1635264000173\n }\n ]\n}\n\nRetrieves data points between 21/10/2021 00:00:00 and 21/10/2021 00:30:00:
\ncurl -X GET 'https://api.surfact.com/api/v1.6/variables/<variable_id>/values/?start=1634792400000&end=1634794200000' \\\n -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73'\n\nResponse:
\n{\n \"count\": true,\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"timestamp\": 1634793902308,\n \"value\": 65084.81,\n \"context\": {\n \"Currency\": \"USD\"\n },\n \"created_at\": 1634793902308\n },\n {\n \"timestamp\": 1634793603356,\n \"value\": 65006.39,\n \"context\": {\n \"Currency\": \"USD\"\n },\n \"created_at\": 1634793603356\n }\n ]\n}\n\nRetrieves all data points from 21/10/2021 00:00:00 to present:
\ncurl -X GET 'https://api.surfact.com/api/v1.6/variables/<variable_id>/values/?start=1634792400000' \\\n -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73'\n\nResponse:
\n{\n \"count\": true,\n \"next\": \"https://api.surfact.com/api/v1.6/variables/<variable_id>/values/?start=1634792400000&page=2\",\n \"previous\": null,\n \"results\": [\n {\n \"timestamp\": 1635368101148,\n \"value\": 58920.82,\n \"context\": {\n \"Currency\": \"USD\"\n },\n \"created_at\": 1635368101148\n }\n ]\n}\n\nRetrieves data points in CSV format:
\ncurl -X GET 'https://api.surfact.com/api/v1.6/variables/<variable_id>/values/?start=1634792400000&end=1634794200000&format=csv' \\\n -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73'\n\nResponse:
\ncontext.Currency,created_at,human_readable_date,timestamp,value\nUSD,1634793902308,2021-10-21 01:25:02.308000-04:00,1634793902308,65084.81\nUSD,1634793603356,2021-10-21 01:20:03.356000-04:00,1634793603356,65006.39\nUSD,1634793302168,2021-10-21 01:15:02.168000-04:00,1634793302168,65120.26\n\n{\n \"code\": 401002,\n \"message\": \"Incorrect authentication credentials.\"\n}\n\nThis endpoint retrieves aggregated statistics for a variable within a specified time range.
\n)
\nimport requests\nfrom datetime import datetime\n# Your credentials\nTOKEN = \"your_token_here\"\nVARIABLE_ID = \"your_variable_id\"\n# Time range (example: full day on Nov 24, 2021)\nstart = 1637730000000 # milliseconds\nend = 1637816399999\n# Get mean value\nurl = f\"https://api.surfact.com/api/v1.6/variables/{VARIABLE_ID}/statistics/mean/{start}/{end}\"\nheaders = {\"X-Auth-Token\": TOKEN}\nresponse = requests.get(url, headers=headers)\ndata = response.json()\nprint(f\"Mean value: {data['mean']}\")\n\nconst TOKEN = \"your_token_here\";\nconst VARIABLE_ID = \"your_variable_id\";\n// Time range\nconst start = 1637730000000;\nconst end = 1637816399999;\n// Get mean value\nconst url = `https://api.surfact.com/api/v1.6/variables/${VARIABLE_ID}/statistics/mean/${start}/${end}`;\nfetch(url, {\n headers: {\n \"X-Auth-Token\": TOKEN\n }\n})\n .then(response => response.json())\n .then(data => console.log(\"Mean value:\", data.mean))\n .catch(error => console.error(\"Error:\", error));\n\nTimestamps must be in milliseconds (POSIX format)
\nTime range is inclusive on both start and end
\nFor available aggregation types, see the aggregation parameter options above
Aggregate data from one or multiple variables within a specified time range. This endpoint can return either a single aggregated value across all variables or individual values per variable.
\nNo start or end: Uses last 100 values from each variable
Only start: Aggregates from start timestamp to current time
Only end: Aggregates from beginning of data to end timestamp
Both start and end: Aggregates within specified range (inclusive)
Get the mean value across multiple variables combined into one result:
\ncurl -X POST 'https://api.surfact.com/api/v1.6/data/stats/aggregation/' \\\n -H 'Content-Type: application/json' \\\n -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73' \\\n -d '{\n \"variables\": [\"618848b4b09758ded46bafda\", \"618848b7b31be1cb509c0a3c\"],\n \"aggregation\": \"mean\",\n \"join_dataframes\": true,\n \"start\": 1636321611000,\n \"end\": 1636321629000,\n \"tz\": \"America/New_York\",\n \"precision\": 2\n }'\n\nSuccess Response (200):
\n{\n \"results\": [\n {\n \"value\": 62873.88,\n \"timestamp\": 1636318800000\n }\n ]\n}\n\nGet mean values for each variable separately:
\ncurl -X POST 'https://api.surfact.com/api/v1.6/data/stats/aggregation/' \\\n -H 'Content-Type: application/json' \\\n -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73' \\\n -d '{\n \"variables\": [\"618848b4b09758ded46bafda\", \"618848b7b31be1cb509c0a3c\"],\n \"aggregation\": \"mean\",\n \"join_dataframes\": false,\n \"start\": 1636321611000,\n \"end\": 1636321629000,\n \"tz\": \"America/New_York\",\n \"precision\": 2\n }'\n\nSuccess Response (200):
\n{\n \"results\": [\n {\n \"value\": 62858.45,\n \"timestamp\": 1636318807253\n },\n {\n \"value\": 62920.19,\n \"timestamp\": 1636318800000\n }\n ]\n}\n\n400 Bad Request (Invalid JSON):
\n{\n \"detail\": \"JSON parse error - Expecting value: line 4 column 22 (char 121)\"\n}\n\n401 Unauthorized:
\n{\n \"code\": 401001,\n \"message\": \"Authentication credentials were not provided.\"\n}\n\nimport requests\nfrom datetime import datetime, timezone\nTOKEN = \"your_token_here\"\nVARIABLE_IDS = [\"618848b4b09758ded46bafda\", \"618848b7b31be1cb509c0a3c\"]\nurl = \"https://api.surfact.com/api/v1.6/data/stats/aggregation/\"\nheaders = {\n \"X-Auth-Token\": TOKEN,\n \"Content-Type\": \"application/json\"\n}\n# Get combined mean across all variables\npayload = {\n \"variables\": VARIABLE_IDS,\n \"aggregation\": \"mean\",\n \"join_dataframes\": True,\n \"start\": 1636321611000,\n \"end\": 1636321629000,\n \"tz\": \"America/New_York\",\n \"precision\": 2\n}\nresponse = requests.post(url, json=payload, headers=headers)\ndata = response.json()\nprint(f\"Combined mean: {data['results'][0]['value']}\")\n# Get individual means per variable\npayload[\"join_dataframes\"] = False\nresponse = requests.post(url, json=payload, headers=headers)\ndata = response.json()\nfor i, result in enumerate(data['results']):\n print(f\"Variable {i+1} mean: {result['value']}\")\n\nconst TOKEN = \"your_token_here\";\nconst VARIABLE_IDS = [\"618848b4b09758ded46bafda\", \"618848b7b31be1cb509c0a3c\"];\nconst url = \"https://api.surfact.com/api/v1.6/data/stats/aggregation/\";\n// Get combined mean across all variables\nconst payload = {\n variables: VARIABLE_IDS,\n aggregation: \"mean\",\n join_dataframes: true,\n start: 1636321611000,\n end: 1636321629000,\n tz: \"America/New_York\",\n precision: 2\n};\nfetch(url, {\n method: \"POST\",\n headers: {\n \"X-Auth-Token\": TOKEN,\n \"Content-Type\": \"application/json\"\n },\n body: JSON.stringify(payload)\n})\n .then(response => response.json())\n .then(data => console.log(\"Combined mean:\", data.results[0].value))\n .catch(error => console.error(\"Error:\", error));\n// Get individual means per variable\npayload.join_dataframes = false;\nfetch(url, {\n method: \"POST\",\n headers: {\n \"X-Auth-Token\": TOKEN,\n \"Content-Type\": \"application/json\"\n },\n body: JSON.stringify(payload)\n})\n .then(response => response.json())\n .then(data => {\n data.results.forEach((result, i) => {\n console.log(`Variable ${i+1} mean:`, result.value);\n });\n })\n .catch(error => console.error(\"Error:\", error));\n\nCombined aggregation (join_dataframes: true):
Calculate average temperature across multiple sensors
\nGet total count of events across different sources
\nFind maximum value across all monitoring points
\nIndividual aggregation (join_dataframes: false):
Compare performance of different sensors
\nMonitor individual device metrics
\nGenerate per-variable reports
\nAll timestamps are in milliseconds (POSIX format)
\nTime ranges are inclusive on both start and end
\nWithout precision specified, results use full decimal precision
\nToken expires after 6 hours - generate fresh tokens as needed
\nTimezone defaults to UTC if not specified
\nRetrieve raw (unaggregated) data from one or multiple variables within a specified time range. This endpoint returns the actual data points with customizable columns.
\nEndpoint:
\nSpecify which data fields to include in the response:
\nNo start or end: Returns last 100 values from each variable
Only start: Returns values from start timestamp to most recent data point
Only end: Returns values from earliest data point to end timestamp
Both start and end: Returns values within specified range (inclusive)
Retrieve 1 hour of raw data from multiple variables:
\ncurl -X POST 'https://api.surfact.com/api/v1.6/data/raw/series' \\\n -H 'Content-Type: application/json' \\\n -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73' \\\n -d '{\n \"variables\": [\"618848b4b09758ded46bafda\", \"618848b7b31be1cb509c0a3c\"],\n \"columns\": [\"value.value\", \"timestamp\"],\n \"join_dataframes\": false,\n \"start\": 1636318800000,\n \"end\": 1636322400000,\n \"tz\": \"America/New_York\",\n \"precision\": 2\n }'\n\nSuccess Response (200):
\n{\n \"results\": [\n [\n [62982.21, 1636322400000],\n [62983.08, 1636321200000],\n [63038.95, 1636320000000],\n [62796.23, 1636318800000]\n ],\n [\n [62850.38, 1636322101553],\n [62883.23, 1636321804316],\n [62870.37, 1636321503773],\n [62983.08, 1636321204195]\n ]\n ],\n \"columns\": [\n [\"5b17df86642ab66a5f6037d8.value.value\", \"timestamp\"],\n [\"5ae73c56bbddbd669ed87e0a.value.value\", \"timestamp\"]\n ]\n}\n\nRetrieve the last 3 values from multiple variables:
\ncurl -X POST 'https://api.surfact.com/api/v1.6/data/raw/series' \\\n -H 'Content-Type: application/json' \\\n -H 'X-Auth-Token: oaXBo6ODhIjPsusNRPUGIK4d72bc73' \\\n -d '{\n \"variables\": [\"618848b4b09758ded46bafda\", \"618848b7b31be1cb509c0a3c\"],\n \"columns\": [\"value.value\", \"timestamp\"],\n \"join_dataframes\": false,\n \"limit\": 3,\n \"tz\": \"America/New_York\",\n \"precision\": 2\n }'\n\nSuccess Response (200):
\n{\n \"results\": [\n [\n [62982.21, 1636322400000],\n [62983.08, 1636321200000],\n [63038.95, 1636320000000]\n ],\n [\n [62850.38, 1636322101553],\n [62883.23, 1636321804316],\n [62870.37, 1636321503773]\n ]\n ],\n \"columns\": [\n [\"5b17df86642ab66a5f6037d8.value.value\", \"timestamp\"],\n [\"5ae73c56bbddbd669ed87e0a.value.value\", \"timestamp\"]\n ]\n}\n\n400 Bad Request (Invalid JSON):
\n{\n \"detail\": \"JSON parse error - Expecting value: line 4 column 22 (char 121)\"\n}\n\n401 Unauthorized:
\n{\n \"code\": 401001,\n \"message\": \"Authentication credentials were not provided.\"\n}\n\nimport requests\nimport pandas as pd\nfrom datetime import datetime\nTOKEN = \"your_token_here\"\nVARIABLE_IDS = [\"618848b4b09758ded46bafda\", \"618848b7b31be1cb509c0a3c\"]\nurl = \"https://api.surfact.com/api/v1.6/data/raw/series\"\nheaders = {\n \"X-Auth-Token\": TOKEN,\n \"Content-Type\": \"application/json\"\n}\n# Get raw data with time range\npayload = {\n \"variables\": VARIABLE_IDS,\n \"columns\": [\"value.value\", \"timestamp\", \"variable.name\"],\n \"join_dataframes\": False,\n \"start\": 1636318800000,\n \"end\": 1636322400000,\n \"tz\": \"America/New_York\",\n \"precision\": 2\n}\nresponse = requests.post(url, json=payload, headers=headers)\ndata = response.json()\n# Process results for each variable\nfor i, variable_data in enumerate(data['results']):\n print(f\"\\nVariable {i+1}:\")\n print(f\"Columns: {data['columns'][i]}\")\n print(f\"Data points: {len(variable_data)}\")\n # Convert to DataFrame for easy analysis\n df = pd.DataFrame(variable_data, columns=data['columns'][i])\n print(df.head())\n# Get just the last 5 values\npayload_recent = {\n \"variables\": VARIABLE_IDS,\n \"columns\": [\"value.value\", \"timestamp\"],\n \"limit\": 5,\n \"precision\": 2\n}\nresponse = requests.post(url, json=payload_recent, headers=headers)\nrecent_data = response.json()\nprint(f\"\\nMost recent values: {recent_data['results'][0]}\")\n\nconst TOKEN = \"your_token_here\";\nconst VARIABLE_IDS = [\"618848b4b09758ded46bafda\", \"618848b7b31be1cb509c0a3c\"];\nconst url = \"https://api.surfact.com/api/v1.6/data/raw/series\";\n// Get raw data with time range\nconst payload = {\n variables: VARIABLE_IDS,\n columns: [\"value.value\", \"timestamp\", \"variable.name\"],\n join_dataframes: false,\n start: 1636318800000,\n end: 1636322400000,\n tz: \"America/New_York\",\n precision: 2\n};\nfetch(url, {\n method: \"POST\",\n headers: {\n \"X-Auth-Token\": TOKEN,\n \"Content-Type\": \"application/json\"\n },\n body: JSON.stringify(payload)\n})\n .then(response => response.json())\n .then(data => {\n data.results.forEach((variableData, i) => {\n console.log(`\\nVariable ${i + 1}:`);\n console.log(`Columns: ${data.columns[i]}`);\n console.log(`Data points: ${variableData.length}`);\n console.log(\"Sample data:\", variableData.slice(0, 3));\n });\n })\n .catch(error => console.error(\"Error:\", error));\n// Get just the last 5 values\nconst recentPayload = {\n variables: VARIABLE_IDS,\n columns: [\"value.value\", \"timestamp\"],\n limit: 5,\n precision: 2\n};\nfetch(url, {\n method: \"POST\",\n headers: {\n \"X-Auth-Token\": TOKEN,\n \"Content-Type\": \"application/json\"\n },\n body: JSON.stringify(recentPayload)\n})\n .then(response => response.json())\n .then(data => console.log(\"Most recent values:\", data.results[0]))\n .catch(error => console.error(\"Error:\", error));\n\nThe response contains:
\nresults: Array of datasets (one per variable if join_dataframes: false)
columns: Array describing column names for each dataset
Each data point in results is an array where values correspond to the columns order:
// For columns: [\"value.value\", \"timestamp\"]\n[62982.21, 1636322400000] // [value, timestamp]\n\nReal-time monitoring: Get the latest values with limit parameter
Historical analysis: Retrieve full time range data for trend analysis
\nData export: Pull raw data for external processing or visualization
\nMulti-sensor comparison: Compare readings across multiple variables
\nCustom reporting: Select specific columns needed for your application
\nResults are ordered by timestamp (most recent first by default)
\nAll timestamps are in milliseconds (POSIX format)
\nTime ranges are inclusive on both start and end
\nWithout precision specified, results use full decimal precision
\nToken expires after 6 hours - generate fresh tokens as needed
\nTimezone defaults to UTC if not specified
\nUse limit to control data volume and API response time
Device Data and all your time series in one place.
Base URL is: api.surfact.com/api/v1.6/
| ID | ","Label | ","Name | ","Description | ","Tags | ","Active | ","Last Activity | ","Created At | ","
|---|---|---|---|---|---|---|---|
| {{id}} | ","{{label}} | ","{{name}} | ","{{description}} | ","{{tags}} | ","{{isActive}} | ","{{lastActivity}} | ","{{createdAt}} | ","
There are two alternate ways to retrieve the most recent value of a specific variable.
\nTo retrieve a single Variable please make a GET request to the following URL:
\nTo retrieve a single Variable of a Device please make a GET request to the following URL:
\nimport requests\nTOKEN = \"your_token_here\"\nDEVICE_LABEL = \"temperature-sensor\"\nVARIABLE_LABEL = \"室温\"\nurl = f\"https://api.surfact.com/api/v1.6/devices/{DEVICE_LABEL}/{VARIABLE_LABEL}/lv\"\nheaders = {\"X-Auth-Token\": TOKEN}\nresponse = requests.get(url, headers=headers)\nif response.status_code == 200:\n last_value = float(response.text)\n print(f\"Last value: {last_value}\")\nelse:\n print(f\"Error: {response.json()}\")\n\nconst TOKEN = \"your_token_here\";\nconst DEVICE_LABEL = \"temperature-sensor\";\nconst VARIABLE_LABEL = \"室温\";\nconst url = `https://api.surfact.com/api/v1.6/devices/${DEVICE_LABEL}/${VARIABLE_LABEL}/lv`;\nfetch(url, {\n headers: {\n \"X-Auth-Token\": TOKEN\n }\n})\n .then(response => response.text())\n .then(value => console.log(\"Last value:\", parseFloat(value)))\n .catch(error => console.error(\"Error:\", error));\n\nDashboard displays: Show current sensor readings
\nStatus monitoring: Check latest device status
\nAlerting systems: Compare current value against thresholds
\nQuick checks: Get instant value without retrieving full history
\nResponse is a simple numeric value (not JSON)
\nReturns only the value itself, without timestamp or metadata
\nFor full value details including timestamp and context, use the Data Raw Series endpoint with limit: 1
Device and variable labels are case-sensitive
\nGet devices for your organization, see device metadata, setup events (alerts) for devices and more.
\nBase URL is: api.surfact.com/api/v2.0/
Standard Payload:
\n{\n \"device\": \"device-label\",\n \"variable\": \"variable-label\",\n \"value\": 23.5,\n \"timestamp\": 1634311791000,\n \"context\": {\n \"status\": \"active\"\n }\n}\n\nCustom Payload:** Available on request to match your existing infrastructure.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"X-Auth-Token"},{"key":"value","value":"Surfact supports webhooks to push data to your systems in real-time, eliminating the need for constant polling.
\nSend data to your database or data warehouse
\nTrigger workflows in systems like Zapier or Make
\nUpdate dashboards in real-time
\nAlert systems when thresholds are exceeded
\nIntegrate with custom applications
\nWhen a variable is updated, Surfact automatically sends an HTTP POST request to your configured endpoint with the data payload.
\nBenefits:
\nReal-time notifications
\nReduced API calls
\nLower bandwidth usage
\nNo polling overhead
\nTo configure a webhook for your account:
\nPrepare your endpoint:
\nHTTPS endpoint URL
\nAuthentication credentials (if required)
\nContact support:
\nEmail: support@surfact.com
\nProvide: endpoint URL and auth credentials
\nSpecify: custom payload format (if needed)
\nWe'll configure and test your webhook
\nAccess the Surfact MQTT broker through plain MQTT or secure MQTT with TLS using the following endpoints.
\nDownload the Surfact PEM certificate for TLS connections: surfact-roots.pem
\n⚠️ Security Note: Always use MQTT with TLS in production to ensure your data travels encrypted, protecting your API token and sensor data from third parties.
\nSurfact supports fixed IP addresses for data ingestion, but we strongly recommend using DNS endpoints instead. Fixed IPs may change in the future.
\n⚠️ Best Practice: Always implement firmware routines using DNS endpoints rather than hardcoding IP addresses.
\n","_postman_id":"22657f01-8b98-4448-9291-14db4d68f021","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"X-Auth-Token"},{"key":"value","value":"To connect to the Surfact MQTT broker, you need a token. A token is a unique key that authorizes your device to interact with the Surfact API.
\nWhen establishing a connection with the MQTT broker, use the following credentials:
\nSee the Authentication documentation for details on:
\nRetrieving your token from your account
\nGenerating tokens programmatically via API
\nToken validity (6 hours)
\nPython (paho-mqtt):
\nimport paho.mqtt.client as mqtt\n# Your Surfact token\ntoken = \"BBFF-nQ5jCC445FfClcKLCQ55YhnTb2oh6knHsZO\"\nclient = mqtt.Client(client_id=\"my-device-12345678901234567890\")\nclient.username_pw_set(username=token, password=\"\")\nclient.connect(\"api.surfact.com\", 8883)\n\nJavaScript (mqtt.js):
\nconst mqtt = require('mqtt');\n// Your Surfact token\nconst token = 'BBFF-nQ5jCC445FfClcKLCQ55YhnTb2oh6knHsZO';\nconst client = mqtt.connect('mqtts://api.surfact.com:8883', {\n username: token,\n password: '',\n clientId: 'my-device-12345678901234567890'\n});\n\nNote: The password field can be left empty or set to any value—it's not validated.
\n","_postman_id":"c1ae270f-247a-4e18-bafd-863aee3d7020","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"X-Auth-Token"},{"key":"value","value":"Use this topic to subscribe to a variable's last value. When you connect, you'll immediately receive the most recent value, then get updates whenever the value changes.
\n/v1.6/devices/<device_label>/<variable_label>/lv\n\n{DEVICE_LABEL} - Your device's unique label
{VARIABLE_LABEL} - The variable you want to monitor
/lv - Last value suffix
⚠️ Note: If the device or variable doesn't exist, the subscription will fail.
\nmosquitto_sub \\\n -h \"api.surfact.com\" \\\n -t \"/v1.6/devices/weather-station/temperature/lv\" \\\n -u \"{{vault:ubidots-api-key}}\" \\\n -p 8883 \\\n -q 1\n\nOutput:
\n24.0\n\nimport paho.mqtt.client as mqtt\ntoken = \"your-surfact-token\"\ndevice_label = \"weather-station\"\nvariable_label = \"temperature\"\ndef on_connect(client, userdata, flags, rc):\n print(f\"Connected with result code {rc}\")\n # Subscribe to last value\n topic = f\"/v2.0/devices/{device_label}/{variable_label}/lv\"\n client.subscribe(topic)\n print(f\"Subscribed to {topic}\")\ndef on_message(client, userdata, msg):\n value = msg.payload.decode()\n print(f\"Last value: {value}\")\nclient = mqtt.Client(client_id=\"my-device-12345678901234567890\")\nclient.username_pw_set(username=token, password=\"\")\nclient.on_connect = on_connect\nclient.on_message = on_message\nclient.connect(\"api.surfact.com\", 8883)\nclient.loop_forever()\n\nconst mqtt = require('mqtt');\nconst token = 'your-surfact-token';\nconst deviceLabel = 'weather-station';\nconst variableLabel = 'temperature';\nconst client = mqtt.connect('mqtts://api.surfact.com:8883', {\n username: token,\n password: '',\n clientId: 'my-device-12345678901234567890'\n});\nclient.on('connect', () => {\n console.log('Connected');\n const topic = `/v2.0/devices/${deviceLabel}/${variableLabel}/lv`;\n client.subscribe(topic, (err) => {\n if (!err) {\n console.log(`Subscribed to ${topic}`);\n }\n });\n});\nclient.on('message', (topic, message) => {\n console.log(`Last value: ${message.toString()}`);\n});\n\nWhen you subscribe to a /lv topic:
Immediate delivery: You receive the variable's current last value immediately upon subscription
\nUpdates: You receive new values whenever the variable is updated
\nRetained messages: The last value is always available (see MQTT Overview for details)
\nThe /lv topic is ideal for:
Device initialization: Get the current state immediately when connecting
\nSyncing device state: Ensure your device matches the cloud state on startup
\nDashboard displays: Show the most recent value without waiting for an update
\nControl systems: Initialize actuators to their last known state
\nUse the regular topic if you only want to receive updates when values change. Use /lv if you need the current value immediately.
Use this topic to subscribe to a variable's last \"dot\" (data point). Unlike the /lv endpoint which returns only the value, this returns the complete data point including value, timestamp, and context.
/v1.6/devices/{DEVICE_LABEL}/{VARIABLE_LABEL}\n\n{DEVICE_LABEL} - Your device's unique label
{VARIABLE_LABEL} - The variable you want to monitor
⚠️ Note: If the device or variable doesn't exist, the subscription will fail.
\nThe response is a JSON object containing:
\n{\n \"value\": 34.0,\n \"timestamp\": 1634311791000,\n \"context\": {\n \"status\": \"cold\"\n },\n \"created_at\": 1634311791000\n}\n\nmosquitto_sub \\\n -h \"api.surfact.com\" \\\n -t \"/v1.6/devices/weather-station/temperature\" \\\n -u \"{{vault:ubidots-api-key}}\" \\\n -p 8883 \\\n -q 1\n\nOutput:
\n{\n \"value\": 34.0,\n \"timestamp\": 1634311791000,\n \"context\": {\n \"status\": \"cold\"\n },\n \"created_at\": 1634311791000\n}\n\nimport paho.mqtt.client as mqtt\nimport json\ntoken = \"your-surfact-token\"\ndevice_label = \"weather-station\"\nvariable_label = \"temperature\"\ndef on_connect(client, userdata, flags, rc):\n print(f\"Connected with result code {rc}\")\n topic = f\"/v2.0/devices/{device_label}/{variable_label}\"\n client.subscribe(topic)\n print(f\"Subscribed to {topic}\")\ndef on_message(client, userdata, msg):\n data = json.loads(msg.payload.decode())\n print(f\"Value: {data['value']}\")\n print(f\"Timestamp: {data['timestamp']}\")\n if 'context' in data:\n print(f\"Context: {data['context']}\")\nclient = mqtt.Client(client_id=\"my-device-12345678901234567890\")\nclient.username_pw_set(username=token, password=\"\")\nclient.on_connect = on_connect\nclient.on_message = on_message\nclient.connect(\"api.surfact.com\", 8883)\nclient.loop_forever()\n\nconst mqtt = require('mqtt');\nconst token = 'your-surfact-token';\nconst deviceLabel = 'weather-station';\nconst variableLabel = 'temperature';\nconst client = mqtt.connect('mqtts://api.surfact.com:8883', {\n username: token,\n password: '',\n clientId: 'my-device-12345678901234567890'\n});\nclient.on('connect', () => {\n console.log('Connected');\n const topic = `/v2.0/devices/${deviceLabel}/${variableLabel}`;\n client.subscribe(topic, (err) => {\n if (!err) {\n console.log(`Subscribed to ${topic}`);\n }\n });\n});\nclient.on('message', (topic, message) => {\n const data = JSON.parse(message.toString());\n console.log(`Value: ${data.value}`);\n console.log(`Timestamp: ${data.timestamp}`);\n if (data.context) {\n console.log(`Context: ${JSON.stringify(data.context)}`);\n }\n});\n\nWhen you subscribe to this topic:
\nImmediate delivery: You receive the variable's last data point immediately upon subscription
\nUpdates: You receive complete data points whenever the variable is updated
\nFull metadata: Includes timestamp and context (unlike /lv which only returns the value)
This topic is ideal when you need:
\nTimestamp information: Know exactly when the data was recorded
\nContext metadata: Access additional information sent with the data point
\nFull data point details: Complete information for logging or analysis
\nAudit trails: Track when data was created and recorded
\nUse /lv if you only need the value. Use the standard topic if you need timestamps, context, or complete data point information.
Use MQTT wildcards to subscribe to multiple topics simultaneously. Wildcards let you monitor multiple devices or variables with a single subscription.
\n+)The single-level wildcard (+) matches exactly one level in the topic hierarchy.
/v1.6/devices/+/{VARIABLE_LABEL}\n\nThis subscribes to the specified variable across all devices that have it.
\nYou have 3 devices with the following variables:
\nTopic:
\n/v1.6/devices/+/pressure/lv\n/v1.6/devices/+/pressure\n\nEquivalent to:
\n/v1.6/devices/device-a/pressure/lv\n/v1.6/devices/device-c/pressure/lv\n\nThis subscribes to the pressure variable for any device that has it. You'll receive updates when device-a or device-c send new pressure values.
Command Line:
\n# Last value only\nmosquitto_sub \\\n -h \"api.surfact.com\" \\\n -t \"/v1.6/devices/+/pressure/lv\" \\\n -u \"{{vault:ubidots-api-key}}\" \\\n -p 8883 \\\n -q 1 \\\n -v\n# Full data point (with timestamp and context)\nmosquitto_sub \\\n -h \"api.surfact.com\" \\\n -t \"/v1.6/devices/+/pressure\" \\\n -u \"{{vault:ubidots-api-key}}\" \\\n -p 8883 \\\n -q 1 \\\n -v\n\nPython:
\nimport paho.mqtt.client as mqtt\ntoken = \"your-surfact-token\"\ndef on_connect(client, userdata, flags, rc):\n print(f\"Connected with result code {rc}\")\n # Subscribe to pressure variable across all devices\n client.subscribe(\"/v1.6/devices/+/pressure/lv\")\ndef on_message(client, userdata, msg):\n # Topic will show which device sent the update\n print(f\"Topic: {msg.topic}\")\n print(f\"Value: {msg.payload.decode()}\")\nclient = mqtt.Client(client_id=\"my-device-12345678901234567890\")\nclient.username_pw_set(username=token, password=\"\")\nclient.on_connect = on_connect\nclient.on_message = on_message\nclient.connect(\"api.surfact.com\", 8883)\nclient.loop_forever()\n\nJavaScript:
\nconst mqtt = require('mqtt');\nconst token = 'your-surfact-token';\nconst client = mqtt.connect('mqtts://api.surfact.com:8883', {\n username: token,\n password: '',\n clientId: 'my-device-12345678901234567890'\n});\nclient.on('connect', () => {\n console.log('Connected');\n // Subscribe to pressure variable across all devices\n client.subscribe('/v1.6/devices/+/pressure/lv');\n});\nclient.on('message', (topic, message) => {\n // Topic will show which device sent the update\n console.log(`Topic: ${topic}`);\n console.log(`Value: ${message.toString()}`);\n});\n\nTopic:
\n/v1.6/devices/device-a/+/lv\n/v1.6/devices/device-a/+\n\nEquivalent to:
\n/v1.6/devices/device-a/temperature/lv\n/v1.6/devices/device-a/pressure/lv\n/v1.6/devices/device-a/humidity/lv\n\nThis subscribes to all variables from device-a. You'll receive updates when any of its variables are updated.
Command Line:
\n# Last value only\nmosquitto_sub \\\n -h \"api.surfact.com\" \\\n -t \"/v1.6/devices/device-a/+/lv\" \\\n -u \"{{vault:ubidots-api-key}}\" \\\n -p 8883 \\\n -q 1 \\\n -v\n# Full data point\nmosquitto_sub \\\n -h \"api.surfact.com\" \\\n -t \"/v1.6/devices/device-a/+\" \\\n -u \"{{vault:ubidots-api-key}}\" \\\n -p 8883 \\\n -q 1 \\\n -v\n\nPython:
\nimport paho.mqtt.client as mqtt\ntoken = \"your-surfact-token\"\ndevice_label = \"device-a\"\ndef on_connect(client, userdata, flags, rc):\n print(f\"Connected with result code {rc}\")\n # Subscribe to all variables from device-a\n topic = f\"/v1.6/devices/{device_label}/+/lv\"\n client.subscribe(topic)\ndef on_message(client, userdata, msg):\n # Extract variable name from topic\n parts = msg.topic.split('/')\n variable = parts[3] # Variable is at index 3\n print(f\"Variable: {variable}\")\n print(f\"Value: {msg.payload.decode()}\")\nclient = mqtt.Client(client_id=\"my-device-12345678901234567890\")\nclient.username_pw_set(username=token, password=\"\")\nclient.on_connect = on_connect\nclient.on_message = on_message\nclient.connect(\"api.surfact.com\", 8883)\nclient.loop_forever()\n\nJavaScript:
\nconst mqtt = require('mqtt');\nconst token = 'your-surfact-token';\nconst deviceLabel = 'device-a';\nconst client = mqtt.connect('mqtts://api.surfact.com:8883', {\n username: token,\n password: '',\n clientId: 'my-device-12345678901234567890'\n});\nclient.on('connect', () => {\n console.log('Connected');\n // Subscribe to all variables from device-a\n const topic = `/v1.6/devices/${deviceLabel}/+/lv`;\n client.subscribe(topic);\n});\nclient.on('message', (topic, message) => {\n // Extract variable name from topic\n const parts = topic.split('/');\n const variable = parts[3]; // Variable is at index 3\n console.log(`Variable: ${variable}`);\n console.log(`Value: ${message.toString()}`);\n});\n\n#)The multi-level wildcard (#) matches any number of levels in the topic hierarchy. It must be the last character in the topic.
# Subscribe to ALL variables from ALL devices\n/v1.6/devices/#\n# Subscribe to everything for a specific device\n/v1.6/devices/device-a/#\n\n⚠️ Warning: Multi-level wildcards can generate very high message volumes. Use with caution in production environments.
\n✅ Do:
\nUse wildcards to reduce the number of subscriptions
\nParse the topic in your message handler to identify the source
\nUse single-level wildcards when you know the topic structure
\n⚠️ Don't:
\nUse # in production unless absolutely necessary
Subscribe to more data than you need
\nForget to handle the increased message volume
\nUse MQTT's multi-level wildcard to subscribe to multiple topics simultaneously. The multi-level wildcard matches any number of topic levels.
\n#)The multi-level wildcard (#) matches all remaining levels in the topic hierarchy. It must always be the last character in the topic.
/v1.6/devices/{DEVICE_LABEL}/#\n\nThis subscribes to all variables within the specified device.
\nYou have 3 devices with the following variables:
\nTopic:
\n/v1.6/devices/device-a/#\n\nEquivalent to:
\n/v1.6/devices/device-a/temperature\n/v1.6/devices/device-a/pressure\n/v1.6/devices/device-a/humidity\n\nThis subscribes to all variables from device-a. You'll receive full data points (with timestamp and context) whenever any variable is updated.
Command Line:
\nmosquitto_sub \\\n -h \"api.surfact.com\" \\\n -t \"/v1.6/devices/device-a/#\" \\\n -u \"{{vault:ubidots-api-key}}\" \\\n -p 8883 \\\n -q 1 \\\n -v\n\nPython:
\nimport paho.mqtt.client as mqtt\nimport json\ntoken = \"your-surfact-token\"\ndevice_label = \"device-a\"\ndef on_connect(client, userdata, flags, rc):\n print(f\"Connected with result code {rc}\")\n # Subscribe to all variables from device-a\n topic = f\"/v1.6/devices/{device_label}/#\"\n client.subscribe(topic)\n print(f\"Subscribed to {topic}\")\ndef on_message(client, userdata, msg):\n # Extract variable name from topic\n parts = msg.topic.split('/')\n variable = parts[3] if len(parts) > 3 else \"unknown\"\n # Parse the message (could be JSON or plain value)\n try:\n data = json.loads(msg.payload.decode())\n print(f\"Variable: {variable}\")\n print(f\"Value: {data.get('value', 'N/A')}\")\n print(f\"Timestamp: {data.get('timestamp', 'N/A')}\")\n except json.JSONDecodeError:\n print(f\"Variable: {variable}\")\n print(f\"Value: {msg.payload.decode()}\")\nclient = mqtt.Client(client_id=\"my-device-12345678901234567890\")\nclient.username_pw_set(username=token, password=\"\")\nclient.on_connect = on_connect\nclient.on_message = on_message\nclient.connect(\"api.surfact.com\", 8883)\nclient.loop_forever()\n\nJavaScript:
\nconst mqtt = require('mqtt');\nconst token = 'your-surfact-token';\nconst deviceLabel = 'device-a';\nconst client = mqtt.connect('mqtts://api.surfact.com:8883', {\n username: token,\n password: '',\n clientId: 'my-device-12345678901234567890'\n});\nclient.on('connect', () => {\n console.log('Connected');\n // Subscribe to all variables from device-a\n const topic = `/v1.6/devices/${deviceLabel}/#`;\n client.subscribe(topic, (err) => {\n if (!err) {\n console.log(`Subscribed to ${topic}`);\n }\n });\n});\nclient.on('message', (topic, message) => {\n // Extract variable name from topic\n const parts = topic.split('/');\n const variable = parts[3] || 'unknown';\n // Parse the message (could be JSON or plain value)\n try {\n const data = JSON.parse(message.toString());\n console.log(`Variable: ${variable}`);\n console.log(`Value: ${data.value}`);\n console.log(`Timestamp: ${data.timestamp}`);\n } catch (e) {\n console.log(`Variable: ${variable}`);\n console.log(`Value: ${message.toString()}`);\n }\n});\n\nTopic:
\n/v1.6/devices/#\n\nEquivalent to:
\n/v1.6/devices/device-a/temperature\n/v1.6/devices/device-a/pressure\n/v1.6/devices/device-a/humidity\n/v1.6/devices/device-b/temperature\n/v1.6/devices/device-c/pressure\n/v1.6/devices/device-c/humidity\n\nThis subscribes to all variables from all devices. You'll receive updates whenever any variable on any device is updated.
\n⚠️ Warning: This can generate extremely high message volumes in production. Use only for testing or small-scale deployments.
\nCommand Line:
\nmosquitto_sub \\\n -h \"api.surfact.com\" \\\n -t \"/v1.6/devices/#\" \\\n -u \"{{vault:ubidots-api-key}}\" \\\n -p 8883 \\\n -q 1 \\\n -v\n\nPython:
\nimport paho.mqtt.client as mqtt\nimport json\ntoken = \"your-surfact-token\"\ndef on_connect(client, userdata, flags, rc):\n print(f\"Connected with result code {rc}\")\n # Subscribe to EVERYTHING\n client.subscribe(\"/v1.6/devices/#\")\n print(\"⚠️ Subscribed to ALL devices and variables\")\ndef on_message(client, userdata, msg):\n # Extract device and variable names from topic\n parts = msg.topic.split('/')\n device = parts[2] if len(parts) > 2 else \"unknown\"\n variable = parts[3] if len(parts) > 3 else \"unknown\"\n # Parse the message\n try:\n data = json.loads(msg.payload.decode())\n print(f\"Device: {device} | Variable: {variable}\")\n print(f\"Value: {data.get('value', 'N/A')}\")\n except json.JSONDecodeError:\n print(f\"Device: {device} | Variable: {variable}\")\n print(f\"Value: {msg.payload.decode()}\")\nclient = mqtt.Client(client_id=\"my-device-12345678901234567890\")\nclient.username_pw_set(username=token, password=\"\")\nclient.on_connect = on_connect\nclient.on_message = on_message\nclient.connect(\"api.surfact.com\", 8883)\nclient.loop_forever()\n\nJavaScript:
\nconst mqtt = require('mqtt');\nconst token = 'your-surfact-token';\nconst client = mqtt.connect('mqtts://api.surfact.com:8883', {\n username: token,\n password: '',\n clientId: 'my-device-12345678901234567890'\n});\nclient.on('connect', () => {\n console.log('Connected');\n // Subscribe to EVERYTHING\n client.subscribe('/v1.6/devices/#', (err) => {\n if (!err) {\n console.log('⚠️ Subscribed to ALL devices and variables');\n }\n });\n});\nclient.on('message', (topic, message) => {\n // Extract device and variable names from topic\n const parts = topic.split('/');\n const device = parts[2] || 'unknown';\n const variable = parts[3] || 'unknown';\n // Parse the message\n try {\n const data = JSON.parse(message.toString());\n console.log(`Device: ${device} | Variable: ${variable}`);\n console.log(`Value: ${data.value}`);\n } catch (e) {\n console.log(`Device: ${device} | Variable: ${variable}`);\n console.log(`Value: ${message.toString()}`);\n }\n});\n\nThe topic itself contains valuable information about which device and variable sent the update:
\n/v1.6/devices/device-a/temperature\n │ │ │\n │ │ └─ Variable name\n │ └─ Device name\n └─ API version\n\nAlways parse the topic in your message handler to identify the source of the data.
\nMessages received via multi-level wildcard subscriptions can be:
\nFull JSON objects (when subscribing to base variable topics)
\nPlain values (when subscribing to /lv topics)
Your code should handle both formats.
\n✅ Do:
\nUse /v1.6/devices/{device}/# for monitoring specific devices
Parse the topic to identify the source device and variable
\nTest with small datasets before deploying to production
\nConsider message volume and bandwidth
\n⚠️ Don't:
\nUse /v1.6/devices/# in production with many devices
Forget to handle different message formats (JSON vs. plain values)
\nSubscribe to more data than you can process
\nIgnore the topic information—it's essential for routing
\nChoose single-level wildcards when you know the exact topic structure. Use multi-level wildcards when you need flexibility but be aware of the increased message volume.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"X-Auth-Token"},{"key":"value","value":"Similar to HTTP GET requests, subscribing lets you receive values from Surfact. The key difference: you don't have to continuously poll the server.
\nWhen a variable's value changes, Surfact automatically notifies you. This saves:
\nData requests
\nProcessing time on your device
\nBattery life
\nCosts
\nThis makes MQTT ideal for controlling actuators and real-time device interactions.
\nSubscribe to variables using this topic pattern:
\n/v2.0/devices/{DEVICE_LABEL}/{VARIABLE_LABEL}\n/v1.6/devices/{DEVICE_LABEL}/{VARIABLE_LABEL}\n\n{DEVICE_LABEL} - Your device's unique label
{VARIABLE_LABEL} - The variable you want to monitor
import paho.mqtt.client as mqtt\ntoken = \"your-surfact-token\"\ndevice_label = \"smart-door\"\nvariable_label = \"lock-status\"\ndef on_connect(client, userdata, flags, rc):\n print(f\"Connected with result code {rc}\")\n # Subscribe to the variable\n topic = f\"/v2.0/devices/{device_label}/{variable_label}\"\n client.subscribe(topic)\ndef on_message(client, userdata, msg):\n print(f\"Received: {msg.payload.decode()} on topic {msg.topic}\")\nclient = mqtt.Client(client_id=\"my-device-12345678901234567890\")\nclient.username_pw_set(username=token, password=\"\")\nclient.on_connect = on_connect\nclient.on_message = on_message\nclient.connect(\"api.surfact.com\", 8883)\nclient.loop_forever()\n\nconst mqtt = require('mqtt');\nconst token = 'your-surfact-token';\nconst deviceLabel = 'smart-door';\nconst variableLabel = 'lock-status';\nconst client = mqtt.connect('mqtts://api.surfact.com:8883', {\n username: token,\n password: '',\n clientId: 'my-device-12345678901234567890'\n});\nclient.on('connect', () => {\n console.log('Connected');\n const topic = `/v2.0/devices/${deviceLabel}/${variableLabel}`;\n client.subscribe(topic, (err) => {\n if (!err) {\n console.log(`Subscribed to ${topic}`);\n }\n });\n});\nclient.on('message', (topic, message) => {\n console.log(`Received: ${message.toString()} on topic ${topic}`);\n});\n\nSubscribe to multiple variables by calling subscribe for each topic:
\ntopics = [\n f\"/v2.0/devices/{device_label}/temperature\",\n f\"/v2.0/devices/{device_label}/humidity\",\n f\"/v2.0/devices/{device_label}/pressure\"\n]\nfor topic in topics:\n client.subscribe(topic)\n\nMQTT supports wildcards for subscribing to multiple variables:
\n+ - Single-level wildcard (matches one level)
# - Multi-level wildcard (matches all remaining levels)
Examples:
\n# Subscribe to ALL variables for a specific device\nclient.subscribe(f\"/v2.0/devices/{device_label}/+\")\n# Subscribe to a specific variable across ALL devices\nclient.subscribe(f\"/v2.0/devices/+/{variable_label}\")\n# Subscribe to everything under /v2.0/devices/\nclient.subscribe(\"/v2.0/devices/#\")\n\n⚠️ Warning: Using wildcards (especially #) can result in high message volumes. Use specific topics when possible.
MQTT is an Internet of Things connectivity protocol designed as an extremely lightweight publish/subscribe messaging transport. It's ideal for connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium.
\nMQTT is especially useful for pushing data from the cloud to your devices.
\nExample scenario: A cloud-controlled door lock.
\nWith HTTP: The device must continuously make GET requests to check if the \"Door Control Variable\" has changed. This consumes bandwidth, drains battery, and isn't truly real-time.
\nWith MQTT: The device \"listens\" to the cloud and only gets notified when the variable changes. The connection stays open, but data only travels when necessary—saving battery, bandwidth, and enabling real-time control.
\nQoS guarantees message delivery reliability. There are three levels:
\nSurfact Support: QoS up to 1 (at least once).
\nLWT messages are sent by the broker when a client connection is interrupted (client goes offline).
\nSurfact Support: LWT is not supported.
\nPersistent sessions allow the broker to save client information if the connection is lost, enabling immediate reconnection.
\nSurfact Support: Persistent sessions are not supported. Setting the cleanSession flag to false has no effect. After disconnection, the client must re-establish connection settings.
The Client ID is a unique identifier for each MQTT client connecting to the broker. It allows the broker to track the client's state.
\nTo avoid collisions with other Surfact users, your Client ID must be:
\nAlphanumeric
\nAt least 20 characters long
\nRandom
\nA retained message is a standard MQTT message with the retained flag set to true. The broker stores the last retained message and its QoS for that topic. New subscribers immediately receive the retained message upon subscription.
By design, every message published to the Surfact broker is marked as retained, regardless of whether the flag is set. This ensures the last value published to a variable is always available via MQTT subscription.
\nSimilarly, when data is posted via HTTP, TCP, or UDP, Surfact publishes the last value to the broker to maintain consistency across protocols.
\n","_postman_id":"2d68f692-0eaa-479b-a113-0c0e343c1f8f","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"X-Auth-Token"},{"key":"value","value":"