Loadsmart YMS - Yard View API

openapi: 3.2.0
info:
  title: Opendock Nova API Documentation YMS - Yard View API
  description: '## Welcome to Opendock Nova!'
  version: v4.144.0 - 39b4253
  contact: {}
servers:
- url: https://neutron.opendock.com
  description: Production Server
- url: https://neutron.staging.opendock.com
  description: Staging Server
tags:
- name: YMS - Yard View
paths:
  /yard/view/spot-grid:
    get:
      operationId: YardViewController_getSpotGrid
      summary: Get lean spot grid data optimized for grid view rendering
      parameters:
      - name: warehouseId
        required: true
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpotGridResponseDto'
      tags:
      - YMS - Yard View
      security:
      - bearer: []
  /yard/view/waiting-assets:
    get:
      operationId: YardViewController_getWaitingAssets
      summary: Get asset visits and containers waiting for spot assignment
      parameters:
      - name: warehouseId
        required: true
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YardViewWaitingQueueResponseDto'
      tags:
      - YMS - Yard View
      security:
      - bearer: []
  /yard/view/list-rows:
    get:
      operationId: YardViewController_getListViewRows
      summary: Get flattened list view rows (one row per container or truckless visit)
      parameters:
      - name: warehouseId
        required: true
        in: query
        schema:
          type: string
      - name: includeWaiting
        required: false
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListViewResponseDto'
      tags:
      - YMS - Yard View
      security:
      - bearer: []
  /yard/view/spot-detail:
    get:
      operationId: YardViewController_getSpotDetail
      summary: 'Get full spot detail for drawer: spot, task, assignment, and when applicable…'
      parameters:
      - name: spotId
        required: true
        in: query
        schema:
          type: string
      - name: warehouseId
        required: true
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpotDetailResponseDto'
      tags:
      - YMS - Yard View
      security:
      - bearer: []
