Discovery API

Request

Send a bearer credential to the discovery endpoint. Mutual TLS clients use the dedicated hostname supplied for their integration.

GET /api/customer/v1/discovery
Authorization: Bearer <access-token>
Accept: application/json

The operation requires discovery read scope. Use siteId to narrow the response to one visible site; omit it to return every site authorized for the integration.

Success response

The response describes the resources and hierarchy available to the current credential. This abbreviated example uses synthetic values:

{
  "resources": [
    {
      "name": "time-series",
      "description": "Read-only aggregate measurements for approved tags.",
      "fields": ["timestamp", "siteId", "tagGuid", "value"],
      "supportedFilters": ["timestamp", "siteId", "lineId", "machineId", "tagGuid"],
      "maxTimeRangeDays": 30,
      "maxResultsPerQuery": 1000,
      "minAggregationIntervalSeconds": 60,
      "responseContentType": "application/json"
    }
  ],
  "sites": [
    {
      "id": "site-1",
      "name": "Plant One",
      "lines": [
        {
          "id": "line-1",
          "name": "Packaging",
          "machines": [
            {
              "id": "machine-1",
              "name": "Case Packer",
              "tags": [
                {
                  "tagGuid": "11111111-1111-4111-8111-111111111111",
                  "name": "IsRunning",
                  "dataType": "Bool",
                  "engineeringUnits": null,
                  "category": "connection"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Interpret capabilities

The exact fields, supportedFilters, and limits can differ by credential and resource. Build requests from the returned capabilities rather than assuming the example values.

Only active Friendly Tags approved for export appear. tagGuid is the stable public identity for a Friendly Tag. Store and send it instead of using the mutable display name as an identity. Site, line, and machine names are display metadata; later requests use their returned identifiers.

Use discovered identifiers

Use a returned siteId in every aggregate data or downtime request. A machineId is valid within its returned line, and a tagGuid is valid for the Friendly Tag represented in the hierarchy. Rerun discovery after an integration scope, hierarchy, export approval, or policy change.

See aggregate data API and downtime API for the requests built from discovery.

Errors

A 401 response means the credential could not be accepted. A 403 response means the credential or integration policy does not permit discovery. See resolve Customer API errors for corrective actions and safe escalation details.