API Documentation

Retailab APIDocumentation

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

Quick Navigation
Getting StartedAuthenticationEndpoints
POST /jobsGET /jobsGET /jobs/{id}/stateGET /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:

  1. Sign in to your Retailab account
  2. Navigate to the Dashboard
  3. Click "Create New Key" in the API Keys section
  4. Configure your key with appropriate permissions (read, write, auto_labeling)
  5. 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"
  }
}
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 KeyTry the Demo