openapi: 3.0.3
info:
  title: Union Pacific API
  version: '1.0'
  description: >-
    The Union Pacific API provides developers and businesses with programmatic access
    to real-time railroad supply chain data and operational actions. The API enables
    shipment tracking, equipment management, order placement, case management, and
    intermodal planning. APIs are structured as data objects (building blocks) that
    can be used standalone or combined to create more robust supply chain workflows.
    Authentication uses OAuth 2.0 token-based flow with Client Credentials.
  contact:
    name: Union Pacific API Support
    email: apisupport@up.com
  x-generated-from: documentation
  x-last-validated: '2026-05-03'
servers:
  - url: https://api.up.com
    description: Union Pacific API

components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: >-
        OAuth 2.0 Client Credentials flow. Request a token using your API Client ID
        and password from the token service endpoint. Tokens are time-limited and
        can be cached until expiration.
      flows:
        clientCredentials:
          tokenUrl: https://api.up.com/oauth/token
          scopes: {}

security:
  - oauth2: []

tags:
  - name: Shipment
    description: Track and manage rail shipments with location and ETA data
  - name: Shipment Actions
    description: Perform actions on shipments — order equipment, release, or cancel
  - name: Cases
    description: Manage exception cases for shipments that are off course
  - name: Equipment
    description: Search and identify rail equipment by specifications
  - name: Location
    description: View Union Pacific network facility and location details
  - name: Account
    description: Access company account information
  - name: Waybill
    description: Look up waybill details for shipments
  - name: Intermodal
    description: Manage intermodal planning, reservations, and driver services