components:
  schemas:
    YardViewCompanyRefDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      required:
      - id
      - name
    YardViewLoadTypeRefDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        direction:
          type: string
          enum:
          - Inbound
          - Outbound
          - Inbound/Outbound
      required:
      - id
      - name
      - direction
    YardViewSpotReserveRefDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        isActive:
          type: boolean
        entityName:
          type:
          - object
          - 'null'
          description: SpotReserveEntityEnum
        objectId:
          type:
          - object
          - 'null'
          format: uuid
        validUntil:
          type:
          - string
          - 'null'
          format: date-time
        createDateTime:
          type: string
          format: date-time
        lastChangedDateTime:
          type: string
          format: date-time
      required:
      - id
      - isActive
      - entityName
      - objectId
      - validUntil
      - createDateTime
      - lastChangedDateTime
    ListViewAppointmentDto:
      type: object
      properties:
        id:
          type:
          - object
          - 'null'
          format: uuid
        identifier:
          type:
          - object
          - 'null'
        refNumber:
          type:
          - object
          - 'null'
        confirmationNumber:
          type:
          - object
          - 'null'
        isPlanned:
          type: boolean
      required:
      - id
      - identifier
      - refNumber
      - confirmationNumber
      - isPlanned
    YardViewSpotDetailAssetContainerItemDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        code:
          type: object
        type:
          type: string
          enum:
          - Trailer
          - Container
          - Oversized
          - Chassis
          - Reefer
          - Other
        pickupAppointmentId:
          type: object
          format: uuid
        dropAppointmentId:
          type: object
          format: uuid
      required:
      - id
    SpotGridResponseDto:
      type: object
      properties:
        areas:
          type: array
          items:
            $ref: '#/components/schemas/SpotGridAreaDto'
      required:
      - areas
    CustomFormDataItemDto:
      type: object
      properties:
        objectId:
          type: string
          format: uuid
        formFieldId:
          type: object
          format: uuid
        label:
          type: string
        value:
          type: object
        type:
          type: string
          enum:
          - str
          - bigstr
          - date
          - bool
          - doc
          - multidoc
          - int
          - email
          - phone
          - dropdown
          - dropdownmultiselect
          - combobox
          - timestamp
          - action
      required:
      - objectId
      - label
      - type
    SpotGridAssetContainerEventDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        eventType:
          type: string
          enum:
          - Arrived
          - Loading
          - Loading Complete
          - Unloading
          - Unloading Complete
          - Ready for Pickup
          - Departed
          - Inoperable
          - Missing
        createDateTime:
          type: string
          format: date-time
        createdBy:
          type:
          - object
          - 'null'
          format: uuid
        assetVisitId:
          type:
          - object
          - 'null'
          format: uuid
        assetContainerId:
          type: string
          format: uuid
      required:
      - id
      - eventType
      - createDateTime
      - createdBy
      - assetVisitId
      - assetContainerId
    ListViewRowDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Container ID, or visit ID when visit has no containers
        isWaiting:
          type: boolean
          description: Whether this asset is waiting for assignment vs parked on a spot
        spot:
          allOf:
          - $ref: '#/components/schemas/YardViewSpotRefDto'
        spotArea:
          allOf:
          - $ref: '#/components/schemas/YardViewSpotAreaRefDto'
        spotReserves:
          description: Active spot reserves when row is parked on a spot (empty when waiting). Same shape as spot-grid; derive reserved as length > 0.
          type: array
          items:
            $ref: '#/components/schemas/YardViewSpotReserveRefDto'
        assetArrivedAt:
          type:
          - string
          - 'null'
          format: date-time
        assetContainer:
          allOf:
          - $ref: '#/components/schemas/ListViewAssetContainerDto'
        assetVisit:
          allOf:
          - $ref: '#/components/schemas/ListViewAssetVisitDto'
        appointment:
          allOf:
          - $ref: '#/components/schemas/ListViewAppointmentDto'
        dropAppointmentCompany:
          description: Company that dropped this container
          allOf:
          - $ref: '#/components/schemas/YardViewCompanyRefDto'
        pickupAppointmentCompany:
          description: Company scheduled to pick up this container
          allOf:
          - $ref: '#/components/schemas/YardViewCompanyRefDto'
        dropoffAppointment:
          allOf:
          - $ref: '#/components/schemas/ListViewAppointmentRefDto'
        pickupAppointment:
          allOf:
          - $ref: '#/components/schemas/ListViewAppointmentRefDto'
        openMoveTask:
          allOf:
          - $ref: '#/components/schemas/YardViewOpenMoveTaskRefDto'
        customFormData:
          description: Custom form data entries for this container
          type: array
          items:
            $ref: '#/components/schemas/CustomFormDataItemDto'
      required:
      - id
      - isWaiting
      - spot
      - spotArea
      - spotReserves
      - assetArrivedAt
      - assetContainer
      - assetVisit
      - appointment
      - dropAppointmentCompany
      - pickupAppointmentCompany
      - dropoffAppointment
      - pickupAppointment
      - openMoveTask
      - customFormData
    SpotGridAssignmentDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        spotId:
          type: string
          format: uuid
        createDateTime:
          type: string
          format: date-time
        lastChangedDateTime:
          type: string
          format: date-time
        observation:
          type:
          - object
          - 'null'
        assetVisitId:
          type:
          - object
          - 'null'
          format: uuid
        assetContainerId:
          type:
          - object
          - 'null'
          format: uuid
        assetVisit:
          description: Populated when the assignment targets an asset visit (truck / attached).
          allOf:
          - $ref: '#/components/schemas/SpotGridAssetVisitDto'
        assetContainer:
          description: Populated when the assignment targets a standalone container only.
          allOf:
          - $ref: '#/components/schemas/SpotGridAssetContainerDto'
      required:
      - id
      - spotId
      - createDateTime
      - lastChangedDateTime
      - observation
      - assetVisitId
      - assetContainerId
      - assetVisit
      - assetContainer
    YardViewSpotAreaRefDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      required:
      - id
      - name
    YardViewWaitingQueueResponseDto:
      type: object
      properties:
        assets:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/YardViewWaitingVisitRowDto'
            - $ref: '#/components/schemas/YardViewWaitingContainerRowDto'
            discriminator:
              propertyName: kind
      required:
      - assets
    SpotGridAssetContainerDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type:
          - string
          - 'null'
          enum:
          - Trailer
          - Container
          - Oversized
          - Chassis
          - Reefer
          - Other
        state:
          type:
          - string
          - 'null'
          enum:
          - Full
          - Empty
          - Partially Loaded
        code:
          type: string
        orgId:
          type: string
          format: uuid
        warehouseId:
          type: string
          format: uuid
        assetVisitId:
          type:
          - object
          - 'null'
          format: uuid
        pickupAppointmentId:
          type:
          - object
          - 'null'
          format: uuid
        dropAppointmentId:
          type:
          - object
          - 'null'
          format: uuid
        company:
          allOf:
          - $ref: '#/components/schemas/YardViewCompanyRefDto'
        pickupAppointment:
          allOf:
          - $ref: '#/components/schemas/SpotGridContainerAppointmentRefDto'
        dropAppointment:
          allOf:
          - $ref: '#/components/schemas/SpotGridContainerAppointmentRefDto'
        assetContainerEvents:
          type: array
          items:
            $ref: '#/components/schemas/SpotGridAssetContainerEventDto'
        createDateTime:
          type:
          - string
          - 'null'
          format: date-time
        lastChangedDateTime:
          type:
          - string
          - 'null'
          format: date-time
        tags:
          type:
          - array
          - 'null'
          items:
            type: string
      required:
      - id
      - type
      - state
      - code
      - orgId
      - warehouseId
      - assetVisitId
      - pickupAppointmentId
      - dropAppointmentId
      - company
      - pickupAppointment
      - dropAppointment
      - assetContainerEvents
      - createDateTime
      - lastChangedDateTime
      - tags
    ListViewAssetVisitCarrierRefDto:
      type: object
      properties:
        id:
          type:
          - object
          - 'null'
          format: uuid
        companyId:
          type:
          - object
          - 'null'
          format: uuid
        company:
          allOf:
          - $ref: '#/components/schemas/YardViewCompanyRefDto'
      required:
      - id
      - companyId
      - company
    YardViewOpenMoveTaskRefDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        refNum:
          type: string
          description: 'Display ref number (e.g. Tasks #123)'
        role:
          type: string
          enum:
          - origin
          - destination
          description: 'origin: move task tied to assigned container on this spot; destination: task tied via spot reserve on this spot'
        child:
          description: Child move-task refs used by clients that resolve spot/container links through nested child ids.
          allOf:
          - $ref: '#/components/schemas/YardViewOpenMoveTaskChildRefsDto'
      required:
      - id
      - refNum
      - role
    YardViewSpotRefDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        code:
          type: string
          description: Spot code (display / yard label)
        spotAreaId:
          type: string
          format: uuid
          description: Owning spot area id for presenter hydration
      required:
      - id
      - code
    YardViewAppointmentRefDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: object
          description: Appointment status
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        refNumber:
          type: object
        refNumbers:
          description: All reference numbers on the appointment
          type: array
          items:
            type: string
        confirmationNumber:
          type: object
        dock:
          $ref: '#/components/schemas/YardViewDockRefDto'
        loadType:
          $ref: '#/components/schemas/YardViewLoadTypeRefDto'
      required:
      - id
      - refNumbers
    SpotGridItemDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        code:
          type: string
        type:
          type: string
          description: SpotType enum
        isActive:
          type: boolean
          description: Spot open vs closed. With a container on `spotAssignments[0]`, UI can derive move-task lock (see @nova/core isSpotLocked).
        spotAreaId:
          type: string
          format: uuid
          description: Parent spot area id
        createDateTime:
          type: string
          format: date-time
        lastChangedDateTime:
          type: string
          format: date-time
        spotReserves:
          description: 'Active reserves for this spot (BFF loads active only). UI: isSpotReserved = spotReserves.length > 0.'
          type: array
          items:
            $ref: '#/components/schemas/YardViewSpotReserveRefDto'
        spotAssignments:
          description: At most one assignment for the grid cell; empty when unassigned.
          type: array
          items:
            $ref: '#/components/schemas/SpotGridAssignmentDto'
        openMoveTask:
          description: Active move task when tied to this spot (reserve or assigned container).
          allOf:
          - $ref: '#/components/schemas/YardViewOpenMoveTaskRefDto'
      required:
      - id
      - code
      - type
      - isActive
      - spotAreaId
      - createDateTime
      - lastChangedDateTime
      - spotReserves
      - spotAssignments
      - openMoveTask
    YardViewOpenMoveTaskChildEntityRefDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
      required:
      - id
    SpotGridContainerAppointmentUserDto:
      type: object
      properties:
        company:
          $ref: '#/components/schemas/YardViewCompanyRefDto'
    SpotGridAssetVisitDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        orgId:
          type: string
          format: uuid
        warehouseId:
          type: string
          format: uuid
        visitType:
          type:
          - string
          - 'null'
          enum:
          - LiveUnload
          - LiveLoad
          - Live
          - Drop
          - PickUp
          - DropHook
          - Unknown
        company:
          allOf:
          - $ref: '#/components/schemas/YardViewCompanyRefDto'
        companyHint:
          type:
          - object
          - 'null'
        phone:
          type:
          - object
          - 'null'
        isPlanned:
          type: boolean
        licensePlate:
          type:
          - object
          - 'null'
        dotNumber:
          type:
          - object
          - 'null'
        companyId:
          type:
          - object
          - 'null'
          format: uuid
        checkInAcknowledged:
          type:
          - object
          - 'null'
        createDateTime:
          type: string
          format: date-time
        lastChangedDateTime:
          type: string
          format: date-time
        appointment:
          allOf:
          - $ref: '#/components/schemas/YardViewAppointmentRefDto'
        assetContainers:
          type: array
          items:
            $ref: '#/components/schemas/SpotGridAssetContainerDto'
        assetVisitEvents:
          type: array
          items:
            $ref: '#/components/schemas/SpotGridAssetVisitEventDto'
      required:
      - id
      - orgId
      - warehouseId
      - visitType
      - company
      - companyHint
      - phone
      - isPlanned
      - licensePlate
      - dotNumber
      - companyId
      - checkInAcknowledged
      - createDateTime
      - lastChangedDateTime
      - appointment
      - assetContainers
      - assetVisitEvents
    SpotGridContainerAppointmentRefDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        user:
          $ref: '#/components/schemas/SpotGridContainerAppointmentUserDto'
      required:
      - id
    YardViewOpenMoveTaskChildRefsDto:
      type: object
      properties:
        originSpot:
          $ref: '#/components/schemas/YardViewOpenMoveTaskChildEntityRefDto'
        destinationSpot:
          $ref: '#/components/schemas/YardViewOpenMoveTaskChildEntityRefDto'
        assetContainer:
          $ref: '#/components/schemas/YardViewOpenMoveTaskChildEntityRefDto'
    ListViewAppointmentPresenterDto:
      type: object
      properties:
        id:
          type:
          - object
          - 'null'
          format: uuid
        userId:
          type:
          - object
          - 'null'
          format: uuid
        user:
          allOf:
          - $ref: '#/components/schemas/ListViewUserRefDto'
        refNumber:
          type:
          - object
          - 'null'
        confirmationNumber:
          type:
          - object
          - 'null'
      required:
      - id
      - userId
      - user
      - refNumber
      - confirmationNumber
    SpotDetailResponseDto:
      type: object
      properties:
        spot:
          type: object
          description: 'Full spot for drawer: core fields, spotReserves, spotAssignments[0] with visit/container'
        openMoveTask:
          description: Active move task for this spot when present (same shape as spot-grid / list-rows)
          allOf:
          - $ref: '#/components/schemas/YardViewOpenMoveTaskRefDto'
        arrivalContainers:
          description: When assignment has assetVisit without appointment (unplanned)
          type: array
          items:
            $ref: '#/components/schemas/YardViewSpotDetailAssetContainerItemDto'
        containersWithSamePickupAppointment:
          description: Containers with same pickup appointment as the visit
          type: array
          items:
            $ref: '#/components/schemas/YardViewSpotDetailAssetContainerItemDto'
        containersWithSameDropAppointment:
          description: Containers with same drop appointment as the visit
          type: array
          items:
            $ref: '#/components/schemas/YardViewSpotDetailAssetContainerItemDto'
      required:
      - spot
    ListViewResponseDto:
      type: object
      properties:
        rows:
          type: array
          items:
            $ref: '#/components/schemas/ListViewRowDto'
      required:
      - rows
    ListViewAppointmentRefDto:
      type: object
      properties:
        id:
          type:
          - object
          - 'null'
          format: uuid
        refNumber:
          type:
          - object
          - 'null'
        confirmationNumber:
          type:
          - object
          - 'null'
      required:
      - id
      - refNumber
      - confirmationNumber
    SpotGridAreaDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        warehouseId:
          type: string
          format: uuid
          description: Warehouse this spot area belongs to (same for all areas in this response).
        orgId:
          type: string
          format: uuid
          description: Organization scope for this spot area.
        spots:
          type: array
          items:
            $ref: '#/components/schemas/SpotGridItemDto'
      required:
      - id
      - name
      - warehouseId
      - orgId
      - spots
    ListViewUserRefDto:
      type: object
      properties:
        id:
          type:
          - object
          - 'null'
          format: uuid
        companyId:
          type:
          - object
          - 'null'
          format: uuid
        company:
          allOf:
          - $ref: '#/components/schemas/YardViewCompanyRefDto'
      required:
      - id
      - companyId
      - company
    ListViewAssetContainerDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        code:
          type:
          - object
          - 'null'
          description: Container code / trailer number
        type:
          type:
          - string
          - 'null'
          enum:
          - Trailer
          - Container
          - Oversized
          - Chassis
          - Reefer
          - Other
        state:
          type:
          - string
          - 'null'
          enum:
          - Full
          - Empty
          - Partially Loaded
        status:
          type:
          - string
          - 'null'
          enum:
          - Arrived
          - Loading
          - Loading Complete
          - Unloading
          - Unloading Complete
          - Ready for Pickup
          - Departed
          - Inoperable
          - Missing
        company:
          description: Container owner
          allOf:
          - $ref: '#/components/schemas/YardViewCompanyRefDto'
        createDateTime:
          type:
          - string
          - 'null'
          format: date-time
        assetContainerEvents:
          type: array
          items:
            $ref: '#/components/schemas/ListViewAssetContainerEventDto'
        dropAppointment:
          allOf:
          - $ref: '#/components/schemas/ListViewAppointmentPresenterDto'
        pickupAppointment:
          allOf:
          - $ref: '#/components/schemas/ListViewAppointmentPresenterDto'
        notes:
          type:
          - object
          - 'null'
          description: Free-form notes on the asset container
      required:
      - id
      - code
      - type
      - state
      - status
      - company
      - createDateTime
      - assetContainerEvents
      - dropAppointment
      - pickupAppointment
      - notes
    ListViewAssetContainerEventDto:
      type: object
      properties:
        createDateTime:
          type:
          - string
          - 'null'
          format: date-time
        eventType:
          type:
          - string
          - 'null'
          enum:
          - Arrived
          - Loading
          - Loading Complete
          - Unloading
          - Unloading Complete
          - Ready for Pickup
          - Departed
          - Inoperable
          - Missing
        assetVisitId:
          type:
          - object
          - 'null'
          format: uuid
        assetVisit:
          allOf:
          - $ref: '#/components/schemas/ListViewAssetVisitCarrierRefDto'
      required:
      - createDateTime
      - eventType
      - assetVisitId
      - assetVisit
    YardViewDockRefDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      required:
      - id
      - name
    ListViewAssetVisitDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        company:
          allOf:
          - $ref: '#/components/schemas/YardViewCompanyRefDto'
        phone:
          type:
          - object
          - 'null'
        visitType:
          type:
          - string
          - 'null'
          enum:
          - LiveUnload
          - LiveLoad
          - Live
          - Drop
          - PickUp
          - DropHook
          - Unknown
        arrivedAt:
          type:
          - string
          - 'null'
          format: date-time
        createDateTime:
          type:
          - string
          - 'null'
          format: date-time
        isPlanned:
          type: boolean
      required:
      - id
      - company
      - phone
      - visitType
      - arrivedAt
      - createDateTime
      - isPlanned
    SpotGridAssetVisitEventDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        eventType:
          type: string
          enum:
          - NotArrived
          - Arrived
          - Docked
          - Departed
          - Canceled
          - Attached
          - Detached
          - Appointment Linked
          - Appointment Unlinked
          - RejectedByCheckin
          - RejectedByWarehouse
        createDateTime:
          type: string
          format: date-time
        createdBy:
          type:
          - object
          - 'null'
          format: uuid
        assetVisitId:
          type: string
          format: uuid
        assetContainerId:
          type:
          - object
          - 'null'
          format: uuid
      required:
      - id
      - eventType
      - createDateTime
      - createdBy
      - assetVisitId
      - assetContainerId
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http