Railcar API

Classify a class list

Creates a class list (switch list) from a list of car numbers by automatically picking destination tracks based on the carrier’s configured block-to-track scope.

This is the API equivalent of the inventory Classify dialog: you provide just the cars, and Cedar mirrors the UI logic to compute where each car goes. Customers replacing the existing class-list API typically batch 5–60 cars per call, scoped to the lead/shift the crew is working — see the switchListBatch example for a realistic shape.

Classification logic (per car, in request order):

Find the parent grouping of the carrier-configured block type (for example yard_block).
Look up the assigned tracks for that block in priority order.
Pick the first assigned track with capacity for the car.
Otherwise fall back to the lowest-priority assigned track.
Otherwise — only when a block exists — fall back to the car’s current track if classifyFallbackToCurrentTrack is enabled in carrier settings.

The operation is atomic: if any car cannot be resolved (missing in inventory, has no block of the carrier-configured type, or has no usable destination) the entire request is rejected and no class list is created. Cars without a block are always rejected, regardless of the fallback setting, mirroring the inventory dialog’s behaviour.

Usage notes:

equipmentInitialAndNumbers accepts entries like "BNSF 999001". The order is preserved in the resulting class list (it determines workOrderPriority on the persisted tasks) and is also used for capacity accounting.
scope is optional. When omitted, the first scope accessible to the caller is used. Scopes that do not start with block2track_ are automatically prefixed. A scope that is not configured for the carrier is rejected with 400 Bad Request.
jobId is optional. Carriers commonly pass the train or job number the crew is working (for example 350 or MORNING-JOB-12); when omitted, a label like Classify 2026-04-30 22:34:11 UTC is generated.
isBack defaults to false; set to true to switch from the back of the track.
The inventory page also offers a Classify by Current Track action that splits a multi-track selection into one class list per source track. To replicate that, partition the cars by current track yourself and call this endpoint once per group (see the byCurrentTrackPerCall example).

Permission required: workOrderManagement.classList.classifyThirdParty.

POST

ims

work-orders

class-lists

classify

curl --request POST \
  --url https://api-lg.arms.cedarai.com/ims/work-orders/class-lists/classify \
  --header 'Content-Type: application/json' \
  --header 'x-arms-api-key: <api-key>' \
  --header 'x-arms-assume-user: <api-key>' \
  --data '
{
  "carrierId": 1234,
  "equipmentInitialAndNumbers": [
    "BNSF 999001",
    "UP 999010",
    "CSXT 999090"
  ]
}
'

{
  "resourceId": 123,
  "uuid": "<string>",
  "jobId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "cuts": [
    123
  ],
  "isBack": true,
  "carrier": {
    "resourceType": "Carrier",
    "resourceId": 123,
    "uuid": "<string>",
    "carrierCode": "<string>",
    "name": "<string>"
  },
  "createdBy": {
    "resourceType": "User",
    "resourceId": 123,
    "uuid": "<string>",
    "displayName": "<string>",
    "email": "jsmith@example.com"
  }
}

{
  "message": "<string>"
}

Authorizations

x-arms-api-key

string

header

required

Your ARMS API key

x-arms-assume-user

string

header

required

Email of a user assigned to the appropriate user group

Query Parameters

carrierId

integer

required

Carrier identifier; required for all endpoints

viewAsUserGroup

string

Optional user group context

Body

application/json

Input for classifying a class list (switch list) from a list of car numbers.

carrierId

integer

required

Carrier identifier.

equipmentInitialAndNumbers

string[]

required

Equipment initial and numbers to classify, e.g. ['BNSF 999001', 'UP 999010']. Order is preserved in the resulting class list and is also used for capacity accounting.

Minimum array length: 1

scope

string

Block-to-track scope to use. Real-world scopes are usually named after the lead and shift the crew is working (for example yard1_first_shift or mainyard_lead_morning). If omitted, the first scope accessible to the caller is used. Values that do not start with block2track_ are automatically prefixed (so yard1_first_shift and block2track_yard1_first_shift are equivalent). A scope that is not configured for the carrier is rejected with 400 Bad Request.

jobId

string

User-specified label for the class list. Carriers commonly pass the train or job number the crew is working (for example 350 or MORNING-JOB-12). If omitted, a label like Classify <UTC timestamp> is generated.

isBack

boolean

default:false

True if switching from the back of the track. Defaults to false.

Response

A class list (switch list) represents a work order for switching operations.

resourceId

integer

uuid

string

UUID that complements the legacy numeric resourceId.

jobId

string

User-specified label for the class list

status

enum<string>

Status of the class list

Available options:

ACTIVE,

ARCHIVED

createdAt

string<date-time>

When the class list was created

cuts

integer[]

Cut positions in the class list

isBack

boolean

True if switching from the back of the track

carrier

object

Show child attributes

createdBy

object

Show child attributes