paths:
  /shipment:
    get:
      operationId: listShipments
      summary: List Shipments
      description: >-
        Search active shipments to view ETA and current location information.
        Returns shipments matching the provided filters.
      tags:
        - Shipment
      parameters:
        - name: shipmentId
          in: query
          required: false
          description: Filter by shipment identifier
          schema:
            type: string
        - name: equipmentNumber
          in: query
          required: false
          description: Filter by equipment (rail car) number
          schema:
            type: string
        - name: origin
          in: query
          required: false
          description: Origin location code
          schema:
            type: string
        - name: destination
          in: query
          required: false
          description: Destination location code
          schema:
            type: string
        - name: accountId
          in: query
          required: false
          description: Account identifier to filter shipments
          schema:
            type: string
      responses:
        '200':
          description: List of matching shipments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Shipment'
        '401':
          description: Unauthorized — invalid or expired OAuth token
        '403':
          description: Forbidden — insufficient permissions

  /shipment/{shipmentId}:
    get:
      operationId: getShipment
      summary: Get Shipment
      description: Retrieve details for a specific shipment including current location and ETA.
      tags:
        - Shipment
      parameters:
        - name: shipmentId
          in: path
          required: true
          description: Unique shipment identifier
          schema:
            type: string
      responses:
        '200':
          description: Shipment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '401':
          description: Unauthorized
        '404':
          description: Shipment not found

  /releaseShipment:
    post:
      operationId: releaseShipment
      summary: Release Shipment Equipment
      description: Release held equipment associated with a shipment.
      tags:
        - Shipment Actions
      requestBody:
        required: true
        description: Equipment release request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReleaseShipmentRequest'
      responses:
        '200':
          description: Equipment release confirmation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

  /orderEquipment:
    post:
      operationId: orderEquipment
      summary: Order In Equipment
      description: Order rail car equipment for a shipment.
      tags:
        - Shipment Actions
      requestBody:
        required: true
        description: Equipment order request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderEquipmentRequest'
      responses:
        '200':
          description: Equipment order confirmation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

  /cancelRequest:
    post:
      operationId: cancelRequest
      summary: Cancel Request
      description: Cancel a previously submitted equipment or shipment request.
      tags:
        - Shipment Actions
      requestBody:
        required: true
        description: Cancellation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelRequest'
      responses:
        '200':
          description: Cancellation confirmation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

  /case:
    get:
      operationId: listCases
      summary: List Cases
      description: >-
        Find exception cases for shipments that are off course or require attention.
        Returns cases matching the account and filter criteria.
      tags:
        - Cases
      parameters:
        - name: accountId
          in: query
          required: false
          description: Account identifier to filter cases
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Filter by case status
          schema:
            type: string
            enum:
              - OPEN
              - CLOSED
              - IN_PROGRESS
        - name: shipmentId
          in: query
          required: false
          description: Filter cases for a specific shipment
          schema:
            type: string
      responses:
        '200':
          description: List of cases
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Case'
        '401':
          description: Unauthorized

  /case/{caseId}:
    get:
      operationId: getCase
      summary: Get Case
      description: Retrieve details for a specific exception case.
      tags:
        - Cases
      parameters:
        - name: caseId
          in: path
          required: true
          description: Unique case identifier
          schema:
            type: string
      responses:
        '200':
          description: Case details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Case'
        '401':
          description: Unauthorized
        '404':
          description: Case not found

  /equipment:
    get:
      operationId: listEquipment
      summary: List Equipment
      description: Search and identify rail equipment by specifications such as type and size.
      tags:
        - Equipment
      parameters:
        - name: equipmentType
          in: query
          required: false
          description: Type of rail equipment (e.g., boxcar, flatcar, tank car)
          schema:
            type: string
        - name: equipmentNumber
          in: query
          required: false
          description: Specific equipment number to look up
          schema:
            type: string
        - name: accountId
          in: query
          required: false
          description: Account identifier
          schema:
            type: string
      responses:
        '200':
          description: List of equipment
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Equipment'
        '401':
          description: Unauthorized

  /location:
    get:
      operationId: listLocations
      summary: List Locations
      description: View Union Pacific network facility and location details.
      tags:
        - Location
      parameters:
        - name: locationCode
          in: query
          required: false
          description: Filter by location code
          schema:
            type: string
        - name: state
          in: query
          required: false
          description: Filter by US state
          schema:
            type: string
        - name: type
          in: query
          required: false
          description: Location type (e.g., TERMINAL, YARD, INTERMODAL)
          schema:
            type: string
      responses:
        '200':
          description: List of locations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Location'
        '401':
          description: Unauthorized

  /account:
    get:
      operationId: listAccounts
      summary: List Accounts
      description: Retrieve company account information associated with the authenticated user.
      tags:
        - Account
      responses:
        '200':
          description: List of accounts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '401':
          description: Unauthorized

  /waybill:
    get:
      operationId: listWaybills
      summary: List Waybills
      description: Look up waybill details for one or multiple shipments.
      tags:
        - Waybill
      parameters:
        - name: waybillNumber
          in: query
          required: false
          description: Specific waybill number to retrieve
          schema:
            type: string
        - name: shipmentId
          in: query
          required: false
          description: Shipment ID to retrieve associated waybills
          schema:
            type: string
      responses:
        '200':
          description: List of waybills
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Waybill'
        '401':
          description: Unauthorized

  /intermodal/reservation:
    post:
      operationId: createIntermodalReservation
      summary: Create Intermodal Reservation
      description: Create a reservation for an intermodal terminal.
      tags:
        - Intermodal
      requestBody:
        required: true
        description: Intermodal reservation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntermodalReservationRequest'
      responses:
        '200':
          description: Reservation confirmation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntermodalReservation'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

  /intermodal/lane:
    get:
      operationId: listIntermodalLanes
      summary: List Intermodal Lanes
      description: Retrieve available intermodal lanes and service options.
      tags:
        - Intermodal
      parameters:
        - name: origin
          in: query
          required: false
          description: Origin terminal code
          schema:
            type: string
        - name: destination
          in: query
          required: false
          description: Destination terminal code
          schema:
            type: string
      responses:
        '200':
          description: List of available intermodal lanes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IntermodalLane'
        '401':
          description: Unauthorized

  /intermodal/departure:
    get:
      operationId: listIntermodalDepartures
      summary: List Intermodal Departures
      description: Retrieve scheduled intermodal departures.
      tags:
        - Intermodal
      parameters:
        - name: origin
          in: query
          required: false
          description: Origin terminal code
          schema:
            type: string
        - name: destination
          in: query
          required: false
          description: Destination terminal code
          schema:
            type: string
        - name: date
          in: query
          required: false
          description: Departure date (YYYY-MM-DD)
          schema:
            type: string
            format: date
      responses:
        '200':
          description: List of scheduled departures
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IntermodalDeparture'
        '401':
          description: Unauthorized

