# Classify stops (https://docs.pulsarml.com/v1/api-reference/stops/put-stops-classifications)

**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.

## `PUT /v1/stops/classifications`

Base URLs:
- `https://draco.prod.pulsarml.com` — Production
- `https://draco.stage.pulsarml.com` — Sandbox (staging)

Authentication: send your API key in the `x-api-key` header.

### Request body (`application/json`, required)

Type: array of object

- `machineId` (integer, required, e.g. `12`) — The machine of the stop: `machine.id` in `POST /v1/reports/stops`.
- `startTime` (string (date-time), required, e.g. `"2026-10-12T10:00:00Z"`) — When the stop started, exactly as `stop.startTime` in `POST /v1/reports/stops`. Together with `machineId` it identifies the stop. A full date and time is required; one without a UTC offset is read as UTC.
- `generalCauseId` (string (uuid), optional, nullable, e.g. `"d56aece5-a92a-462e-b275-919e15446bba"`) — One of the machine's general causes, from `GET /v1/stops/classification-options`.
- `specificCauseId` (string (uuid), optional, nullable, e.g. `"f89b5866-2d26-45a1-8cfc-8295557594d8"`) — One of the specific causes of `generalCauseId` on the machine. Needs `generalCauseId`.
- `componentId` (string (uuid), optional, nullable, e.g. `"3e8e81cf-7521-4ef9-b6c9-40074aa764c5"`) — One of the machine's components, from `GET /v1/stops/classification-options`.
- `description` (string, optional, nullable, min length 1, max length 255, pattern `\S`, e.g. `"Bearing seized on the main motor"`) — A free-text note, not blank. Required when there is no `generalCauseId`.

### Responses

#### 200 — One result per row, in request order

Type: array of object

- `machineId` (integer, required, e.g. `12`) — The machine of the stop: `machine.id` in `POST /v1/reports/stops`.
- `startTime` (string (date-time), required, e.g. `"2026-10-12T10:00:00Z"`) — When the stop started, exactly as `stop.startTime` in `POST /v1/reports/stops`. Together with `machineId` it identifies the stop. A full date and time is required; one without a UTC offset is read as UTC.
- `generalCauseId` (string (uuid), optional, nullable, e.g. `"d56aece5-a92a-462e-b275-919e15446bba"`) — One of the machine's general causes, from `GET /v1/stops/classification-options`.
- `specificCauseId` (string (uuid), optional, nullable, e.g. `"f89b5866-2d26-45a1-8cfc-8295557594d8"`) — One of the specific causes of `generalCauseId` on the machine. Needs `generalCauseId`.
- `componentId` (string (uuid), optional, nullable, e.g. `"3e8e81cf-7521-4ef9-b6c9-40074aa764c5"`) — One of the machine's components, from `GET /v1/stops/classification-options`.
- `description` (string, optional, nullable, min length 1, max length 255, pattern `\S`, e.g. `"Bearing seized on the main motor"`) — A free-text note, not blank. Required when there is no `generalCauseId`.
- `status` ("classified" | "stopNotFound" | "duplicateStop" | "missingClassification" | "missingGeneralCause" | "generalCauseNotAvailable" | "specificCauseNotAvailable" | "componentNotAvailable", required, e.g. `"classified"`) — What happened to this row. Only `classified` rows changed a stop; see the endpoint description for the others.

#### 401 — * `unauthenticated`: The credentials are missing, invalid or expired.

#### 403 — * `missing_scope`: The credentials are valid but lack the scope this endpoint requires.

#### 422 — Validation Error

Type: object (`HTTPValidationError`)

- `detail` (array of object, optional)
  - `loc` (array of string | integer, required)
  - `msg` (string, required)
  - `type` (string, required)
  - `input` (any, optional)
  - `ctx` (object, optional)

#### 429 — * `rate_limited`: The API key exceeded its rate limit. Retry after `Retry-After` seconds.

### Example request

```bash
curl -X PUT 'https://draco.prod.pulsarml.com/v1/stops/classifications' \
  -H 'x-api-key: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "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"
    }
  ]'
```