Customer API Documentation

API that allows customers to read and write device data using a restricted set of keys.

Authentication uses your username and password via HTTP Basic Auth. No separate API keys are needed.

Base URL: https://api.dc3control.net/api

Authentication

All endpoints use HTTP Basic Auth. Pass your the platform username and password with every request.

Most HTTP clients (Postman, curl, etc.) have a built-in Basic Auth option so you don't need to encode manually.

curl example:

curl -u "your_username:your_password" "https://api.dc3control.net/api/timeseries?..."

Errors:

Endpoints

GET /attributes

Fetch the latest attribute values for a device.

Query Parameters:

Example Request:

curl -u "username:password" \
  "https://api.dc3control.net/api/attributes?entityType=DEVICE&entityId=abc-123&keys=status,firmware_version"

Example Response:

[
  { "key": "status", "value": "online", "lastUpdateTs": 1712000000000 },
  { "key": "firmware_version", "value": "2.1.0", "lastUpdateTs": 1712000000000 }
]

GET /timeseries

Fetch the latest timeseries values for a device.

Query Parameters:

Example Request:

curl -u "username:password" \
  "https://api.dc3control.net/api/timeseries?entityType=DEVICE&entityId=abc-123&keys=temperature,pressure"

Example Response:

{
  "temperature": [{ "ts": 1712000000000, "value": "72.5" }],
  "pressure": [{ "ts": 1712000000000, "value": "14.7" }]
}

POST /attributes

Write attribute values to a device.

Request Body:

Example Request:

curl -u "username:password" -X POST \
  "https://api.dc3control.net/api/attributes" \
  -H "Content-Type: application/json" \
  -d '{"entityType":"DEVICE","entityId":"abc-123","data":{"status":"online"}}'

Example Response:

null

the platform returns an empty response on success.

POST /timeseries

Write telemetry values to a device.

Request Body:

Example Request:

curl -u "username:password" -X POST \
  "https://api.dc3control.net/api/timeseries" \
  -H "Content-Type: application/json" \
  -d '{"entityId":"abc-123","data":{"temperature":72.5,"pressure":14.7}}'

Example Response:

null

the platform returns an empty response on success.

Error Responses

All endpoints return errors in this format:

{ "error": "description of the error" }

3. Retrieve Latest Device Data

Returns the latest attribute and time-series values for all devices under the authenticated user's account. Uses the same Basic Auth as all other Customer API endpoints.

3.1 Request Method

POST

3.2 Endpoint

https://api.dc3control.net/api/devices/latest

3.3 Request Headers

3.4 Request Body

All fields are optional. If keys is omitted, all permitted keys are returned. See Section 5.1 for the full list of permitted keys.

Example — request specific keys:

{
  "keys": ["Area", "WellName", "gallons", "1118", "9995", "active", "lastActivityTime"],
  "pageSize": 1000,
  "page": 0
}

Example — return all allowed keys (empty body):

{}

3.5 Example Request

curl -u "your_username:your_password" \
  --request POST \
  --url "https://api.dc3control.net/api/devices/latest" \
  --header "Content-Type: application/json" \
  --data '{"keys": ["Area", "WellName", "gallons", "1118", "9995", "active", "lastActivityTime"]}'

3.6 Example Response

The response is an array — one element per device. The entityId.id is a unique device ID that can be passed to Section 4.

[
  {
    "entityId": {
      "entityType": "DEVICE",
      "id": "12345678-123-123-123-12345678"
    },
    "readAttrs": true,
    "readTs": true,
    "latest": {
      "TIME_SERIES": {
        "1118":    { "ts": 1728892800000, "value": "29.30712" },
        "9995":    { "ts": 1728892800000, "value": "3613" },
        "gallons": { "ts": 1728892800000, "value": "271.377864448" }
      },
      "ENTITY_FIELD": {
        "name": { "ts": 1729014241371, "value": "864259063692484" },
        "type": { "ts": 1729014241371, "value": "TLM" }
      },
      "ATTRIBUTE": {
        "Area":             { "ts": 1729008009632, "value": "area ABC" },
        "WellName":         { "ts": 1715323167435, "value": "Test Well" },
        "ChemicalType":     { "ts": 1715323571831, "value": "Corrosion Inhibitor" },
        "ProductName":      { "ts": 1715323284628, "value": "ABCD" },
        "InjectionPoint":   { "ts": 1714702597504, "value": "ZZ Refining - Sample" },
        "active":           { "ts": 1728719873056, "value": "true" },
        "lastActivityTime": { "ts": 1728892673058, "value": "1728892670622" }
      }
    },
    "timeseries": {},
    "aggLatest": {}
  },
  {
    "entityId": {
      "entityType": "DEVICE",
      "id": "765432-765-765-7654-7654321"
    },
    "readAttrs": true,
    "readTs": true,
    "latest": {
      "TIME_SERIES": {
        "1118":    { "ts": 1728979200000, "value": "7.57488" },
        "9995":    { "ts": 1728979200000, "value": "3619" },
        "gallons": { "ts": 1728979200000, "value": "66.43414835200001" }
      },
      "ENTITY_FIELD": {
        "name": { "ts": 1729014241371, "value": "864259063692724" },
        "type": { "ts": 1729014241371, "value": "TEK" }
      },
      "ATTRIBUTE": {
        "Area":             { "ts": 1729008055908, "value": "Area ZXC" },
        "WellName":         { "ts": 1727988519648, "value": "Test well2" },
        "ChemicalType":     { "ts": 1727988550125, "value": "5403" },
        "ProductName":      { "ts": 1727983340130, "value": "" },
        "InjectionPoint":   { "ts": 1727988545988, "value": "ABC" },
        "active":           { "ts": 1727983343034, "value": "true" },
        "lastActivityTime": { "ts": 1728979223050, "value": "1728979222796" }
      }
    },
    "timeseries": {},
    "aggLatest": {}
  }
]

4. Retrieve Historical Device Data

Returns historical time-series data for a specific device. Use the entityId.id from Section 3 as the deviceId.

4.1 Request Method

GET

4.2 Endpoint

https://api.dc3control.net/api/devices/{deviceId}/history

4.3 Request Headers

4.4 Query Parameters

Note: Only time-series keys listed in Section 5.1 are accepted. Attribute keys are not valid here.

4.5 Example Request

curl -u "your_username:your_password" \
  --request GET \
  "https://api.dc3control.net/api/devices/12345678-123-123-123-12345678/history?keys=gallons,1118,9995&startTs=1727812338000&endTs=1727820000000"

4.6 Example Response

{
  "1118": [
    { "ts": 1727818200000, "value": "12.283540000000002" },
    { "ts": 1727816400000, "value": "12.283540000000002" },
    { "ts": 1727814600000, "value": "12.244169999999997" },
    { "ts": 1727812800000, "value": "12.283540000000002" }
  ],
  "gallons": [
    { "ts": 1727818200000, "value": "110.83869561600002" },
    { "ts": 1727816400000, "value": "110.83869561600002" },
    { "ts": 1727814600000, "value": "110.46742076799998" },
    { "ts": 1727812800000, "value": "110.83869561600002" }
  ]
}

5. Available Data Keys

5.1 TIME_SERIES Keys — Full Reference

Table 1, v2.0 — All time-series keys available on the DC3 Control platform.

5.2 ATTRIBUTE Keys — Full Reference