components:
  schemas:
    Shipment:
      type: object
      description: A rail shipment with tracking and ETA information
      properties:
        shipmentId:
          type: string
          description: Unique shipment identifier
        status:
          type: string
          description: Current shipment status
          enum:
            - IN_TRANSIT
            - DELIVERED
            - DELAYED
            - HELD
            - CANCELLED
        origin:
          type: string
          description: Origin location code
        destination:
          type: string
          description: Destination location code
        currentLocation:
          $ref: '#/components/schemas/Location'
        estimatedArrival:
          type: string
          format: date-time
          description: Estimated time of arrival at destination
        estimatedGate:
          type: string
          format: date-time
          description: Estimated gate time at destination
        equipment:
          type: array
          items:
            $ref: '#/components/schemas/Equipment'
          description: Equipment associated with this shipment
        accountId:
          type: string
          description: Account identifier
        waybillNumber:
          type: string
          description: Associated waybill number
        commodity:
          type: string
          description: Type of commodity being shipped

    Case:
      type: object
      description: An exception case for a shipment that is off course or requires attention
      properties:
        caseId:
          type: string
          description: Unique case identifier
        shipmentId:
          type: string
          description: Associated shipment ID
        status:
          type: string
          description: Case status
          enum:
            - OPEN
            - CLOSED
            - IN_PROGRESS
        type:
          type: string
          description: Type of exception
        description:
          type: string
          description: Human-readable description of the exception
        createdAt:
          type: string
          format: date-time
          description: When the case was created
        updatedAt:
          type: string
          format: date-time
          description: When the case was last updated
        accountId:
          type: string
          description: Account identifier

    Equipment:
      type: object
      description: Rail equipment (car) with specifications and tracking status
      properties:
        equipmentNumber:
          type: string
          description: Equipment identifier (rail car number)
        type:
          type: string
          description: Equipment type (e.g., BOXCAR, FLATCAR, TANK_CAR, INTERMODAL)
        status:
          type: string
          description: Current equipment status
        currentLocation:
          type: string
          description: Current location code
        specifications:
          type: object
          description: Equipment specifications (length, capacity, etc.)
          properties:
            length:
              type: number
              description: Length in feet
            capacity:
              type: number
              description: Capacity in tons

    Location:
      type: object
      description: A Union Pacific network facility or location
      properties:
        locationCode:
          type: string
          description: Location identifier code
        name:
          type: string
          description: Location name
        type:
          type: string
          description: Location type (TERMINAL, YARD, INTERMODAL, STATION)
        city:
          type: string
          description: City
        state:
          type: string
          description: US state code
        latitude:
          type: number
          format: double
          description: Geographic latitude
        longitude:
          type: number
          format: double
          description: Geographic longitude

    Account:
      type: object
      description: Union Pacific customer account
      properties:
        accountId:
          type: string
          description: Unique account identifier
        name:
          type: string
          description: Account name
        type:
          type: string
          description: Account type
        status:
          type: string
          description: Account status

    Waybill:
      type: object
      description: Waybill record for a shipment
      properties:
        waybillNumber:
          type: string
          description: Unique waybill number
        shipmentId:
          type: string
          description: Associated shipment ID
        origin:
          type: string
          description: Origin location code
        destination:
          type: string
          description: Destination location code
        commodity:
          type: string
          description: Commodity description
        weight:
          type: number
          description: Shipment weight in pounds
        accountId:
          type: string
          description: Billing account ID
        createdAt:
          type: string
          format: date-time
          description: Waybill creation date

    ReleaseShipmentRequest:
      type: object
      description: Request body for releasing equipment
      required:
        - shipmentId
      properties:
        shipmentId:
          type: string
          description: Shipment ID to release equipment for
        equipmentNumber:
          type: string
          description: Specific equipment number to release
        releaseType:
          type: string
          description: Type of release

    OrderEquipmentRequest:
      type: object
      description: Request body for ordering rail car equipment
      required:
        - accountId
        - equipmentType
        - origin
        - destination
      properties:
        accountId:
          type: string
          description: Account identifier
        equipmentType:
          type: string
          description: Type of equipment to order
        origin:
          type: string
          description: Origin location code
        destination:
          type: string
          description: Destination location code
        requestedDate:
          type: string
          format: date
          description: Requested equipment available date
        quantity:
          type: integer
          description: Number of units to order
          default: 1

    CancelRequest:
      type: object
      description: Request body for cancelling a request
      required:
        - requestId
      properties:
        requestId:
          type: string
          description: ID of the request to cancel
        reason:
          type: string
          description: Reason for cancellation

    ActionResponse:
      type: object
      description: Response confirming a successful action
      properties:
        confirmationNumber:
          type: string
          description: Unique confirmation number for the action
        status:
          type: string
          description: Status of the action
          enum:
            - SUCCESS
            - PENDING
            - FAILED
        message:
          type: string
          description: Human-readable status message
        timestamp:
          type: string
          format: date-time
          description: When the action was processed

    IntermodalReservationRequest:
      type: object
      description: Request body for creating an intermodal terminal reservation
      required:
        - origin
        - destination
        - date
        - equipmentType
      properties:
        origin:
          type: string
          description: Origin intermodal terminal code
        destination:
          type: string
          description: Destination intermodal terminal code
        date:
          type: string
          format: date
          description: Requested departure date
        equipmentType:
          type: string
          description: Equipment type (e.g., 53FT_CONTAINER, 20FT_CONTAINER)
        quantity:
          type: integer
          description: Number of units
          default: 1
        accountId:
          type: string
          description: Billing account ID

    IntermodalReservation:
      type: object
      description: Confirmed intermodal terminal reservation
      properties:
        reservationId:
          type: string
          description: Unique reservation ID
        status:
          type: string
          description: Reservation status
        confirmationNumber:
          type: string
          description: Confirmation number
        origin:
          type: string
          description: Origin terminal
        destination:
          type: string
          description: Destination terminal
        scheduledDeparture:
          type: string
          format: date-time
          description: Scheduled departure time
        estimatedArrival:
          type: string
          format: date-time
          description: Estimated arrival time

    IntermodalLane:
      type: object
      description: Available intermodal service lane
      properties:
        laneId:
          type: string
          description: Lane identifier
        origin:
          type: string
          description: Origin terminal code
        destination:
          type: string
          description: Destination terminal code
        transitDays:
          type: integer
          description: Standard transit time in days
        frequency:
          type: string
          description: Service frequency (e.g., DAILY, WEEKLY)
        equipmentTypes:
          type: array
          items:
            type: string
          description: Equipment types available on this lane

    IntermodalDeparture:
      type: object
      description: Scheduled intermodal train departure
      properties:
        departureId:
          type: string
          description: Departure identifier
        origin:
          type: string
          description: Origin terminal
        destination:
          type: string
          description: Destination terminal
        scheduledDeparture:
          type: string
          format: date-time
          description: Scheduled departure time
        estimatedArrival:
          type: string
          format: date-time
          description: Estimated arrival time
        availableCapacity:
          type: integer
          description: Available booking capacity