ColorSensing
API docs by Redocly

ColorSensing API (2025-01-28)

root

Check API Status

This method allows verifying the operational status of the API. It responds with information about the API version and a confirmation that it is active and responding correctly.

Responses

Response samples

Content type
application/json
{
  • "api_version": "aws-1.0",
  • "instance_version": "food-idn-paper",
  • "status": "The API is active and responding!"
}

User Login

This method allows users to log in by providing their credentials (name and password). If the credentials are valid, a valid access token is generated for 24 hours. This token will be required to authenticate requests in other API methods.

Request Body schema: application/json
required

Request body in JSON format with the user's credentials.

name
string

Username

password
string

User's password

Responses

Request samples

Content type
application/json
{
  • "name": "user123",
  • "password": "secure_password"
}

Response samples

Content type
application/json
{
  • "statusCode": 200,
  • "body": {
    }
}

accounts

Retrieve user accounts

This method allows retrieving information about user accounts. If the optional user_uuid argument is provided, it returns the data for that specific user. If not specified, it returns a list of all registered users.

Authorizations:
BearerAuth
query Parameters
user_uuid
string
Example: user_uuid=aBcDeFgHiJkLmNoPqRsTuVwXyZ

(Optional) Unique UUID of the user. If provided, the response will include only information for that specific user.

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Authentication token in Bearer token format. This token is required to access the resource.

Responses

Response samples

Content type
application/json
Example
{
  • "user123": "aBcDeFgHiJkLmNoPqRsTuVwXyZ",
  • "user456": "XyZ789AbC123AbC123XyZ789"
}

Create a new user account

This method allows creating a new user account. A username (username) and a password (password) are required.

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Authentication token in Bearer token format. This token is required to access the resource.

Request Body schema: application/json
required

Request body in JSON format with the parameters required to create a new user.

username
string

Username for the new account.

password
string

Password for the new account.

Responses

Request samples

Content type
application/json
{
  • "username": "new_user",
  • "password": "secure_password"
}

Response samples

Content type
application/json
{
  • "message": "User created successfully",
  • "user_uuid": "aBcDeFgHiJkLmNoPqRsTuVwXyZ"
}

labels

Retrieve label information (QRs)

This method allows retrieving information about registered labels (QRs). If the optional label_id argument is provided, it returns the data for the corresponding label. If no argument is specified, it returns a list of all available labels along with their unique identifiers.

Authorizations:
BearerAuth
query Parameters
label_id
string
Example: label_id=AbC123XyZ789

(Optional) Unique identifier of the label. This ID must be a random string of 12 characters, including numbers, uppercase, and lowercase letters. If provided, the response will include only the information for the specified label.

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Authentication token in Bearer token format. This token is required to access the resource.

Responses

Response samples

Content type
application/json
Example
{
  • "label_ids": [
    ]
}

Upload new QR codes (labels)

This method allows uploading new locally generated QRs. It receives an image file and metadata such as name, description, and the number of associated colors. The image is stored in an S3 bucket and the label is registered in the database.

Authorizations:
BearerAuth
query Parameters
project
string
Example: project=Project-A

Name of the project associated with the label.

service
string
Example: service=Service-1

Name of the service generating the label.

name
required
string
Example: name=QR-Example

Name of the label.

description
required
string
Example: description=QR code for product tracking

Description of the label.

n_colors
required
integer
Example: n_colors=5

Number of colors associated with the QR code.

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Authentication token in Bearer token format. This token is required to access the resource.

Request Body schema: multipart/form-data
required

Request body that includes the QR image file in multipart/form-data format.

image
string <binary>

Image file in TIFF format.

Responses

Request samples

Content type
multipart/form-data
{
  "image": "(binary data)"
}

Response samples

Content type
application/json
{
  • "message": "Label successfully uploaded and created",
  • "label_id": "AbC123XyZ789",
  • "image_id": "aBcDeFgHiJkLmNoPqRsTuVwXyZ"
}

images

Retrieve images or image details

This method allows retrieving a list of all images or detailed information about a specific image provided by its image_id. It can also return the image encoded in base64 if the request_type parameter is not specified.

Authorizations:
BearerAuth
query Parameters
image_id
string
Example: image_id=aBcDeFgHiJkLmNoPqRsTuVwXyZ

(Optional) Unique ID of the image to retrieve. If not provided, a list of all image IDs will be returned.

request_type
string
Enum: "info" "image"
Example: request_type=info

(Optional) If specified as info, returns information about the image such as upload date and MIME type. If not provided, returns the image encoded in base64.

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Authentication token in Bearer token format. This token is required to access the resource.

