Reelables Workspace Assets API

openapi: 3.2.0
info:
  title: Reelables Workspace Assets 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: Workspace Assets
paths:
  /workspaces/{workspaceId}/assets:
    get:
      tags:
      - Workspace Assets
      summary: List Assets in a Workspace
      parameters:
      - name: workspaceId
        in: path
        description: The identifier of the Workspace
        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
      - name: inSpaceIds
        in: query
        description: 'Filter the Assets to those currently in a set of Spaces. Comma-separated list, for example: ''?inSpaceIds={spaceId1},{spaceId2},{spaceId3}'''
        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: bleIds
        in: query
        description: 'Filter the Assets to those linked to a set of labels, identified by their BLE_ID. Comma-separated list, for example: ''?bleIds={bleId1},{bleId2},{bleId3}'''
        schema:
          type: string
      - name: searchTerm
        in: query
        description: String to match name of Assets
        schema:
          type: string
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceAssets'
        '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
      operationId: getWorkspacesByWorkspaceIdAssets
      x-operation-id-source: derived
    post:
      tags:
      - Workspace Assets
      summary: Create new Assets 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/WorkspaceAssetsInput'
        required: true
      responses:
        '201':
          description: 201 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceAssets'
        '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
      operationId: postWorkspacesByWorkspaceIdAssets
      x-operation-id-source: derived
components:
  schemas:
    Address:
      type: object
      properties:
        country:
          maxLength: 255
          type: string
          description: The country name. Example 'United Kingdom'
        road:
          maxLength: 255
          type: string
          description: The road name. Example 'Downing Street'
        city:
          maxLength: 255
          type: string
          description: The city name. Example 'London'
        district:
          maxLength: 255
          type: string
          description: The district name. Example 'Westminster'
        postalCode:
          maxLength: 10
          type: string
          description: The postal code. Example 'SW1A 2AA'
        county:
          maxLength: 255
          type: string
          description: The county name. Example 'Greater London'
        state:
          maxLength: 255
          type: string
          description: The state name. Example 'England'
      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
    Coordinate:
      required:
      - latitude
      - longitude
      type: object
      properties:
        latitude:
          maximum: 90
          minimum: -90
          type: number
          description: 'Latitude value of the coordinate. Example: 51.123'
          format: float
        accuracy:
          maximum: 1000000
          minimum: 0
          type: integer
          description: The horrizontal accuracy in metres
          format: int32
        longitude:
          maximum: 180
          minimum: -180
          type: number
          description: 'Longitude value of the coordinate. Example: -0.123'
          format: float
      additionalProperties: false
    Asset:
      required:
      - id
      - name
      - workspaceId
      type: object
      properties:
        inSpaces:
          type: array
          items:
            $ref: '#/components/schemas/AssetInSpace'
        temperatures:
          $ref: '#/components/schemas/AssetTemperatures'
        name:
          maxLength: 500
          pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
          type: string
          description: The name of the Asset
        locations:
          $ref: '#/components/schemas/AssetLocations'
        id:
          maxLength: 20
          pattern: ^[-_A-Za-z0-9]*$
          type: string
          description: 'Unique identifier of the Asset. Example: ''00Es43YBJfNRXNSvLmni'''
        label:
          $ref: '#/components/schemas/AssetLabel'
        createdOn:
          maxLength: 20
          pattern: ^[0-9TZ:-]*$
          type: string
          description: 'Date that the Asset 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
    WorkspaceAssetsInput:
      required:
      - assets
      type: object
      properties:
        assets:
          maxItems: 1000
          type: array
          items:
            required:
            - name
            type: object
            properties:
              name:
                maxLength: 500
                pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
                type: string
                description: The name of the Asset
              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
      description: Assets to create in the Workspace
    AssetTemperatures:
      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/Temperature'
      additionalProperties: false
    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
    Location:
      required:
      - coordinate
      - timestamp
      type: object
      properties:
        lastSeenTimestamp:
          maxLength: 20
          pattern: ^[0-9TZ:-]*$
          type: string
          description: 'Timestamp last seen at the location. Example: ''2019-07-21T17:32:28Z'''
          format: date-time
        coordinate:
          $ref: '#/components/schemas/Coordinate'
        address:
          $ref: '#/components/schemas/Address'
        error:
          maximum: 1000000
          minimum: 0
          type: integer
          description: The horrizontal error in metres [Deprecated - use coordinate.accuracy instead]
          format: int32
        timestamp:
          maxLength: 20
          pattern: ^[0-9TZ:-]*$
          type: string
          description: 'Timestamp of the location. Example: ''2019-07-21T17:32:28Z'''
          format: date-time
      additionalProperties: false
    AssetLocations:
      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/Location'
      additionalProperties: false
    Temperature:
      required:
      - degreesCelsius
      - timestamp
      type: object
      properties:
        timestamp:
          maxLength: 20
          pattern: ^[0-9TZ:-]*$
          type: string
          description: 'Timestamp of the temperature. Example: ''2019-07-21T17:32:28Z'''
          format: date-time
        degreesCelsius:
          maximum: 500
          minimum: -100
          type: number
          description: 'Temperature value rounded to 1 decimal place, for each minute of the hour. Example: -2.1'
          format: float
      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
    AssetInSpace:
      required:
      - enteredOn
      - spaceId
      - spaceName
      type: object
      properties:
        spaceName:
          maxLength: 500
          pattern: ^[a-zA-Z0-9!@#$&()\-`.+,/" ]*$
          type: string
          description: The name of the Space
        spaceId:
          maxLength: 20
          pattern: ^[-_A-Za-z0-9]*$
          type: string
          description: 'Unique identifier of the Space. Example: ''00Es43YBJfNRXNSvLmni'''
        hasExited:
          type: boolean
          description: Indicate whether the Asset has exited the Space
        enteredOn:
          maxLength: 20
          pattern: ^[0-9TZ:-]*$
          type: string
          description: 'Date that the Asset entered the Space. Example: ''2019-07-21T17:32:28Z'''
          format: date-time
        exitedOn:
          maxLength: 20
          pattern: ^[0-9TZ:-]*$
          type: string
          description: 'Date that the Asset exited the Space. Example: ''2019-07-21T17:32:28Z'''
          format: date-time
      additionalProperties: false
    WorkspaceAssets:
      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/Asset'
      additionalProperties: false
      description: Assets in the Workspace
  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.'