Cedarai Ims API
The Ims API from Cedarai — 16 operation(s) for ims.
OpenAPI Specification
openapi: 3.0.1
info:
title: protobuf/arms/charge.proto ChargeService Ims API
version: version not set
servers:
- description: Production (US)
url: https://api-lg-k-h1.arms.cedarai.com
- description: Production (EU)
url: https://api-lg-k-h1.arms.cedarai.se
security:
- ApiKeyAuth: []
AssumeUserAuth: []
tags:
- name: Ims
paths:
/ims/waybills/bill-of-lading:
post:
summary: Create bill of lading
description: 'Create a bill of lading for a waybill.
It will always create a bill of lading regardless of what is provided in the request.
When a `billOfLadingNumber` already exists within the last 6 months for this carrier (regardless of lead equipment), the request is rejected with HTTP 409 — use the update endpoint instead, including to correct lead equipment on an existing bill.
When `waybillTemplateId` is set, Cedar merges template data with the request. Static parties (shipper, consignee, freight bill party, in-care-of) are merged field-by-field; all other parties from the request and template are kept. See [Cross-border (Mexico) waybills](/user-docs/api-reference/cross-border-mexico#parties) for party merge rules when using templates.'
operationId: createBillOfLading
parameters:
- $ref: '#/components/parameters/CarrierId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBillOfLadingInput'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Waybill'
'409':
description: A bill with this number already exists within the lookup window
tags:
- Ims
put:
summary: Update bill of lading
description: 'Update an existing bill of lading identified by `billOfLadingNumber` (within the last 6 months for this carrier).
Immutable fields: `billOfLadingNumber`, `waybillNumber`, and `waybillDate`.
Lead equipment (`equipmentDetails[0].equipmentInitial` / `equipmentNumber`) may be changed via update. Cedar archives the prior bill and creates a replacement bill with the new lead equipment. When a prior outbound 404 EDI was sent for the archived bill, Cedar sends a cancellation 404 (BX01=04, ZC1=CA) for the archived bill after creating the replacement.
For in-place field changes (same lead equipment), when a prior outbound 404 EDI was sent for this bill, Cedar automatically sends a correction 404 (BX01=04, ZC1=CO) after a successful update.
When `waybillTemplateId` is set, Cedar merges template data with the request using the same rules as create.'
operationId: updateBillOfLading
parameters:
- $ref: '#/components/parameters/CarrierId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateBillOfLadingInput'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Waybill'
'400':
description: Immutable field change rejected
'404':
description: No matching bill found within the 6-month lookup window
'409':
description: Multiple bills match the lookup key
tags:
- Ims
/ims/work-orders/class-lists/classify:
post:
summary: Classify a class list
description: '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):
1. Find the parent grouping of the carrier-configured block type (for example `yard_block`).
2. Look up the assigned tracks for that block in priority order.
3. Pick the first assigned track with capacity for the car.
4. Otherwise fall back to the lowest-priority assigned track.
5. 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`.'
operationId: classifyClassList
parameters:
- $ref: '#/components/parameters/CarrierId'
- $ref: '#/components/parameters/ViewAsUserGroup'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ClassifyClassListInput'
examples:
minimal:
summary: Classify three cars using the carrier's default scope
value:
carrierId: 1234
equipmentInitialAndNumbers:
- BNSF 999001
- UP 999010
- CSXT 999090
full:
summary: Classify with an explicit scope, job label, and is-back flag
value:
carrierId: 1234
equipmentInitialAndNumbers:
- BNSF 999001
- UP 999010
scope: shift1
jobId: MORNING-CLASSIFY-2026-04-30
isBack: true
switchListBatch:
summary: Typical morning switch list (mixed Class I and tank-car marks)
description: 'A realistic batch the way a switch crew would build a class list: a dozen-plus cars sourced from one or two yard tracks, classified together under a job number that matches the train/job the crew is working. The numeric `jobId` mirrors how dispatchers actually label switch jobs in production. Equipment numbers in this example are synthetic placeholders (UMLER caps reporting marks at 6 digits).'
value:
carrierId: 1234
scope: yard1_first_shift
jobId: '350'
equipmentInitialAndNumbers:
- UTLX 999020
- UTLX 999021
- TILX 999030
- GATX 999040
- NATX 999050
- BNSF 999002
- DOWX 999060
- SHPX 999070
- GATX 999041
- PROX 999080
- UTLX 999022
- TILX 999031
byCurrentTrackPerCall:
summary: One classify call per source track (mirrors the inventory dialog's 'Classify by Current Track')
description: The inventory UI's 'Classify by Current Track' action partitions a multi-track selection by each car's current track and opens one dialog per group. To replicate that workflow over the API, group the cars yourself and call this endpoint once per source track. Each call produces an independent class list with its own job label so each switch crew gets a clean assignment list.
value:
carrierId: 1234
scope: yard1_first_shift
jobId: 350-from-trk-A12
equipmentInitialAndNumbers:
- UTLX 999020
- UTLX 999021
- TILX 999030
explicitScopeMultiShift:
summary: Explicit shift-scoped classify (carriers often configure separate scopes per shift)
description: Carriers commonly configure two or more block-to-track scopes per crew lead — for example a 1st-shift scope and a 2nd-shift scope that route the same yard blocks to different destination tracks. Pass the relevant scope explicitly to honour the right routing for the crew that is actually on duty.
value:
carrierId: 1234
scope: mainyard_lead_second_shift
jobId: '352'
equipmentInitialAndNumbers:
- BNSF 999002
- BNSF 999003
- UP 999011
- UP 999012
- GATX 999040
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ClassList'
'400':
description: Bad Request
'401':
description: Unauthorized
'404':
description: Not Found
'500':
description: Internal Server Error
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Ims
/ims/groupings/list:
post:
summary: List groupings
description: Returns a simplified list of groupings for a carrier, filtering out consist-related grouping types for third-party consumers.
operationId: listGroupingsThirdParty
parameters:
- $ref: '#/components/parameters/CarrierId'
- $ref: '#/components/parameters/ViewAsUserGroup'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/SimplifiedListGroupingInput'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListGroupingsOutput'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Ims
/ims/work-orders/class-lists/tasks:
post:
summary: List class list tasks
description: 'Retrieves the list of tasks associated with specified class lists.
Usage notes:
- Pagination: Use pageSize, pageNextToken, and pagePrevToken to navigate paginated results.
- Filtering: Combine multiple criteria (e.g., workOrderId, status, equipmentName) to narrow results.
- Date ranges: carrierDateRange is assumed to be in the carrier''s timezone.'
operationId: listClassListTasks
parameters:
- $ref: '#/components/parameters/CarrierId'
- $ref: '#/components/parameters/ViewAsUserGroup'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListClassListTasksInput'
examples:
basic:
summary: Basic pagination
value:
carrierId: 1234
pageSize: 20
filterByWorkOrder:
summary: Filter by class list ID
value:
carrierId: 1234
workOrderId: 5678
filterByStatus:
summary: Filter by status
value:
carrierId: 1234
status:
- NOT_STARTED
- COMPLETED
filterByEquipment:
summary: Filter by equipment
value:
carrierId: 1234
equipmentName: ABC 12345
filterByTracks:
summary: Filter by tracks
value:
carrierId: 1234
currentTrackName: Track 1
assignedTrackName: Track 5
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListClassListTasksOutput'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Ims
/ims/equipment/bulk-edit-charged-history:
post:
summary: Bulk edit railcar charge history
description: Create and delete multiple charged history records in one request (supports dry run).
operationId: bulkEditChargedHistory
parameters:
- $ref: '#/components/parameters/CarrierId'
- $ref: '#/components/parameters/ViewAsUserGroup'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkEditChargedHistoryInput'
examples:
dryrun:
summary: Dry run delete and create
value:
carrierId: 1234
dryrun: true
actions:
- action: DELETE
historyItemId: 789
- action: CREATE
equipmentId: 456
chargeGroupId: 123
timestamp: '2022-04-25T14:30:00Z'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BulkEditChargedHistoryOutput'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Ims
/ims/equipment/load-toolswork:
post:
summary: Toolswork load equipment
description: Bulk load equipment with groupings and weights; supports on-the-fly grouping creation.
operationId: toolsworkLoadEquipment
parameters:
- $ref: '#/components/parameters/CarrierId'
- $ref: '#/components/parameters/ViewAsUserGroup'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ToolsWorkLoadEquipmentInput'
examples:
example1:
summary: Load toolswork with 2 equipment
value:
carrierId: 1
details:
- initialAndNumber: HUEH 862431
netWeightTons: 2000
grossWeightTons: 3000
comments: very nice
groupings:
- type: bin
name: bin 0
- type: ash type
name: ash type 0
- initialAndNumber: YHZT 582774
netWeightTons: 2000
grossWeightTons: 3000
groupings:
- type: bin
name: bin 1
- type: ash type
name: ash type 1
trackName: Jacob Flores
waybillTemplateId: 11
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ToolsWorkLoadEquipmentOutput'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Ims
/ims/equipment/move:
post:
summary: Update railcar inventory (move equipment)
description: 'Move equipment between tracks/spots. Supports sequencing and batch moves.
Usage notes:
- Use to.grouping.resourceId to target a track and to.groupingIndex to control position (0 = front, -1 = back).
- Provide updateIntermodalUnits=true to keep intermodal units in sync when moving equipment.'
operationId: moveEquipment
parameters:
- $ref: '#/components/parameters/CarrierId'
- $ref: '#/components/parameters/ViewAsUserGroup'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MoveEquipmentExternalInput'
examples:
moveToFront:
summary: Move equipment to front of track
value:
items:
- equipment:
resourceId: 1
resourceType: Equipment
locationUpdate:
from: {}
to: {}
updateIntermodalUnits: true
jobName: MOVE TO FRONT
moveToBack:
summary: Move equipment to back of track
value:
items:
- equipment:
resourceId: 2
resourceType: Equipment
locationUpdate:
from: {}
to: {}
updateIntermodalUnits: true
jobName: MOVE TO BACK
moveToMiddle:
summary: Move equipment to middle of track
value:
items:
- equipment:
resourceId: 3
resourceType: Equipment
locationUpdate:
from: {}
to:
groupingIndex: 5
updateIntermodalUnits: true
jobName: MOVE TO MIDDLE
resequence:
summary: Resequence a track
value:
items:
- equipment:
resourceId: 2
resourceType: Equipment
locationUpdate:
from:
grouping:
resourceId: 4
to:
grouping:
resourceId: 4
groupingIndex: 0
updateIntermodalUnits: true
- equipment:
resourceId: 3
resourceType: Equipment
locationUpdate:
from:
grouping:
resourceId: 4
to:
grouping:
resourceId: 4
groupingIndex: 0
updateIntermodalUnits: true
- equipment:
resourceId: 1
resourceType: Equipment
locationUpdate:
from:
grouping:
resourceId: 4
to:
grouping:
resourceId: 4
groupingIndex: 0
updateIntermodalUnits: true
jobName: RESEQUENCE
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MoveEquipmentExternalOutput'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Ims
/ims/customers:
post:
summary: List customers
description: Retrieves a list of customers for the specified carrier.
operationId: listCustomers
parameters:
- $ref: '#/components/parameters/CarrierId'
- $ref: '#/components/parameters/ViewAsUserGroup'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListCustomersInput'
examples:
basic:
summary: List all customers
value:
carrierId: 1234
filterByIds:
summary: Filter by customer IDs
value:
carrierId: 1234
customerIds:
- 100
- 200
- 300
includeShippers:
summary: Include shipper customers
value:
carrierId: 1234
includeShipperCustomers: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListCustomersOutput'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Ims
/ims/work-orders/class-lists/create:
post:
summary: Create a class list
description: 'Creates a new class list (switch list) with the specified equipment moves.
Usage notes:
- Each item represents an equipment move to a target track location.
- The jobId is a user-specified label for the class list.'
operationId: createClassList
parameters:
- $ref: '#/components/parameters/CarrierId'
- $ref: '#/components/parameters/ViewAsUserGroup'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateClassListInput'
examples:
basic:
summary: Create a class list with two equipment moves
value:
carrierId: 1234
jobId: SWITCH-001
items:
- equipmentId: 100
location:
grouping:
resourceId: 10
resourceType: Grouping
groupingIndex: 0
- equipmentId: 200
location:
grouping:
resourceId: 10
resourceType: Grouping
groupingIndex: 1
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ClassList'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Ims
/ims/equipment/notes/update:
post:
summary: Update equipment notes
description: 'Updates notes on one or more pieces of equipment.
Usage notes:
- Use equipmentIds + notes for bulk updates (same note on multiple equipment).
- Use the updates array for per-equipment notes (different note per equipment).
- Pass null for the note value to clear an existing note.
- Notes are limited to 280 characters.
- The response returns the updated equipment objects with third-party visible fields.
Permission required: `inventoryManagement.equipment.updateNotes`'
operationId: updateEquipmentNotes
parameters:
- $ref: '#/components/parameters/CarrierId'
- $ref: '#/components/parameters/ViewAsUserGroup'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEquipmentNotesInput'
examples:
bulkSameNote:
summary: Set the same note on multiple equipment
value:
carrierId: 1234
equipmentIds:
- 100
- 200
- 300
notes: Needs inspection before loading
perEquipmentNotes:
summary: Set different notes per equipment
value:
carrierId: 1234
updates:
- equipmentId: 100
note: Brake issue reported
- equipmentId: 200
note: Cleaned and ready
clearNote:
summary: Clear notes on equipment
value:
carrierId: 1234
equipmentIds:
- 100
notes: null
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEquipmentNotesOutput'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Ims
/ims/groupings/station-tracks:
get:
summary: List station tracks
description: Retrieves a list of station tracks and their associated groupings for a specific carrier.
operationId: listStationTracks
parameters:
- $ref: '#/components/parameters/CarrierId'
- $ref: '#/components/parameters/ViewAsUserGroup'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ListStationTracksInput'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListStationTracksOutput'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Ims
/ims/equipment/switch-request:
post:
summary: Submit railcar switch request
description: 'Submit switch requests for one or more equipment to spots/tracks.
Usage notes:
- When a spot does not exist yet, providing a spot name will create it on the fly.
- requestType codes: PL (Pull), IP (In-place), TR (Transfer), RELEASE, LEAVE.'
operationId: switchRequestEquipment
parameters:
- $ref: '#/components/parameters/CarrierId'
- $ref: '#/components/parameters/ViewAsUserGroup'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SwitchRequestEquipmentInput'
examples:
single:
summary: Single switch request
value:
carrierId: 111111
switchRequests:
- equipmentId: 1
trackId: 2
spot: AD2
requestType: PL
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SwitchRequestEquipmentOutput'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Ims
/ims/equipment/charged-history:
post:
summary: List railcar charge history
description: Retrieves charged history records, filterable by equipment, time range, and flags.
operationId: listChargedHistory
parameters:
- $ref: '#/components/parameters/CarrierId'
- $ref: '#/components/parameters/ViewAsUserGroup'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListChargedHistoryInput'
examples:
basic:
summary: Filter by initial and number
value:
carrierId: 1234
initialAndNumber: XYZ 123456
showDeletion: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListChargedHistoryOutput'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Ims
/ims/work-orders/class-lists:
post:
summary: List class lists
description: 'Retrieves a list of class lists.
Usage notes:
- Pagination: Use pageSize, pageNextToken, and pagePrevToken to navigate paginated results.
- Filtering: Combine multiple criteria (e.g., status, customerName, equipmentName) to narrow results.
- Date ranges: carrierDateRange is assumed to be in the carrier''s timezone.'
operationId: listClassLists
parameters:
- $ref: '#/components/parameters/CarrierId'
- $ref: '#/components/parameters/ViewAsUserGroup'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListClassListsInput'
examples:
basic:
summary: Basic pagination
value:
carrierId: 1234
pageSize: 20
filterByStatus:
summary: Filter by status
value:
carrierId: 1234
status:
- ACTIVE
filterByJobId:
# --- truncated at 32 KB (127 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cedarai/refs/heads/main/openapi/cedarai-ims-api-openapi.yml