Responses

Response samples

Content type
application/json
Example
{
  • "image_ids": [
    ]
}

Upload a new image

This method allows uploading a new image to the system. The image is stored in an S3 bucket and registered in the database along with its MIME type and a unique ID.

Authorizations:
BearerAuth
header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Authentication token in Bearer token format. This token is required to access the resource.

Request Body schema: multipart/form-data
required

Request body that includes the image file in multipart/form-data format.

file
string <binary>

Image file to upload (jpg, png, tiff).

Responses

Request samples

Content type
multipart/form-data
{
  "file": "(binary data)"
}

Response samples

Content type
application/json
{
  • "message": "Image uploaded successfully",
  • "id": "aBcDeFgHiJkLmNoPqRsTuVwXyZ"
}

results

Retrieve results or result details

This method allows retrieving a list of all results or detailed information about a specific result provided by its result_id. If result_id is not provided, it returns a list of all accessible results.

Authorizations:
BearerAuth
query Parameters
result_id
string
Example: result_id=mzRkcmKyZSQSwFmxSUzPLKrw

(Optional) Unique ID of the result to retrieve. This ID should be a string of 24 alphanumeric characters (uppercase and lowercase). If not provided, a list of result IDs will be returned.

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Authentication token in Bearer token format. This token is required to access the resource.

Responses

Response samples

Content type
application/json
Example
{
  • "result_ids": [
    ]
}

Process and save results

This method allows processing and saving a result associated with an image and a label within a specific project. Results are dynamically generated based on the provided data.

Authorizations:
BearerAuth
path Parameters
project_name
required
string
Example: Project-A

Name of the project to associate the result with. This parameter is required.

query Parameters
image_id
required
string
Example: image_id=aBcDeFgHiJkLmNoPqRsTuVwXyZ

Unique ID of the image on which to create the result. This parameter is required.

label_id
required
string
Example: label_id=AbC123XyZ789

Unique ID of the reference QR for creating the result. This parameter is required.

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Authentication token in Bearer token format. This token is required to access the resource.

Responses

Response samples

Content type
application/json
{
  • "id": "mzRkcmKyZSQSwFmxSUzPLKrw",
  • "image_id": "aBcDeFgHiJkLmNoPqRsTuVwXyZ",
  • "label_id": "AbC123XyZ789",
  • "time_in_out": 2.34,
  • "result_info": {
    }
}

create_qr

Create a new QR code

This method allows creating a new QR code associated with a specific project. The QR code data is dynamically generated based on the provided information.

Authorizations:
BearerAuth
path Parameters
project_name
required
string
Example: Project-A

Name of the project to associate the QR code with. This parameter is required.

header Parameters
Authorization
required
string
Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Authentication token in Bearer token format. This token is required to access the resource.

Request Body schema: application/json
required

Request body in JSON format with the parameters necessary to generate the QR code.

data
string
Default: "default_data"

Data to be included in the QR code.

size
number
Default: 1

Scale of the QR code size.

und
string
Default: "inch"
Enum: "inch" "cm" "mm"

Unit of measurement for the QR code size.

border
integer
Default: 4

Size of the white border around the QR code.

path_to_save
string
Default: "/tmp/"

Path where the QR code will be temporarily saved on the server.

name_to_save
string
Default: "new_qr"

Name of the file containing the QR code.

palette
Array of strings
Default: []

Color palette used for the QR code.

remain_palette
Array of strings
Default: null

Additional color palette used for the remaining areas of the QR code.

version
integer
Default: 3

QR code version.

mode
string
Default: "CMYK_u8"

Color mode of the QR code.

n_is_data
integer
Default: 64

Number of colors in the data area of the QR code.

n_is_ec
integer
Default: 0

Number of colors in the error correction area of the QR code.

seed
integer
Default: 1234

Seed used for generating colors in the QR code.

floor_round
boolean
Default: true

Indicates whether the QR size will be rounded down.

verbose
boolean
Default: true

Displays configuration information for debugging.

Responses

Request samples

Content type
application/json
{
  • "data": "Hello, QR Code!",
  • "size": 1,
  • "und": "inch",
  • "border": 4,
  • "path_to_save": "/tmp/",
  • "name_to_save": "new_qr",
  • "palette": [
    ],
  • "remain_palette": [
    ],
  • "version": 3,
  • "mode": "CMYK_u8",
  • "n_is_data": 64,
  • "n_is_ec": 0,
  • "seed": 1234,
  • "floor_round": true,
  • "verbose": true
}

Response samples

Content type
application/json
{
  • "message": "Label successfully uploaded and created",
  • "label_data": {
    }
}