openapi: 3.0.1
info:
  title: Reelables Gateway Asset Facilities Workspace Consignments API
  description: RESTful API for partners to send data to the Reelables platform from Gateway devices
  contact:
    email: team@reelables.com
  version: 1.1.1
servers:
- url: https://api.reelables.com/{basePath}
  variables:
    basePath:
      default: gateway
  description: The production URL for sending requests to the Reelables Gateway API.
tags:
- name: Workspace Consignments
paths:
  /workspaces/{workspaceId}/consignments:
    get:
      tags:
      - Workspace Consignments
      summary: List Consignments in a Workspace
      parameters:
      - name: workspaceId
        in: path
        description: The identifier of the Workspace
        required: true
        schema:
          type: string
      - name: request-id
        in: header
        description: 'Unique identifier for the API request. Example: f7ecf495-ca1c-4468-a6c2-6ee3f723fa00'
        schema:
          type: string
      - name: limit
        in: query
        description: 'Number of items to return. Default: 10. Maximum: 10000'
        schema:
          type: string
      - name: nextToken
        in: query
        description: Pagination token to get next page of items
        schema:
          type: string
      - name: trackingRef
        in: query
        description: The tracking reference that identifies the Consignment in the user system
        schema:
          type: string
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceConsignments'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - AuthEndpoint:
        - https://auth.reelables.com/full-access
    post:
      tags:
      - Workspace Consignments
      summary: Create new Consignment in Workspace
      parameters:
      - name: workspaceId
        in: path
        description: The identifier of the Workspace
        required: true
        schema:
          type: string
      - name: request-id
        in: header
        description: 'Unique identifier for the API request. Example: f7ecf495-ca1c-4468-a6c2-6ee3f723fa00'
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceConsignmentsInput'
        required: true
      responses:
        '201':
          description: 201 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceConsignments'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - AuthEndpoint:
        - https://auth.reelables.com/full-access
    patch:
      tags:
      - Workspace Consignments
      summary: Update a Consignment using a Tracking Reference
      parameters:
      - name: workspaceId
        in: path
        description: The identifier of the Workspace
        required: true
        schema:
          type: string
      - name: request-id
        in: header
        description: 'Unique identifier for the API request. Example: f7ecf495-ca1c-4468-a6c2-6ee3f723fa00'
        schema:
          type: string
      - name: trackingRef
        in: query
        description: The tracking reference that identifies the Consignment in the user system
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchConsignmentInput'
        required: true
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Consignment'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Consignment not found in Workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - AuthEndpoint:
        - https://auth.reelables.com/full-access
