REST APIs
This document provides an overview of the Edgify Agent's REST API Endpoints.
For the most up-to-date information, please use the Swagger documentation hosted within your local agent.
Simply browse to: http://localhost:3000/docs/ on your Edgify-enabled device (the agent must be running).
Important:
To satisfy the digest authentication, you must perform a one-time login via Swagger before you can start executing API calls. At the top of the Swagger page you'll find a section for configuring environment variables (default is "localhost" at port "8090"). Click the "Authorize" button, and you will be prompted for your Edgify username and account token.
If you want to see the Swagger documentation without installing the Agent, you can view the Swagger Docs of the public agent we host on our cloud.
Edgify APIs
POST capture and predict
Endpoint
POST http://localhost:8090/api/v2/capture-and-predict
Description:
The Agent captures an image from the camera feed and infers a prediction. The Agent now optionally accepts a weight parameter in the request body to provide additional context for the prediction.
Request Body Example:
{
"captureTrigger": "scale-stable",
"family": "fruits-and-vegetables",
"weight": 1.25
}
Request Body Parameters
| Parameter | Explanation | Values (Explanation) |
|---|---|---|
| captureTrigger | Mechanism/flow which prompted the agent to capture an image | auto-scale: (scale weight settles above x) |
| barcode: (Barcoded item is scanned) | ||
| button: (On-screen button, could be linked to the existing lookup/picklist button) | ||
| family | Department / category | Fruitsandvegetables |
| Bakery | ||
| This list is not exhaustive - you can send any string value that defines the family of items you wish Edgify to predict |
| weight | Optional weight parameter to enhance prediction context| Decimal value representing the weight measured at capture time (e.g., in kg) |
* family is relevant only when the “Get Prediction” API is called from a menu button, else simply pass an empty value for this parameter.
Response Example
{
"sampleId": "65506cf8-1aa0-4bf3-bcbf-7656ab85a158",
"certain": false,
"options": [
{
"label": "4011",
"certainty": 0.98
}
],
"image": "/9j/4AAQSkZJRgABAQAAAQABAAD/.......",
}
Response Body Parameters
| Parameter | Explanation |
|---|---|
| "sampleId" | Unique ID returned with each inference |
| "certain" | See below |
| "options" | Defines the start of the prediction object. This section will return one or multiple predictions |
| "label" | PLU or barcode for a given item |
| "certainty" | Confidence of prediction as a percentage |
| "image" | The image captured by the agent from the camera feed, encoded in Base64 |
"Unknown" prediction response
When confidence in recognition is very low, the agent will return a prediction object with “Unknown” in the prediction array. This is a normal and key part of the systems ability to learn.
“Certain” flag
Indicates exceptionally high confidence in item recognition. When this flag returns true, it prompts the receiving application software to perform enhanced functionality, such as automatically adding the item straight into the customer's basket or printing a ticket without requiring further validation from the user. Handling of this flag is optional.
Note:
-
If weight is not provided in the request but was recently included in a previous /capture-and-predict request with the same sampleId, the agent reuses the last known weight value automatically.
-
If the sampleId changes and no image is provided, the agent returns an error.
POST /capture
Endpoint
POST http://localhost:8090/api/v2/capture
Description :
The primary function of this endpoint is to capture an image.
Request Body Example:
{
"captureTrigger": "barcode",
}
Request Body Parameters
| Parameter | Explanation | Values (Explanation) |
|---|---|---|
| captureTrigger | Mechanism/flow which prompted the agent to capture an image | barcode: (Barcoded item is scanned) |
| button: (On-screen button, could be linked to the existing lookup/picklist button) |
Response Body Parameters
| Parameter | Explanation |
|---|---|
| "image" | The image captured by the agent from the camera feed, encoded in Base64 |
Response Example
The response is a json object containing a base64 representation of the captured image
{
"image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA..."
}
Response Body Parameters
| Parameter | Explanation |
|---|---|
| "image" | The image captured by the agent from the camera feed, encoded in Base64 |
POST /capture-and-save
Endpoint
POST http://localhost:8090/api/v2/capture-and-save
Description :
This endpoint's primary function is to capture an image from the camera feed and save it with a unique sample ID. It records essential item details, including barcode, category, weight, price, and image source. Upon successful storage, the system returns a unique sample ID.
Request Body Example:
{
"barcode": "ABC1234",
"captureTrigger": "barcode",
"category": "Drinks",
"count": 1,
"family": "Milk",
"groupId": "b932de54-41ca-4f5a-99d5-b9db779f8888",
"imgSource": "ip-camera-SCO-1",
"label": "4201",
"labelTrigger": "RegularMenuSelection",
"name": "Org Milk",
"price": 0.95,
"totalPrice": 0.95,
}
Notes:
- "groupId" is not a mandatory field
Request Body Parameters
| Parameter | Explanation | Values (Explanation) |
|---|---|---|
| barcode | Unique identifier of the product | String: (E.g., "ABC1234") |
| captureTrigger | Mechanism/flow which prompted the capture | menu: (Triggered via menu selection) |
| category | The category of the item | Drinks: (Indicates Drink items) |
| count | The number of items captured | Integer: (E.g., 1) |
| family | The family classification of the item | Milk: (Belongs to the Milk family) |
| groupId | Unique identifier for the group the item belongs to | String: (E.g., "b932de54-41ca-4f5a-99d5-b9db779f8888") |
| imgSource | Source of the image capture | String: (E.g., "ip-camera-SCO-1") |
| label | Label identifier for the product | String: (E.g., "4201") |
| labelTrigger | Mechanism that triggered the label assignment | RegularMenuSelection: (Label assigned through regular menu selection) |
| name | Name of the item | String: (E.g., "Org Milk") |
| price | Unit price of the item | Float: (E.g., 0.95) |
| totalPrice | Total price after discounts or adjustments | Float: (E.g., 0.95) |
Response Body Parameters
| Parameter | Explanation |
|---|---|
| sampleId | Unique identifier for the stored sample |
Response Example
The response is a JSON object containing a unique sampleId.
{
"sampleId": "9c9847e6-591b-4f29-a988-922da9e56484"
}
PUT /samples
Endpoint
PUT http://localhost:8090/api/v2/samples/{sample_id}
Description :
Tells the agent to save a labelled image. These images are used by the Edgify solution to train and improve the recognition model.
Request Body Example:
{
"captureTrigger": "auto-scale",
"labelTrigger": "RecommendationStrip",
"category": "ExoticFruits",
"count": 0,
"image": "/9j/4AAQSkZJRgABAQAA........",
"imgSource": "",
"label": "4011",
"name": "banana",
"price": 1.2,
"weight": 1.5,
"totalPrice": 1.8,
}
Request Body Parameters
| Header | Explanation | Values (Explanation) |
|---|---|---|
| "sampleId" | Unique ID returned with each inference | Pass the value returned by Capture & Predict API |
| "captureTrigger" | Mechanism/flow which prompted the agent to capture an image | Pass the same value as Capture & Predict API |
| "labelTrigger" | Mechanism by which user selects/identifies the item they are purchasing | "EdgifyPrediction": (Edgify predictions shown on-screen for the customer to select) |
| "ManualLookup": (Customer searches the picklist / menus to find their item - AKA the normal process on non-AI enabled scales) | ||
| "HandScanner": (For SCO/Lane POS where an additional barcode scanner is employed) | ||
| "category" (optional) | Retailer catalog hierarchy | Will depend on the retailer, for example: "CitrusFruits", "Alcohol", "PowerTools", "ExoticVegetables", "Pets", "Clothing". |
| "groupId" (optional) | Enables future Edgify functionality | |
| "imgSource" (optional) | ID of the image capture device | Applicable for IP camera use only. Example: "IP-Cam-10-44-01" or "192.168.1.101". |
| "image" | The image captured by the agent from the camera feed, encoded in Base64 | |
| "label" | PLU or barcode for a given item | Example: "8547230239400", "4011", "4133". |
| "name" | The English / Human readable item name | Example: "DietCoke20oz", "BananaOrganic", "GalaApple". |
| "count" | Number of items being purchased | Barcoded items count is always "1". |
| "price" | Item cost per unit weight | Applicable only for weighted items, else do not pass this header. |
| "weight" | The weight of item being purchased | Applicable only for weighted items, else do not pass this header. |
| "totalPrice" | Product of "price" x "weight" | Barcoded item price should be passed here. |
Response Example
{
"matchStrength": "alert-non-match"
}
Response Body Parameters
| Header | Explanation | Values (Explanation) |
|---|---|---|
| "matchStrength" | Logic determining if the label received by Edgify in the Samples API matches the item Edgify sees | "match": (Label received matches item seen - AKA no loss event suspected) "alert-non-match": (Label received does not match item seen by Edgify - Possible loss event/false selection/barcode switching) "unknown": Edgify was unable to confidently match or identify a non-match |
POST /samples
POST http://localhost:8090/api/v2/samples
Description :
Tells the agent to save a labelled image and generate a Unique sample ID. These images are used by the Edgify solution to train and improve the recognition model.
Request Body Example:
{
"captureTrigger": "barcode",
"labelTrigger": "barcode_scanner",
"category": "drinks",
"count": 1,
"image": "/9j/4AAQSkZJRgABAQAA........",
"imgSource": "ip-camera-SCO-1",
"label": "4011254",
"name": "Milk",
"price": 6.95,
}
Request Body Parameters
| Header | Explanation | Values (Explanation) |
|---|---|---|
| "sampleId" | Unique ID returned with each inference | Pass the value returned by Capture & Predict API |
| "captureTrigger" | Mechanism/flow which prompted the agent to capture an image | Pass the same value as Capture & Predict API |
| "labelTrigger" | Mechanism by which user selects/identifies the item they are purchasing | "EdgifyPrediction": (Edgify predictions shown on-screen for the customer to select) |
| "ManualLookup": (Customer searches the picklist / menus to find their item - AKA the normal process on non-AI enabled scales) | ||
| "HandScanner": (For SCO/Lane POS where an additional barcode scanner is employed) | ||
| "category" (optional) | Retailer catalog hierarchy | Will depend on the retailer, for example: "CitrusFruits", "Alcohol", "PowerTools", "ExoticVegetables", "Pets", "Clothing". |
| "groupId" (optional) | Enables future Edgify functionality | |
| "imgSource" (optional) | ID of the image capture device | Applicable for IP camera use only. Example: "IP-Cam-10-44-01" or "192.168.1.101". |
| "image" | The image captured by the agent from the camera feed, encoded in Base64 | |
| "label" | PLU or barcode for a given item | Example: "8547230239400", "4011", "4133". |
| "name" | The English / Human readable item name | Example: "DietCoke20oz", "BananaOrganic", "GalaApple". |
| "count" | Number of items being purchased | Barcoded items count is always "1". |
| "price" | Item cost per unit weight | Applicable only for weighted items, else do not pass this header. |
| "weight" | The weight of item being purchased | Applicable only for weighted items, else do not pass this header. |
| "totalPrice" | Product of "price" x "weight" | Barcoded item price should be passed here. |
Response Example
{
"matchStrength": "alert-non-match"
}
Response Body Parameters
| Header | Explanation | Values (Explanation) |
|---|---|---|
| "matchStrength" | Logic determining if the label received by Edgify in the Samples API matches the item Edgify sees | "match": (Label received matches item seen - AKA no loss event suspected) "alert-non-match": (Label received does not match item seen by Edgify - Possible loss event/false selection/barcode switching) "unknown": Edgify was unable to confidently match or identify a non-match |
PATCH samples
PATCH http://localhost:8090/api/v2/samples/{sample_id}
Description :
Used to add further metadata to a previous PUT samples call
Request Body Example:
{
"captureTrigger": "auto-scale",
"labelTrigger": "RecommendationStrip",
"category": "ExoticFruits",
"count": 0,
"groupId": "b932de54-41ca-4f5a-99d5-b9db779f8888",
"sampleId": "9c9847e6-591b-4f29-a988-922da9e56484",
"imgSource": "",
"label": "4011",
"name": "banana",
"price": 1.2,
"weight": 1.5,
"totalPrice": 1.8
}
Headers and Possible Values:
Any combination of the above headers can be passed with this call.
Response Example
No response generated
POST events
POST http://localhost:8090/api/v2/events
Description :
Passes information to the Edgify agent. We are continuously developing new use cases.
Request Body Example:
{
"name": "StartCustomerSession"
}
Headers and Possible Values:
| Header | Explanation | Values (Explanation) |
|---|---|---|
| "name" | Single field used to pass information | "StartCustomerSession": Triggered by the first interaction of a new customer and prompts the Edgify agent to begin recording video (for SCO/Lane Loss prevention use case only) |
| "StopCustomerSession": Bookends the "StartCustomerSession" call by telling the agent to stop recording video | ||
| "UpdateCustomerSession": allows updating session metadata after the session has started, with all changes forwarded to the backend | ||
| "StartInteraction": For barcodeless items - Triggered by the first user interaction with the manual lookup process. Used to measure duration of transaction/interaction without Edgify | ||
| "StartIntervention": Prevents false-positives by marking when store attendant begins assisting the user (SCO use case only) | ||
| "StopIntervention": Marks the end of attendant assistance | ||
| "non-match-continue": For use in false selection flows | ||
| "non-match-startover": For use in false selection flows |
Delete Sample
DELETE http://localhost:8090/api/v2/samples/{sample_id}
Description :
Deletes a sample
Request Body Example:
No body required
Webhook - Predict
The "Predict" webhook is triggered when a prediction occurs within the Edgify Agent (configurable via Webhooks:Enabled:TRUE device configuration setting).
To handle prediction webhooks, ensure your application is configured to serve the webhook endpoint and can accept the body as described below.
As part of the integration, ensure your application can:
- Accept requests at the relevant endpoint.
- Parse the incoming JSON payload.
- Validate the payload structure and data types.
- Store or process the relevant information as needed by your application.
- Respond with appropriate HTTP status codes.
- Log errors for troubleshooting
You can use tools like Postman to simulate webhook requests and test the endpoint.
POST http://localhost:3050/predict
Request body example: The webhook will send a JSON payload with the following structure:
{
"capturedAt": "2025-05-20T13:00:00.953Z",
"certain": false,
"duration": 87,
"id": "49b2f957-62f2-4b32-bdf3-8b54b4f395cb",
"image": "...",
"modelId": 56,
"predictedAt": "2025-05-22T08:25:21.761Z",
"predictions": [
{
"certainty": 0.8263,
"label": "84",
"name": "orange"
},
{
"certainty": 0.1078,
"label": "855"
}
],
"weight": "2.3"
}