Classify stops

Required scope: stop_classifications.update. Related: reports.read to find the stops to classify with POST /v1/reports/stops; stop_catalogs.read to list the causes and components each machine accepts with GET /v1/stops/classification-options.

Classify stops: set their general cause, specific cause, component and description. The body is a JSON array of up to 1,000 rows, each its own classification.

Identifying a stop. A stop is identified by its machine and the time it started, not by an id: stop ids can change when a shift is recalculated. Take machine.id and stop.startTime from POST /v1/reports/stops. Open stops, still running, can be classified too.

Choosing a classification. Each machine accepts only the causes of its loss tree and its own components, listed by GET /v1/stops/classification-options. A row sets at least a generalCauseId or a description; specificCauseId needs a generalCauseId.

A row replaces the stop's classification. Whatever a row leaves out is cleared: sending only generalCauseId removes the stop's specific cause, component and description. Sending the same rows again is harmless, so a request that timed out can be retried as is. A cause set by an operator in Pulsar is overwritten too.

Every row comes back with a status, and only classified rows changed anything:

  • classified: the stop now has this classification.
  • stopNotFound: machine machineId has no stop that started at startTime, or it is not one of your machines.
  • duplicateStop: another row in the same request names the same stop, so neither was applied.
  • generalCauseNotAvailable: the general cause is not in the machine's loss tree.
  • specificCauseNotAvailable: the specific cause does not go under the general cause on this machine.
  • componentNotAvailable: the component is not assigned to the machine.

The schema also lists missingClassification and missingGeneralCause. This endpoint rejects such rows with 422 before they reach Pulsar, so you will not receive them.

Result rows echo your rows in request order, with startTime normalized to UTC; match them by position rather than by comparing startTime strings.

The classified rows of a request are saved together. Metrics that depend on the stops' causes are recalculated in the background, so reports may take a moment to show the change.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

A JSON array. Each item has these fields:

Response Body

application/json

application/json

application/json

application/json

application/json

Try it live
PUT
/v1/stops/classifications

This endpoint requires authentication — paste a token in the Authorization section below.

curl -X PUT "https://example.com/v1/stops/classifications" \  -H "Content-Type: application/json" \  -d '[    {      "machineId": 12,      "startTime": "2026-10-12T10:00:00Z"    }  ]'
[  {    "machineId": 12,    "startTime": "2026-10-12T10:00:00Z",    "generalCauseId": "d56aece5-a92a-462e-b275-919e15446bba",    "specificCauseId": "f89b5866-2d26-45a1-8cfc-8295557594d8",    "componentId": "3e8e81cf-7521-4ef9-b6c9-40074aa764c5",    "description": "Bearing seized on the main motor",    "status": "classified"  }]