Qboid Cloud API specifications

PRELIMINARY
Application Version: v0.12.0


Table of content

Qboid Cloud API

API root endpoint

Endpoints Overview

Authentication

API Rate limiting

API Error Codes

JSON/Images Encoding

Endpoints

Qboid Cloud API

The Qboid Cloud API offers a way to interact with data stored in the Qboid Cloud. It allows users to access detailed information about scans and devices, fetch image files, and apply filters for customized queries. Authentication, secured by API tokens generated via Qboid Cloud, ensures data integrity and privacy.

API root endpoint

The QBOID APIs can be accessed through this base URL

https://customers.qboid.ai/api/v1

where v1 specifies the current version of the API.

Hostname

The documentation references customers.qboid.ai as the hostname; please update this to reflect the actual server in use.

Endpoints Overview

The table below provides a summary of the API endpoints. For detailed information, see the specific sections by clicking on the endpoint.

Endpoint Description
/scans Retrieves a list of scans, offering optional filtering by barcode, device, and username. Returns scans sorted by timestamp, from the newest to the oldest.
/scans/{id} Retrieves a single scan by its ID. When enabling base64 image encoding, it returns a record in the exact same format as provided by a Perceptor device.
/images/{path} Retrieves an image file from the server. Can return the image as binary data or base64 encoded string.
/devices Retrieves the list of devices associated with the user. Returns a JSON array containing serial numbers of registered devices.

Authentication

Token Creation

To access the API, start by creating a token:

Using the token

Clients must include the API token in one of the following ways:

Example 1: Including Token in GET Request

This command initiates a GET request to the specified endpoint, incorporating the API token within the query parameter for authentication.

Curl

# Replace YOUR_API_TOKEN with your actual API token.
curl "https://customers.qboid.ai/api/v1/devices?api_token=YOUR_API_TOKEN"

Python

# Replace YOUR_API_TOKEN with your actual API token.
import requests
print(requests.get('https://customers.qboid.ai/api/v1/devices?api_token=YOUR_API_TOKEN').text)
Example 2: Including Token in Header

This command initiates a GET request to the specified endpoint, incorporating the API token within the Authorization header.

Curl

# Replace YOUR_API_TOKEN with your actual API token.
curl -H "Authorization: api_token YOUR_API_TOKEN" "https://customers.qboid.ai/api/v1/devices"

Python

# Replace YOUR_API_TOKEN with your actual API token.
import requests
headers={'Authorization': 'api_token YOUR_API_TOKEN'}
print(requests.get('https://customers.qboid.ai/api/v1/devices', headers=headers).text)

API Rate limiting

The API rate is limited to 60 requests per minute per API token to ensure equitable access and maintain optimal service performance for all users. Exceeding this limit results in a API Quota Exceeded Error. This measure helps prevent overuse and ensures the system remains reliable and responsive. To resume requests after hitting the limit, please wait a few seconds before retrying.

Note: Qboid is actively monitoring API usage and reserve the right to adjust this limit to adapt to changing usage patterns and maintain system integrity. Additionally, a limit on the number of API tokens per user will be introduced in the future to further ensure fair usage and system stability

API Error Codes

When interacting with the API, clients may encounter various errors related to API token authentication and usage. Below is a description of different error types:

JSON/Images Encoding

String fields follow JSON escaping rules: New Line to \n, \ to \\, / to \/, Carriage return to \r, Tab to \t. Images in JSON are base64-encoded Data URI scheme as per RFC-2045, limited to 76 characters per line.

For additional details, please consult the Advanced Encoding Info section in the Qboid Perceptor API specifications.

Endpoints

GET /scans

Description:

This endpoint retrieves a list of scans associated with users in a specific organization. The scans can be filtered by various parameters, including barcode, device, and username. It returns a JSON response containing the scans.

