Agent API

The agent features a robust RESTful API that can be used to extend xConnect beyond built-in functionality.

There are often use-cases we haven't thought about or developed for and this API allows you to take enhance xConnect to fit your specific need.

OpenAPI Documentation

Full OpenAPI3 (Swagger) documentation can be found at: http://localhost:8886/docs

Submit Custom Telemetry to xConnect

Used to collect telemetry from outside services that can POST a formed JSON object.

Basically, you can create your own telemetry collection script, POST it to this API endpoint, and it will appear in your cloud dashboard along with all other telemetry.

URL : http://localhost:8886/submitTelemetry

Method : POST

Auth required : NO

Data constraints

uid value should be a unique UUID per device or object. These can be generated at: https://www.uuidgenerator.net/version4

Note

You may use the value "self" for the uid which will inherit the uid, type, and name that the agent is already using for system telemetry

type value will drive how the device is categorized on the cloud dashboard (Only needed when not using "self")

name value is what the friendly name of the device will be on the cloud dashboard (Only needed when not using "self")

telemetry value is a list that can be a single object or multiple objects. Each object must contain 3 "categories" that are used to assemble the telemetry key

Each telemetry list object needs to have a primaryCategory, secondaryCategory, and tertiaryCategory specified or you will receive a malformed JSON response

{
  "xconnect": {
    "uid": "[unique UID per device or object]",
    "type": "[Device or Asset Type]",
    "name": "[Device Name that is human friendly]",
    "telemetry": [
      {
        "primaryCategory": "[First Value of Telemetry Key]",
        "secondaryCategory": "[Second Value of Telemetry Key]",
        "tertiaryCategory": "[Third Value of Telemetry Key]",
        "value": "[TelemetryValue]"
      }
    ]
  }
}

Data example

{
  "xconnect": {
    "uid": "2bf2aa37-fb9c-460b-8f49-5d671017bec4",
    "type": "Display",
    "name": "Device1234567",
    "telemetry": [
      {
        "primaryCategory": "Display",
        "secondaryCategory": "Model1234",
        "tertiaryCategory": "Resolution",
        "value": "1920x1080"
      },
      {
        "primaryCategory": "Display",
        "secondaryCategory": "Model1234",
        "tertiaryCategory": "Power State",
        "value": "Standby"
      }
    ]
  }
}

Success Response

Code : 201 OK