Reelables Consignment Gateways API

openapi: 3.2.0
info:
  title: Reelables Consignment Gateways 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: Consignment Gateways
paths:
  /consignments/{consignmentId}/gateways:
    get:
      tags:
      - Consignment Gateways
      summary: List Gateways in a 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
      - 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
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsignmentGateways'
        '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
          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: getConsignmentsByConsignmentIdGateways
      x-operation-id-source: derived
    post:
      tags:
      - Consignment Gateways
      summary: Add Gateways to a 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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsignmentGatewaysInput'
        required: true
      responses:
        '201':
          description: 201 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsignmentGateways'
        '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
          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: postConsignmentsByConsignmentIdGateways
      x-operation-id-source: derived
  /consignments/{consignmentId}/gateways/{gatewayId}:
    delete:
      tags:
      - Consignment Gateways
      summary: Remove a Gateway from a 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
      - name: gatewayId
        in: path
        description: The identifier of the Gateway
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 204 response
          content: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Gateway not found
          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: deleteConsignmentsByConsignmentIdGatewaysByGatewayId
      x-operation-id-source: derived
components:
  schemas:
    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
    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
    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
    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
  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.'