Query Parameters:
Parameter Format Description
limit int
(optional)		 Limits the number of scans returned. Defaults to 10 if not provided.
Note: Currently, a maximum of 1000 entries is allowed. We plan to introduce pagination support soon. Upon implementing pagination, we intend to significantly lower the maximum limit
barcode string
(optional)		 Filters scans by barcode.
device string
(optional)		 Filters scans by device serial.
user string
(optional)		 Filters scans by username. The username must belong to the same organization as the authenticated user in case he belongs to an organization. This filter is IGNORED for authenticated users who DO NOT belong to any organization.
after_ts int
(optional)		 Returns scans uploaded after the specified UNIX timestamp.
before_ts int
(optional)		 Returns scans uploaded before the specified UNIX timestamp.
after_id int
(optional)		 Returns scans with an ID greater than the specified ID.
before_id int
(optional)		 Returns scans with an ID less than the specified ID.
Response:
Sample Request:
GET https://customers.qboid.ai/api/v1/scans?limit=10&barcode=123456&device=FH0402211700000&user=username1
Sample Response:
{
  "scans": [
    {
      "id": 123,
      "timestamp": "2024\/01\/01 10:30:00",
      "ts": 1704105000,
      "l": 10,
      "w": 5,
      "h": 3,
      "weight": 50,
      "barcode": "123456",
      "shape": "Irregular",
      "device": "FH0402211700000",
      "note": "Sample note",
      "attributes": {
        "hazmat": "true"
      },
      "image": "fullres\/username1\/2024\/01\/01\/image\/88111cf0ed12423b98e4712042170b0e.png",
      "imageseg": "fullres\/username1\/2024\/01\/01\/imageseg\/88111cf0ed12423b98e4712042170b0e.png",
      "imagecolor": "fullres\/username1\/2024\/01\/01\/imagecolor\/88111cf0ed12423b98e4712042170b0e.png",
      "user": "username1"
    },
    ...
  ]
}

GET /scans/{id}

Description:

This endpoint retrieves a single scan by its ID. It returns a JSON response containing the scan.

Path Parameters:
Parameter Format Description
id int ID of the scan to retrieve.
Query Parameters:
Parameter Format Description
base64_images boolean [0/1]
(optional)		 Indicates whether to include base64 encoded images in the response. Defaults to false.
Response:
Scan JSON Format

The message structure for this API endpoint conforms to the standard Dimensioning Record used in our M2 Perceptor API. Below is a brief breakdown of the fields. Refer to the Dimensioning Record to get more details about the fields, escaping characters and image encoding. Fields marked as Optional may be missing on the json in case the scan does not include them.

Field Type Description
timestamp String UTC timestamp indicating when the scan was performed, formatted as yyyy/MM/dd HH:mm:ss.
ts int UTC UNIX time epoch indicating the time the sequence was uploaded on the server.
l int Length of the item in mm.
w int Width of the item in mm.
h int Height of the item in mm.
weight int (Optional) Weight of the item in g.
barcode String Barcode associated with the scan.
shape String Shape of the item. Can be either Cuboidal or Irregular.
device String Device serial number.
note String Additional note about the scan.
attributes map(string->string)
{} if empty		 Additional attributes in JSON format.
image String (Optional) The relative path or base64 encoded image data of the image with the bounding box drawn on top.
imagecolor String (Optional) The relative path or base64 encoded image data of the image without the bounding box drawn on top.
imageseg String (Optional) The relative path or base64 encoded image data of the segmented image.
user String Username associated with the scan.

Important Note:
In the response, both timestamp and ts fields are returned, but they represent distinct concepts (in addition to differing in format):

Sample request:
GET https://customers.qboid.ai/api/v1/scans/123?base64_images=1
Sample response:
{
  "id": 123,
  "timestamp": "2024\/02\/26 10:30:00",
  "ts": 1704105000,
  "l": 10,
  "w": 5,
  "h": 3,
  "weight": 50,
  "barcode": "123456",
  "shape": "Irregular",
  "device": "FH0402211700000",
  "note": "Sample note",
  "attributes": {
    "hazmat": "true"
  },
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gIoSUNDX1BST0ZJTEU...",
  "user": "username1"
}

GET /images/{path}

Description:

This endpoint retrieves an image file from the server. It can return the image file as binary data or base64 encoded string depending on the query parameter.

Path Parameters:
Parameter Format Description
path string The relative path to either image, imageseg, or imagecolor, as defined in Message Structure
Query Parameters:
Parameter Format Description
base64 boolean [0/1]
(optional)		 Indicates whether to return the image as base64 encoded string. Defaults to false.
Response:
Sample request
GET https://customers.qboid.ai/api/v1/images/path/to/image.jpg?base64=true
Sample Response:
The binary or the base64 representation of the requested image

GET /devices

Description:

This endpoint retrieves the list of devices associated with the user.

Response:
Sample request
GET https://customers.qboid.ai/api/v1/devices
Sample Response:
["FH0402211700000", "FH0402211700001", "FH0402211700002"]

Table of content

Qboid Cloud API

API root endpoint

Endpoints Overview

Authentication

API Rate limiting

API Error Codes

JSON/Images Encoding

Endpoints