Loadsmart Unit Limiter API

openapi: 3.2.0
info:
  title: Opendock Nova API Documentation Unit Limiter API
  description: '## Welcome to Opendock Nova! #### What is Opendock Nova? Opendock is an online dock appointment scheduling tool. Facilities such as warehouses, distribution centers, and

    manufacturing plants use it to organize their docks and schedule appointments for outbound pickups and inbound

    deliveries. You can read all our knowledge base

    articles here. We now provide an SSO option for User Authentication. Read

    the docs here. ---


    ## Our APIs


    We have 3 main APIs:


    - REST API called _Neutron_ for performing standard HTTP operations. - Real-time API called _Subspace_ for receiving streaming events whenever objects are Created/Updated/Deleted. - A **"Reference Number Validation"** aka "PO Validation" _protocol_ for validating PO numbers (or similar) before an

    appointment is scheduled. Detailed documentation for it can be found

    here: PO/Ref Number Validation Implementation


    ---


    ## Neutron - REST API


    All endpoints are listed below. Depending on your User Role, some may be forbidden. Almost all endpoints expect a simple

    JWT token to be set in the `Authorization: Bearer` HTTP header. Read more about Bearer

    tokens here. ### Base URL


    The base URL is the same as it is for this document (look at the current URL in your browser''s address bar). For

    example, our production Neutron Base URL is https://neutron.opendock.com. ### Authentication


    To start, call the `POST /auth/login` endpoint to exchange your user credentials (email + password) for a simple JWT

    token. If you don''t have an account yet, reach out to your account admin or contact us for further help. If login is successful, the response will be a JWT token to use as your `Bearer` header as described above. The JWT expiration time depends on your User Role as well as other factors. You may base64-decode your JWT token to view

    more technical details about it. #### Test it:


    To test that your auth headers are set correctly, call the `GET /auth/me` endpoint. It will return a JSON payload with

    your User information. ---


    ## Subspace - Real-time Streaming API


    Subspace is a _read-only_ API that allows your system to recieve streaming real-time information about changes to your

    Appointments, Warehouses, Docks, etc. Using Subspace you can implement a "push"-based approach to your integration instead of relying only on "poll"-ing

    methods (which can be inefficient). Subpsace is based on the famous `socket.io` library. ### Choosing a socket.io Client


    The socket.io project provides a JavaScript client library that works in the browser as well as NodeJS. However there

    are also client implementations in many other languages including C#, Java, Python, and Go, so you should select the

    appropriate client for your project. A good overview of socket.io and a list of client implementations can be found

    here: Socket.IO Introduction


    **NOTE:** Currently Opendock uses socket.io server **v4.x** so please make sure to select an appropriate socket.io

    client version that is protocol compatible. ### Connecting and Authentication


    The base connection URL is the same as the base URL for Neutron above, except with the word "subspace" instead of "

    neutron". For example, our production Subspace connection URL

    is wss://subspace.opendock.com. For convenience, the same JWT token obtained from the Neutron `/auth/login` endpoint above is used for Subspace

    authentication. Connecting and Authenticating are done in a single operation: simply connect to the following `wss` URL:


    ```

    ?token=

    ```


    That can be a little confusing to parse. Here''s a real-life example connection string:


    ```

    wss://subspace.opendock.com?token=eyJhbGciOiJIUzI1Ni...(full token continues)

    ```


    **NOTE:** Currently Opendock only supports the `websocket` transport, so you must specify this in your connection

    settings. Here''s an example of connecting to Subspace using the JavaScript client:


    ```JavaScript

    // NOTE: we assume "accessToken" was already obtained earlier via a call to ''/auth/login''.'
  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: Unit Limiter
paths:
  /loadtype-group:
    post:
      operationId: LoadTypeGroupController_createLoadTypeGroup
      summary: Create a new load type group
      description: Creates a load type group, which is a collection of load types that can be managed together for unit limiting purposes. Load type groups allow you to apply the same unit limits to multiple load types simultaneously, simplifying capacity management.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLoadTypeGroupDto'
      responses:
        '200':
          description: Load type group successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseLoadTypeGroupDto'
      tags:
      - Unit Limiter
      security:
      - bearer: []
    get:
      operationId: LoadTypeGroupController_getLoadTypeGroups
      summary: Retrieve load type groups
      description: Fetches all load type groups for a specific warehouse. Returns a list of groups with their associated load types, useful for displaying configuration options or managing unit limits.
      parameters: []
      responses:
        '200':
          description: List of load type groups for the specified warehouse
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResponseLoadTypeGroupDto'
      tags:
      - Unit Limiter
      security:
      - bearer: []
  /loadtype-group/{id}:
    patch:
      operationId: LoadTypeGroupController_updateLoadTypeGroup
      summary: Update an existing load type group
      description: Updates the name or load type membership of an existing load type group. This allows you to modify which load types are included in the group without recreating it.
      parameters:
      - name: id
        required: true
        in: path
        description: The unique identifier of the load type group to update
        schema:
          format: uuid
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLoadTypeGroupDto'
      responses:
        '200':
          description: Load type group successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseLoadTypeGroupDto'
      tags:
      - Unit Limiter
      security:
      - bearer: []
    delete:
      operationId: LoadTypeGroupController_deleteLoadTypeGroup
      summary: Delete a load type group
      description: Deletes a load type group. This removes the group itself but does not affect the individual load types that were part of the group. Any unit limits referencing this group will need to be reconfigured.
      parameters:
      - name: id
        required: true
        in: path
        description: The unique identifier of the load type group to delete
        schema:
          format: uuid
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteLoadTypeGroupDto'
      responses:
        '200':
          description: Load type group successfully deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
      tags:
      - Unit Limiter
      security:
      - bearer: []
  /unit-limit/configuration:
    post:
      operationId: UnitLimitController_setUpConfiguration
      summary: Create or update unit limit configuration
      description: Configures unit limits for a warehouse based on grouping criteria (warehouse, dock, load type, or load type group). Unit limits control how many appointment or handling units (pallets, etc.) can be scheduled within specific time periods. This helps manage warehouse capacity and prevent overbooking.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnitLimitConfigurationWriteDTO'
      responses:
        '200':
          description: Unit limit configuration successfully created or updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    example: 123e4567-e89b-12d3-a456-426614174000
      tags:
      - Unit Limiter
      security:
      - bearer: []
    get:
      operationId: UnitLimitController_getConfiguration
      summary: Retrieve unit limit configurations
      description: Fetches unit limit configurations based on specified filters such as warehouse, grouper type (dock, load type, or load type group), and unit type. Returns all matching configurations for the authenticated user's organization.
      parameters: []
      responses:
        '200':
          description: List of unit limit configurations matching the query parameters
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnitLimit'
      tags:
      - Unit Limiter
      security:
      - bearer: []
  /unit-limit/count:
    get:
      operationId: UnitLimitController_getCount
      summary: Get unit limit counts for specific configurations
      description: Retrieves actual unit counts for specified unit limit configurations within a date range. This shows how many units have been scheduled against each limit, helping track capacity utilization.
      parameters: []
      responses:
        '200':
          description: List of unit counts for the requested unit limits and date range
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnitLimitCount'
      tags:
      - Unit Limiter
      security:
      - bearer: []
  /unit-limit/validate:
    post:
      operationId: UnitLimitController_validateUnitLimit
      summary: Validate if scheduling at a given time would breach unit limits
      description: Checks whether creating an appointment with the specified warehouse, dock, load type, and time interval would violate any configured unit limits. Returns an array of results for each day in the interval.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnitLimitValidateDTO'
      responses:
        '200':
          description: Unit limits validation results for each day in the requested interval
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    valid:
                      type: boolean
                      example: true
                    message:
                      type: string
                      example: Unit limits validation passed
                    date:
                      type: string
                      example: '2025-11-05'
      tags:
      - Unit Limiter
      security:
      - bearer: []
components:
  schemas:
    CreateLoadTypeGroupDto:
      type: object
      properties:
        tags:
          type: object
    ResponseLoadTypeGroupDto:
      type: object
      properties: {}
    UnitLimitCount:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the record
          example: a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5
          readOnly: true
        createDateTime:
          format: date-time
          type: string
          description: The date and time when the record was created
          example: '2023-10-01T12:00:00Z'
          readOnly: true
        createdBy:
          type: object
          description: The ID of the user who created the record
          example: a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5
          readOnly: true
        lastChangedDateTime:
          format: date-time
          type: string
          description: The date and time when the record was last changed
          example: '2023-10-01T12:00:00Z'
          readOnly: true
      required:
      - id
      - createDateTime
      - createdBy
      - lastChangedDateTime
    UnitLimitValidateDTO:
      type: object
      properties:
        tags:
          type: object
        warehouseId:
          type: string
          description: The warehouse of the unit limit configuration
          example: 550e8400-e29b-41d4-a716-446655440000
        dockId:
          type: string
          description: The dock of the unit limit configuration
          example: 550e8400-e29b-41d4-a716-446655440001
        loadTypeId:
          type: string
          description: The load type of the unit limit configuration
          example: 550e8400-e29b-41d4-a716-446655440002
        start:
          type: string
          description: Start date of the unit limit validation period
          example: '2025-11-01'
        end:
          type: string
          description: End date of the unit limit validation period (must be within 5 days of start date)
          example: '2025-11-04'
        requestedUnits:
          type: number
          description: Number of units requested within the specified date range
          example: 10
      required:
      - warehouseId
      - dockId
      - loadTypeId
      - start
      - end
    DeleteLoadTypeGroupDto:
      type: object
      properties:
        tags:
          type: object
    UnitLimit:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the record
          example: a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5
          readOnly: true
        createDateTime:
          format: date-time
          type: string
          description: The date and time when the record was created
          example: '2023-10-01T12:00:00Z'
          readOnly: true
        createdBy:
          type: object
          description: The ID of the user who created the record
          example: a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5
          readOnly: true
        lastChangedDateTime:
          format: date-time
          type: string
          description: The date and time when the record was last changed
          example: '2023-10-01T12:00:00Z'
          readOnly: true
      required:
      - id
      - createDateTime
      - createdBy
      - lastChangedDateTime
    UpdateLoadTypeGroupDto:
      type: object
      properties:
        tags:
          type: object
    UnitLimitConfigurationWriteDTO:
      type: object
      properties:
        tags:
          type: object
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http