Reelables Consignments API

openapi: 3.2.0
info:
  title: Reelables Consignments API
  description: RESTful API for communicating with the Reelables Platform.
  contact:
    email: team@reelables.com
  version: 1.3.11
servers:
- url: https://api.reelables.com/{basePath}
  variables:
    basePath:
      default: v1
  description: The production URL for sending requests to the Reelables API.
security:
- AuthEndpoint:
  - https://auth.reelables.com/full-access
tags:
- name: Consignments
paths:
  /consignments/{consignmentId}:
    get:
      tags:
      - Consignments
      summary: Get Consignment
      parameters:
      - name: request-id
        in: header
        description: 'Unique identifier for the API request. Example: f7ecf495-ca1c-4468-a6c2-6ee3f723fa00'
        schema:
          type: string
      - name: consignmentId
        in: path
        description: The identifier of the Consignment
        required: true
        schema:
          type: string
      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
      operationId: getConsignmentsByConsignmentId
      x-operation-id-source: derived
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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
  securitySchemes:
    AuthEndpoint:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.reelables.com/oauth2/token
          scopes:
            https://auth.reelables.com/full-access: Full access to the Public API
x-topics:
- title: Getting started
  content: Before using the Reelables API, you require a `CLIENT_ID` and `CLIENT_SECRET` to authenticate your requests. You can obtain these by contacting [Reelables Support](mailto:support@reelables.com)
- title: Authentication
  content: 'Our authentication is based on the Client Credentials flow of the OAuth 2.0 authentication framework ([Client Credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4)).


    You need to retrieve an access token (`ACCESS_TOKEN`) from our authentication endpoint to then send in the header (`"Authorization: Bearer ACCESS_TOKEN"`) of subsequent requests.


    **To obtain an `ACCESS_TOKEN`, send a POST request to https://auth.reelables.com/oauth2/token?grant_type=client_credentials with headers:**

    - `"Content-Type": "application/x-www-form-urlencoded"`

    - `"Authorization": "Basic base64(CLIENT_ID>:<CLIENT_SECRET>)"`

    where base64() is the base64-encoded representation of the `<CLIENT_ID>:<CLIENT_SECRET>` combination.


    **Using the `ACCESS_TOKEN` in requests:**

    - add an `Authorization` header to your request including the `ACCESS_TOKEN` as the value: `"Authorization: Bearer ACCESS_TOKEN"`

    - the `ACCESS_TOKEN` is valid for 1 hour. Once it has expired, re-authenticate to obtain a fresh `ACCESS_TOKEN`

    '
  example: '_Example Authentication request_

    ```curl --request POST --url ''https://auth.reelables.com/oauth2/token?grant_type=client_credentials'' --user CLIENT_ID:CLIENT_SECRET --header ''Content-Type: application/x-www-form-urlencoded''```

    - Note: using the curl --user option adds an `Authorization` header with value `Basic Base64(CLIENT_ID:CLIENT_SECRET)`'
- title: Errors
  content: 'The API uses standard HTTP response codes to indicate the success or failure of requests. Statuses in the `2xx` range indicate success; statuses in the `4xx` and `5xx` ranges indicate errors. The format of error messages is unified, and can be distinguished by their `status` key. The `title` and `detail` are plain English explanations of the problem.

    '
  example: "```json\n{\n  \"status\": \"status_code\",\n  \"id\": \"A unique identifier for this particular occurrence of the problem.\",\n  \"title\": \"A short, human-readable summary of the problem.\",\n  \"detail\": \"A human-readable explanation specific to this occurrence of the problem.\",\n}\n```\n"
- title: Versioning and backwards compatibility
  content: 'The API is versioned by path (`/v1/...`). When we introduce breaking changes, we will increase this version number. We will of course continually make backward-compatible changes without increasing the version number.


    Examples of things we do **not** consider breaking include:

    * Adding new API resources.

    * Adding new optional request parameters to existing API methods.

    * Adding new properties to existing API responses. We will occasionally move response fields in the API, and will continue to return the existing field in its previous location, while removing it from this documentation.

    * Changing the order of properties in existing API responses.

    * Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings. Strings that are marked as const or enum in this documentation will not change.

    '
- title: Rate limiting
  content: 'We enforce a rate limit on how many HTTP requests can be made in a given period. When the limit is reached, the API will return an error `429 Too Many Requests`.

    '
- title: Data Entities
  content: 'The core entities in the Reelables API are:

    - **`Workspace`**: a permissions boundary within the Reelables Platform.

    Typically this is an organization or team but it can also represent an application across several organizations, for example when multiple parties have visibility of `Assets` through a supply chain.


    `Assets`, `Spaces`, `Printers`, `Consignments` and `Facilities` all exist within the context of a `Workspace`. `Users` can have permissions in more than one `Workspace`.

    - **`Asset`**: a physical item that can be tracked. Reelables `Labels` are activated (typically by a `Printer`) and attached to `Assets`.

    - **`Space`**: a physical area within which `Assets` can be detected. A `Space` can be static (e.g. a receiving bay in a `Facility`) or mobile (e.g. in the trailer of a truck). A `Space` is characterized in the real world by a `Gateway`, a physical device that listens for signals from Reelables `Labels`.

    - **`Consignment`**: A collection of pieces that are being tracked. In the context of a `Consignment` a piece is an `Asset`.

    - **`Facility`**: A physical location, comprised of one or more `Spaces` where `Assets` are stored or transit through. E.g. a warehouse or distribution center.

    - **`Label`**: A Reelables smart label that produces signals that are detected by a `Gateway`.

    - **`Gateway`**: A device that listens for signals from `Labels`.

    - **`Printer`**: a physcial device that enables customers to use Reelables `Labels` at scale. `Printers` are linked to a `Workspace` and are used to print `Labels` for `Assets`.

    - **`User`**: can be a part of one or more `Workspaces`, their permissions within those `Workspaces` are role-based.'