API Documentation

Retailab APIDocumentation

Integrate our AI-powered product detection into your applications with our RESTful API.

Quick Navigation

Getting Started Authentication Endpoints

POST /jobs GET /jobs GET /jobs/{id}/state GET /jobs/{id}

Getting Started

Quick start guide to using the Retailab API

Base URL

http://localhost:8080/protected-api

All API requests should be made to this base URL.

Quick Example

Here's a simple example of creating a job to detect products in an image:

curl -X POST http://localhost:8080/protected-api/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "image=@/path/to/image.jpg" \
  -F 'all_skus=[{"code":"coca_cola_classic_500ml","name":"Coca-Cola Classic 500ml","description":"Red can with white logo"}]'

Authentication

How to authenticate your API requests

Getting Your API Key

To use the Retailab API, you need an API key. You can create and manage your API keys from the dashboard.

Steps to Get Your API Key:

Sign in to your Retailab account
Navigate to the Dashboard
Click "Create New Key" in the API Keys section
Configure your key with appropriate permissions (read, write, auto_labeling)
Copy your API key immediately - it's only shown once!

Go to Dashboard

Using Your API Key

Include your API key in every request using one of these methods:

Include your API key in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Security Best Practices

• Never expose your API keys in client-side code or public repositories
• Use environment variables to store your keys securely
• Rotate your keys periodically and revoke unused ones

API Endpoints

Complete reference for all available endpoints

POST/jobsCreate Job

Create a new auto-labeling job to detect products in an uploaded image. The job will be processed asynchronously.

Request

Content-Type: multipart/form-data

Form Fields:

image (required) - Image file (JPG, PNG, WEBP)
all_skus (required) - JSON string array of SKU objects

SKU Object Format

{
  "code": "coca_cola_classic_500ml",
  "name": "Coca-Cola Classic 500ml Aluminum Can",
  "description": "Bright red background (#DC143C), white Spencerian script logo..."
}

Example Request

curl -X POST http://localhost:8080/protected-api/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "image=@/path/to/image.jpg" \
  -F 'all_skus=[{"code":"coca_cola_classic_500ml","name":"Coca-Cola Classic 500ml","description":"Red can with white logo"}]'

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Job created successfully",
  "status": "pending"
}

GET/jobsList Jobs

Retrieve a list of all your auto-labeling jobs. Returns jobs ordered by creation date (newest first).

Example Request

curl -X GET http://localhost:8080/protected-api/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1,
      "job_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "user_email": "user@example.com",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:45Z",
      "completed_at": "2024-01-15T10:30:45Z",
      "used_ai_input_tokens": 1500,
      "used_ai_output_tokens": 800,
      "used_tokens": 50000,
      "error_message": null
    }
  ]
}

GET/jobs/{id}/stateGet Job State

Check the current state of a job. Useful for polling to know when a job has completed.

Path Parameters

id (required) - The job ID returned from creating a job

Example Request

curl -X GET http://localhost:8080/protected-api/jobs/550e8400-e29b-41d4-a716-446655440000/state \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "data": "completed"
}

Possible values: pending, processing, completed, failed

GET/jobs/{id}Get Job Result

Retrieve the complete results of a completed job, including detection images and job metadata.

This endpoint only returns results for completed jobs. Check the job state first to ensure it's completed.

Example Request

curl -X GET http://localhost:8080/protected-api/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "data": {
    "job": {
      "id": 1,
      "job_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "user_email": "user@example.com",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:45Z",
      "completed_at": "2024-01-15T10:30:45Z",
      "used_ai_input_tokens": 1500,
      "used_ai_output_tokens": 800,
      "used_tokens": 50000,
      "error_message": null
    },
    "result_image": "https://example.com/results/result_image.jpg",
    "detections_image": "https://example.com/results/detections_image.jpg"
  }
}

ML Model Performance

Live accuracy metrics from our latest model evaluation on 7,360 test images — trained on real Colombian retail shelves.

Brand Accuracy

96.92%

Macro F1: 94.50%

Sub-Brand Accuracy

94.61%

Macro F1: 93.67%

Avg. Confidence

95.51%

On correct predictions: 96.73%

Classes Supported

189 brands

+ 358 sub-brand classes