components:
  schemas:
    Gateway:
      required:
      - gatewayId
      - manufacturer
      type: object
      properties:
        shortId:
          maxLength: 10
          pattern: ^[-_A-Za-z0-9]*$
          type: string
          description: 'Short human-readable Gateway identifier. Example: ''AB1D'''
        isStatic:
          type: boolean
          description: Indicate whether the Gateway is statically located. If so, then longitude and latitude are required.
        latitude:
          maximum: 90
          minimum: -90
          type: number
          description: 'Latitude value of the coordinate. Example: 51.123'
          format: float
        hasPendingCommands:
          type: boolean
          description: Indicate whether there are pending commands for the Gateway
        rssiFilter:
          description: The RSSI filter value for the Gateway BLE receiver (setting RSSI Filter via the API is only currently supported for Particle Gateways)
          oneOf:
          - type: string
            enum:
            - FAR
            - NEAR
            - VERY_NEAR
          - maximum: 0
            minimum: -127
            type: integer
            format: int32
        deviceId:
          maxLength: 100
          pattern: ^[-_A-Za-z0-9]*$
          type: string
          description: 'Manufacturer identifier for the Gateway device. Example: ''e10fce301222e588e1d7482b'''
        gatewayId:
          maxLength: 100
          pattern: ^[-_A-Za-z0-9]*$
          type: string
          description: 'Gateway identifier, which is a combination of manufacturer and deviceId. Example: ''sysLoco_e10fce301222e588e1d7482b'''
        productName:
          maxLength: 100
          pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
          type: string
          description: 'Name of Gateway product. Example: ''HGD4'''
        addedOn:
          maxLength: 20
          pattern: ^[0-9TZ:-]*$
          type: string
          description: 'ISO Timestamp of when the Gateway was linked, in UTC. Example: ''2023-07-21T17:32:28Z'''
          format: date-time
        manufacturer:
          maxLength: 100
          pattern: ^[-_A-Za-z0-9]*$
          type: string
          description: 'Gateway manufacturer. Example: ''sysLoco'''
        longitude:
          maximum: 180
          minimum: -180
          type: number
          description: 'Longitude value of the coordinate. Example: -0.123'
          format: float
      additionalProperties: false
    InFacility:
      required:
      - enteredOn
      - facilityId
      - facilityName
      type: object
      properties:
        hasExited:
          type: boolean
          description: Indicate whether the item has exited the Facility
        facilityId:
          maxLength: 36
          pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
          type: string
          description: 'Unique identifier of the Facility. Example: ''d290f1ee-6c54-4b01-90e6-d701748f0851'''
          format: uuid
        enteredOn:
          maxLength: 20
          pattern: ^[0-9TZ:-]*$
          type: string
          description: 'Date that the item entered the Facility. Example: ''2023-07-21T17:32:28Z'''
          format: date-time
        facilityName:
          maxLength: 500
          pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
          type: string
          description: The name of the Facility
        exitedOn:
          maxLength: 20
          pattern: ^[0-9TZ:-]*$
          type: string
          description: 'Date that the item exited the Facility. Example: ''2023-07-21T17:32:28Z'''
          format: date-time
        userFacilityId:
          maxLength: 500
          type: string
          description: A facility identifier relevant to the user
      additionalProperties: false
    Consignment:
      required:
      - id
      - trackingRef
      - workspace
      type: object
      properties:
        pieces:
          $ref: '#/components/schemas/ConsignmentPieces'
        trackingRef:
          maxLength: 500
          type: string
          description: The tracking reference that identifies the Consignment in the user system
        gateways:
          $ref: '#/components/schemas/ConsignmentGateways'
        workspace:
          $ref: '#/components/schemas/Workspace'
        destination:
          type: object
          properties:
            name:
              maxLength: 500
              type: string
              description: 'Name of the destination. Example: LHR'
            facility:
              $ref: '#/components/schemas/Facility'
          additionalProperties: false
        id:
          maxLength: 36
          pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
          type: string
          description: 'Unique identifier of the Consignment. Example: ''d290f1ee-6c54-4b01-90e6-d701748f0851'''
          format: uuid
        isActive:
          type: boolean
          description: Indicates whether the Consignment is actively being tracked
        deactivated:
          required:
          - when
          type: object
          properties:
            where:
              type: object
              properties:
                facility:
                  $ref: '#/components/schemas/Facility'
              additionalProperties: false
            when:
              maxLength: 20
              pattern: ^[0-9TZ:-]*$
              type: string
              description: 'ISO Timestamp when Consignment was de-activated. Example: ''2023-07-21T17:32:28Z'''
              format: date-time
          additionalProperties: false
        activated:
          required:
          - when
          type: object
          properties:
            where:
              type: object
              properties:
                facility:
                  $ref: '#/components/schemas/Facility'
              additionalProperties: false
            when:
              maxLength: 20
              pattern: ^[0-9TZ:-]*$
              type: string
              description: 'ISO Timestamp when Consignment was activated. Example: ''2023-07-21T17:32:28Z'''
              format: date-time
          additionalProperties: false
      additionalProperties: false
    ConsignmentPiecesInput:
      maxItems: 100
      type: array
      description: Pieces to add to a Consignment
      items:
        required:
        - label
        type: object
        properties:
          trackingRef:
            maxLength: 500
            type: string
            description: The tracking reference that identifies the Piece in the user system
          label:
            required:
            - nfcId
            type: object
            properties:
              nfcId:
                maxLength: 20
                pattern: ^[a-zA-Z0-9]*$
                type: string
                description: 'Label NFC identifier, used when creating an Asset and linking a Label at the same time. Example: ''0000007B'''
            additionalProperties: false
        additionalProperties: false
    Workspace:
      required:
      - id
      - name
      type: object
      properties:
        name:
          maxLength: 500
          pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
          type: string
          description: The name of the Workspace
        id:
          maxLength: 36
          pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
          type: string
          description: 'Unique identifier of the workspace. Example: ''d290f1ee-6c54-4b01-90e6-d701748f0851'''
          format: uuid
      additionalProperties: false
    ConsignmentGatewaysInput:
      maxItems: 1
      type: array
      description: Gateways to add to a Consignment
      items:
        required:
        - deviceId
        - manufacturer
        type: object
        properties:
          registerGateway:
            type: boolean
            description: Indicates whether the gateway should be registered. True - will register a new gateway (productName is required) False - indicates that the gateway has already been registered
          deviceId:
            maxLength: 100
            pattern: ^[-_A-Za-z0-9]*$
            type: string
            description: 'Manufacturer identifier for the Gateway device. Example: ''e10fce301222e588e1d7482b'''
          productName:
            maxLength: 100
            pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
            type: string
            description: 'Name of Gateway product. Example: ''HGD4'''
          manufacturer:
            oneOf:
            - type: string
              description: 'Gateway manufacturer. Example: ''sysLoco''. If you want us to support a new manufacturer, please contact us at support@reelables.com'
              enum:
              - hpeAruba
              - cassiaNetworks
              - particle
              - sysLoco
              - versa
        additionalProperties: false
    WorkspaceConsignments:
      required:
      - items
      type: object
      properties:
        nextToken:
          maxLength: 5000
          pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/"]*$
          type: string
          description: Pagination token
        items:
          type: array
          items:
            $ref: '#/components/schemas/Consignment'
      additionalProperties: false
      description: Consignments in the Workspace
    ConsignmentPieces:
      required:
      - items
      type: object
      properties:
        total:
          maximum: 1000000
          minimum: 0
          type: integer
          description: The total number of items in all pages of results
          format: int32
        nextToken:
          maxLength: 5000
          pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/"]*$
          type: string
          description: Pagination token
        items:
          type: array
          items:
            $ref: '#/components/schemas/Piece'
      additionalProperties: false
      description: Pieces in the Consignment
    LabelConfig:
      type: object
      properties:
        reportingInterval:
          type: string
          description: Interval at which the label reports locations. Example values include 'default (every 20 minutes), 'hourly', 'daily', 'twoDays'
      additionalProperties: false
    ConsignmentGateways:
      required:
      - items
      type: object
      properties:
        nextToken:
          maxLength: 5000
          pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/"]*$
          type: string
          description: Pagination token
        items:
          type: array
          items:
            $ref: '#/components/schemas/Gateway'
      additionalProperties: false
      description: Gateways in the Consignment
    ErrorResponse:
      required:
      - errors
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                maxLength: 100
                pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/"]*$
                type: string
                description: An application-specific error code, expressed as a string value
              id:
                maxLength: 100
                pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/"]*$
                type: string
                description: A unique identifier for this particular occurrence of the problem
              detail:
                maxLength: 500
                pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
                type: string
                description: A human-readable explanation specific to this occurrence of the problem
              title:
                maxLength: 100
                pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
                type: string
                description: A short, human-readable summary of the problem
              status:
                maxLength: 3
                pattern: ^[0-9]*$
                type: string
                description: The HTTP status code applicable to this problem, expressed as a string value
            additionalProperties: false
      additionalProperties: false
      description: This is an error
    Piece:
      required:
      - consignmentId
      - id
      - trackingRef
      - workspaceId
      type: object
      properties:
        trackingRef:
          maxLength: 500
          type: string
          description: The tracking reference that identifies the Piece in the user system
        inFacilities:
          maxItems: 10000
          type: array
          items:
            $ref: '#/components/schemas/InFacility'
        consignmentId:
          maxLength: 36
          pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
          type: string
          description: 'Unique identifier of the Consignment. Example: ''d290f1ee-6c54-4b01-90e6-d701748f0851'''
          format: uuid
        id:
          maxLength: 20
          pattern: ^[-_A-Za-z0-9]*$
          type: string
          description: 'Unique identifier of the Piece. Example: ''00Es43YBJfNRXNSvLmni'''
        label:
          $ref: '#/components/schemas/AssetLabel'
        createdOn:
          maxLength: 20
          pattern: ^[0-9TZ:-]*$
          type: string
          description: 'Date that the item was created, in UTC. Example: ''2019-07-21T17:32:28Z'''
          format: date-time
        workspaceId:
          maxLength: 36
          pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
          type: string
          description: 'Unique identifier of the workspace. Example: ''d290f1ee-6c54-4b01-90e6-d701748f0851'''
          format: uuid
      additionalProperties: false
    Facility:
      required:
      - id
      - name
      - workspaceId
      type: object
      properties:
        createdAt:
          maxLength: 20
          pattern: ^[0-9TZ:-]*$
          type: string
          description: 'Date that the item was created, in UTC. Example: ''2019-07-21T17:32:28Z'''
          format: date-time
        name:
          maxLength: 500
          pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
          type: string
          description: The name of the Facility
        id:
          maxLength: 36
          pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
          type: string
          description: 'Unique identifier of the Facility. Example: ''d290f1ee-6c54-4b01-90e6-d701748f0851'''
          format: uuid
        workspaceId:
          maxLength: 36
          pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
          type: string
          description: 'Unique identifier of the workspace. Example: ''d290f1ee-6c54-4b01-90e6-d701748f0851'''
          format: uuid
        userFacilityId:
          maxLength: 500
          type: string
          description: A facility identifier relevant to the user
      additionalProperties: false
    ConsignmentInput:
      required:
      - pieces
      - trackingRef
      type: object
      properties:
        pieces:
          $ref: '#/components/schemas/ConsignmentPiecesInput'
        trackingRef:
          maxLength: 500
          type: string
          description: The tracking reference that identifies the Consignment in the user system
        gateways:
          $ref: '#/components/schemas/ConsignmentGatewaysInput'
      additionalProperties: false
      description: Consignment data
    AssetLabel:
      required:
      - addedOn
      - bleId
      - nfcId
      type: object
      properties:
        bleId:
          maximum: 2147483647
          minimum: 0
          type: integer
          description: 'Label BLE identifier. Example: 123'
          format: int32
        nfcId:
          maxLength: 20
          pattern: ^[a-zA-Z0-9]*$
          type: string
          description: 'Label NFC identifier, used when creating an Asset and linking a Label at the same time. Example: ''0000007B'''
        config:
          $ref: '#/components/schemas/LabelConfig'
        addedOn:
          maxLength: 20
          pattern: ^[0-9TZ:-]*$
          type: string
          description: 'Date that the Label was linked to the Asset, in UTC. Example: ''2019-07-21T17:32:28Z'''
          format: date-time
      additionalProperties: false
    WorkspaceConsignmentsInput:
      required:
      - consignments
      type: object
      properties:
        consignments:
          maxItems: 1
          type: array
          items:
            $ref: '#/components/schemas/ConsignmentInput'
      additionalProperties: false
      description: Consignments to create in the Workspace
    PatchConsignmentInput:
      type: object
      properties:
        isActive:
          type: boolean
          description: Indicates whether the Consignment is actively being tracked
      additionalProperties: false
      description: Consignment data
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header