Brand	F1-Score	Precision	Recall	Confidence ✓	Support
Aguardiente Amarillo	100.00%	100.00%	100.00%	99.70%	1
Aguila Roja	100.00%	100.00%	100.00%	99.87%	1
Ariel	100.00%	100.00%	100.00%	98.31%	84
Baby Dove	100.00%	100.00%	100.00%	99.70%	50
Bacardi	100.00%	100.00%	100.00%	95.98%	16
Bonfiest	100.00%	100.00%	100.00%	89.52%	1
Cheese Tris	100.00%	100.00%	100.00%	99.79%	8
Cheetos	100.00%	100.00%	100.00%	98.54%	22
Choclitos	100.00%	100.00%	100.00%	99.77%	15
Choco Listo	100.00%	100.00%	100.00%	94.66%	10
Chocorramo	100.00%	100.00%	100.00%	99.10%	9
Chokis	100.00%	100.00%	100.00%	99.84%	5
Clorox	100.00%	100.00%	100.00%	98.01%	22
Doritos	100.00%	100.00%	100.00%	98.99%	28
Ego	100.00%	100.00%	100.00%	98.09%	10
Familia	100.00%	100.00%	100.00%	97.10%	12
Fassi	100.00%	100.00%	100.00%	96.41%	17
Flips	100.00%	100.00%	100.00%	99.66%	11
Gala	100.00%	100.00%	100.00%	99.99%	6
Gol	100.00%	100.00%	100.00%	97.99%	10
Hills	100.00%	100.00%	100.00%	97.42%	9
Huggies	100.00%	100.00%	100.00%	95.14%	31
Intibon	100.00%	100.00%	100.00%	87.04%	4
Jgb Alcohol	100.00%	100.00%	100.00%	99.10%	7
Kelloggs	100.00%	100.00%	100.00%	97.25%	5
Kotex	100.00%	100.00%	100.00%	99.35%	12
Ladysoft	100.00%	100.00%	100.00%	98.59%	19
Loreal	100.00%	100.00%	100.00%	92.19%	11
Los Cuates	100.00%	100.00%	100.00%	95.33%	7
Mani Moto	100.00%	100.00%	100.00%	97.90%	12
Max	100.00%	100.00%	100.00%	96.37%	25
Mexsana	100.00%	100.00%	100.00%	99.47%	51
Mr Tea	100.00%	100.00%	100.00%	89.59%	4
Natuchips	100.00%	100.00%	100.00%	97.10%	12
Old Spice	100.00%	100.00%	100.00%	99.42%	34
Olmeca	100.00%	100.00%	100.00%	89.64%	5
Palette	100.00%	100.00%	100.00%	98.68%	23
Raid	100.00%	100.00%	100.00%	95.25%	14
Recamier	100.00%	100.00%	100.00%	99.54%	14
Sanson	100.00%	100.00%	100.00%	99.24%	7
Seven Up	100.00%	100.00%	100.00%	94.05%	4
Sprite	100.00%	100.00%	100.00%	99.03%	21
Stay Free	100.00%	100.00%	100.00%	97.63%	6
Suavitel	100.00%	100.00%	100.00%	97.41%	10
Super Ricas	100.00%	100.00%	100.00%	94.27%	51
Tostacos	100.00%	100.00%	100.00%	99.62%	14
Trolli	100.00%	100.00%	100.00%	99.58%	7
Valle	100.00%	100.00%	100.00%	97.84%	35
Todorico	99.32%	100.00%	98.65%	98.85%	74
Super Blank	99.27%	100.00%	98.55%	98.25%	69
Bebex	99.22%	98.46%	100.00%	99.83%	64
De Todito	99.21%	98.44%	100.00%	98.90%	63
Cristalino	99.20%	100.00%	98.41%	96.83%	63
Arrurru	99.16%	98.33%	100.00%	96.97%	59
Dogourmet	99.05%	99.57%	98.53%	96.06%	475
Margarita	99.05%	100.00%	98.11%	98.91%	106
Nosotras	98.99%	98.99%	98.99%	99.23%	99
Cat Chow	98.92%	100.00%	97.87%	97.71%	235
Pequenin	98.89%	100.00%	97.80%	98.13%	91
Bbc	98.82%	97.67%	100.00%	98.08%	42
Carefree	98.82%	97.67%	100.00%	97.85%	42
Axion	98.73%	100.00%	97.50%	95.80%	80
Mi Dia	98.72%	98.72%	98.72%	97.38%	78
Head Shoulders	98.71%	99.48%	97.96%	96.23%	196
Igora	98.70%	100.00%	97.44%	99.57%	39
Ponds	98.70%	97.44%	100.00%	96.58%	38
Protex	98.62%	100.00%	97.28%	97.07%	147
Schick	98.55%	97.14%	100.00%	93.91%	34
Lady Speed Stick	98.38%	100.00%	96.81%	96.39%	94
Postobon	98.36%	96.77%	100.00%	95.68%	30
Winny	98.36%	98.36%	98.36%	97.70%	183
Aromax	98.31%	96.67%	100.00%	99.63%	29
Nescafe	98.31%	100.00%	96.67%	99.94%	30
Quatro	98.31%	96.67%	100.00%	96.72%	29
Babysec	98.18%	96.43%	100.00%	99.83%	27
Fortident	98.18%	97.59%	98.78%	97.59%	82
Oralb	98.16%	98.77%	97.56%	97.75%	82
Balance	98.15%	99.07%	97.25%	97.28%	109
Dorado	98.04%	96.15%	100.00%	99.40%	25
Fluocardent	97.96%	96.00%	100.00%	96.50%	96
Hit	97.92%	97.92%	97.92%	97.99%	48
Johnsons	97.92%	99.40%	96.49%	92.29%	171
Rexona	97.92%	98.60%	97.24%	97.27%	145
Listerine	97.83%	97.83%	97.83%	98.54%	92
Savital	97.79%	99.25%	96.38%	97.25%	138
Agility Gold	97.78%	97.78%	97.78%	99.69%	45
Speed Max	97.67%	95.45%	100.00%	99.50%	21
Pantene	97.52%	96.72%	98.33%	97.73%	120
Nutriss	97.51%	97.16%	97.86%	97.88%	140
Carey	97.37%	97.37%	97.37%	98.61%	76
Pepsi	97.37%	94.87%	100.00%	98.93%	37
Nutribela	97.26%	97.93%	96.60%	96.19%	147
Brisa	97.06%	97.06%	97.06%	98.50%	34
Soka	97.06%	97.06%	97.06%	98.09%	34
Colgate	96.80%	99.07%	94.64%	95.65%	336
Jumbo	96.77%	95.74%	97.83%	98.47%	46
Gillette	96.73%	97.37%	96.10%	92.99%	77
Grisly	96.55%	93.33%	100.00%	95.14%	14
Nectar	96.55%	100.00%	93.33%	98.37%	15
Cocosette	96.43%	93.10%	100.00%	97.38%	27
Cristal	96.36%	98.15%	94.64%	91.96%	56
Nucita	96.30%	92.86%	100.00%	97.92%	13
Vive 100	96.30%	92.86%	100.00%	99.50%	13
Lak	96.24%	94.12%	98.46%	96.40%	65
Colombiana	96.10%	100.00%	92.50%	95.21%	40
Coca Cola	96.04%	95.10%	97.00%	92.46%	100
Aguardiente Antioqueno	96.00%	94.74%	97.30%	96.44%	74
Ritz	96.00%	92.31%	100.00%	97.72%	12
Axe	95.89%	92.11%	100.00%	96.79%	35
Sedal	95.89%	98.13%	93.75%	97.06%	112
Blancox	95.71%	96.30%	95.12%	94.78%	82
Electrolit	95.65%	95.65%	95.65%	99.93%	23
Speed Stick	95.65%	91.67%	100.00%	97.61%	11
Aromatel	95.30%	95.95%	94.67%	96.19%	75
Dove	95.24%	90.91%	100.00%	95.58%	50
Excellent	95.24%	90.91%	100.00%	97.38%	10
Tio Nacho	95.24%	92.59%	98.04%	97.43%	51
Pony Malta	94.87%	94.87%	94.87%	94.29%	39
Equilibrio	94.74%	90.00%	100.00%	99.77%	9
Festival	94.74%	90.00%	100.00%	99.24%	9
Gato Negro	94.74%	94.74%	94.74%	99.01%	19
Natumalta	94.74%	90.00%	100.00%	87.21%	9
Pulp	94.74%	90.00%	100.00%	97.19%	9
Nutre Can	94.44%	89.47%	100.00%	96.16%	17
Ron Santafe	94.44%	94.44%	94.44%	95.01%	18
Sol	94.44%	94.44%	94.44%	99.40%	18
Pilsen	94.34%	96.15%	92.59%	96.80%	27
Aguila	94.12%	94.12%	94.12%	95.65%	17
Chi Ricos	94.12%	88.89%	100.00%	91.53%	8
Cifrut	94.12%	94.12%	94.12%	95.08%	17
Ellas	94.12%	94.12%	94.12%	97.21%	17
Gatorlit	94.12%	88.89%	100.00%	97.80%	8
Lubriderm	94.12%	94.12%	94.12%	97.09%	17
Andina	93.65%	95.16%	92.19%	98.79%	64
Coco	93.33%	87.50%	100.00%	99.64%	7
Fab	93.33%	87.50%	100.00%	90.81%	7
Minichips	93.33%	87.50%	100.00%	99.87%	7
Suntea	93.33%	100.00%	87.50%	99.84%	8
Yodora	92.90%	92.39%	93.41%	91.68%	91
Aguardiente Nectar	92.31%	85.71%	100.00%	97.29%	6
Saviloe	92.31%	100.00%	85.71%	99.58%	7
Top	91.89%	100.00%	85.00%	97.04%	20
Azul Clean	91.80%	93.33%	90.32%	98.95%	31
Chivas Regal	90.91%	90.91%	90.91%	82.96%	11
Gatorade	90.91%	83.33%	100.00%	97.01%	10
Nivea	90.91%	86.96%	95.24%	96.94%	21
Sanpic	90.91%	83.33%	100.00%	85.72%	10
Tanga	90.91%	83.33%	100.00%	99.01%	5
H2o	90.32%	87.50%	93.33%	96.51%	15
Black And White	90.00%	81.82%	100.00%	97.69%	9
Ron Viejo De Caldas	90.00%	85.71%	94.74%	97.15%	38
Venus	90.00%	100.00%	81.82%	99.39%	11
Elite	89.66%	81.25%	100.00%	99.52%	13
Maizitos	89.66%	81.25%	100.00%	97.63%	13
Jack Daniels	89.47%	89.47%	89.47%	95.68%	19
Big Cola	89.23%	93.55%	85.29%	87.75%	68
Hatsu	89.09%	89.09%	89.09%	92.23%	55
Baileys	88.89%	88.89%	88.89%	91.77%	9
Corona	88.89%	100.00%	80.00%	92.67%	5
Dampy	88.89%	100.00%	80.00%	96.32%	5
Yupi	88.89%	100.00%	80.00%	98.38%	5
Something Special	88.00%	91.67%	84.62%	99.27%	13
Sporade	88.00%	78.57%	100.00%	98.32%	11
Angela	87.50%	87.50%	87.50%	97.03%	8
Buen Dia	87.50%	93.33%	82.35%	96.83%	17
Crema N4	87.50%	100.00%	77.78%	97.37%	9
Deseo	85.71%	75.00%	100.00%	83.84%	9
Fabuloso	85.71%	75.00%	100.00%	73.59%	6
Kola Roman	85.71%	75.00%	100.00%	88.97%	9
Vanish	85.71%	100.00%	75.00%	90.53%	8
Lozocrem	84.85%	82.35%	87.50%	94.72%	16
Tecate	84.85%	73.68%	100.00%	97.05%	14
Deo Pies	83.33%	71.43%	100.00%	94.60%	5
Dersa	83.33%	83.33%	83.33%	98.17%	6
Royal Canin	82.35%	77.78%	87.50%	99.88%	8
Ron Medellin	81.82%	90.00%	75.00%	95.99%	24
Carinoso	80.00%	66.67%	100.00%	99.72%	4
Grants	80.00%	100.00%	66.67%	97.92%	6
Jose Cuervo	80.00%	100.00%	66.67%	99.63%	6
Lava	80.00%	100.00%	66.67%	99.98%	6
Lite	80.00%	100.00%	66.67%	98.71%	6
Cielo	78.26%	64.29%	100.00%	98.97%	9
Br For Dog	76.92%	71.43%	83.33%	99.87%	6
Cicatricure	75.00%	60.00%	100.00%	97.96%	6
Trululu	75.00%	100.00%	60.00%	98.59%	10
Asepxia	73.68%	63.64%	87.50%	96.86%	8
Mk	72.73%	80.00%	66.67%	79.22%	6
La Joya	70.59%	60.00%	85.71%	94.68%	7
Club Colombia	66.67%	100.00%	50.00%	97.35%	2

Showing 189 of 189 brands · sorted by F1-Score

How to Read These Results

Metric Definitions

• F1-Score: Harmonic mean of precision & recall — the primary quality signal
• Precision: Of all predictions, what fraction was correct
• Recall: Of all true instances, what fraction was found
• Confidence ✓: Avg. model confidence when the prediction was correct
• Support: Number of real instances in the test set

Color Legend

≥ 95%Excellent — production-ready

≥ 85%Good — reliable for most use cases

≥ 75%Acceptable — limited training data

< 75%Low — rare class or visual ambiguity

Error Handling

Understanding API error responses

The API uses standard HTTP status codes to indicate success or failure. Error responses include a message describing what went wrong.

400 Bad Request

Invalid request parameters or missing required fields.

401 Unauthorized

Invalid or missing API key.

403 Forbidden

API key doesn't have required permissions.

404 Not Found

Job ID not found or doesn't belong to you.

Ready to get started?

Create your API key and start integrating product detection into your applications.

Get API Key Try the Demo