Developer Portal

Interactive API Reference & Live Test Suite

Explore all available endpoints in the Product Data API. Use the live Try It Out button on any endpoint to execute requests directly against the local server.

Filter View by Role:

0. Developer & User Authentication

GET /v1/auth/registration-status

Check if public new user registrations are currently open or disabled by the system administrator.

POST /v1/auth/register & /v1/auth/signup

Register a new developer user account and auto-issue an initial API key with $10.00 USD trial balance. Returns 403 Forbidden if public registration is disabled by system administrator.

Example Request Body:
{
  "full_name": "Jane Developer",
  "email": "jane@techcorp.lk",
  "password": "Password123!",
  "company_name": "TechCorp Solutions",
  "country_code": "LK"
}
Example Response (201 Created):
{
  "message": "User registration successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "usr_9f8e7d6c5b4a3a21",
    "email": "jane@techcorp.lk",
    "fullName": "Jane Developer",
    "companyName": "TechCorp Solutions",
    "countryCode": "LK",
    "status": "active"
  },
  "apiKeyInfo": {
    "apiKey": "pk_live_47b28a91c3d4e5f6...",
    "scope": "read"
  }
}
POST /v1/auth/login

Authenticate an existing developer account and receive a JWT bearer token.

GET /v1/auth/me

Get profile details for the current authenticated user session (requires Bearer JWT in Authorization header).

1. Public Product Catalog & Country Hierarchy

GET /v1/products

Lookup products by barcode, or search by text within a mandatory category prefix. Supports ln language selection and returns full category_hierarchy path.

Query Parameters:
Parameter Type Required Description
barcode string Optional* EAN/UPC barcode. Required if no category_code supplied.
category_code string Optional* 3-letter category prefix e.g. CHI, BEV, GRO. Required if no barcode.
search string Optional Full-text search filter on product name or description within category.
ln string Optional Language code: EN (default), SI (Sinhala), TA (Tamil).
country_code string Optional ISO 2-letter country code to filter regional catalog e.g. LK.
exclude_images boolean Optional Set true to omit image URLs from response (faster payload).
Live Test — Query Parameters:
Example Response (200 OK) 
{
  "status": "success",
  "pagination": { "total": 1 },
  "data": [{
    "uuid": "6e652b6c-0f88-4a38-9614-4a070625275b",
    "product_code": "LK-CHI-000001",
    "barcode": "4791066002119",
    "name": "Elephant House Toffee Caramel Ice Cream 1L",
    "description": "Delicious caramel ice cream 1 litre tub.",
    "brand_name": "Elephant House",
    "category_prefix": "CHI",
    "country_code": "LK",
    "ln": "EN",
    "unit": "l",
    "unit_value": 1,
    "status": "active",
    "category_hierarchy": {
      "path_names": ["Supermarket & Grocery", "Dairy, Chilled & Eggs", "Ice Cream & Desserts"],
      "full_path": "Supermarket & Grocery > Dairy, Chilled & Eggs > Ice Cream & Desserts"
    },
    "images": [{ "url": "https://cdn.example.com/products/ice-cream.jpg", "is_primary": true }],
    "available_languages": ["en", "si"]
  }]
}
GET /v1/products/:uuid_or_barcode

Fetch full detailed metadata for a single product by its UUID or Barcode string.

Live Test — Lookup by barcode 4791066002119:
POST /v1/products

Directly index a new master product into the public catalog. Restricted to authorized vendors, developers, or system administrators.

Example Request Body:
{
  "barcode": "4791066888888",
  "name": "Elephant House Wonder Bar Ice Cream 80ml",
  "description": "Vanilla coated chocolate ice cream bar",
  "category_code": "CHI",
  "brand": "Elephant House",
  "country_code": "LK",
  "unit_quantity": 80,
  "unit": "ml"
}
Example Response (201 Created):
{
  "uuid": "b64accf0-7162-430f-bcc8-3acdca9734cb",
  "product_code": "LK-CHI-000002"
}
GET /v1/categories

Lists all master category prefixes and classification codes.

GET /v1/countries

Lists all countries available in the catalog database, including Universal (UN) worldwide products.

GET /v1/countries/LK/categories

Polls categories containing products available for a specific country (combining local LK products + UN universal products).

GET /v1/countries/:country_code/categories/:category_code/products

Category product discovery listing. Returns clean public representation (barcodes strictly omitted). Supports pagination.

Query Parameters:
Parameter Type Default Description
page integer 1 Page number (1-indexed).
limit integer 20 Items per page (max 100).
exclude_images boolean false Set true to omit image URLs (faster payload).
Live Test — LK Beverages, Page 1, Limit 5:
Example Response (200 OK) 
{
  "country_code": "LK",
  "category_code": "BEV",
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 2,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  },
  "data": [{
    "uuid": "49eca906-31ab-43f3-9048-46a685131aae",
    "product_code": "LK-BEV-000001",
    "name": "Nestomalt Malted Food Drink 180ml",
    "description": "Malted food drink for daily energy.",
    "unit_quantity": 180,
    "unit": "ml",
    "brand": "Nestle",
    "country_code": "LK",
    "is_universal": false,
    "available_languages": ["en"],
    "images": []
  }]
}

2. Vendor & Manufacturer Gateway

GET /v1/vendor/profile

Fetch default submission profile (company name, region, default category) for form auto-fill.

PUT /v1/vendor/profile

Update vendor default submission settings.

POST /v1/vendor/submissions

Submits manufactured products (books, beverages, electronics) for admin review and catalog indexing.

GET /v1/vendor/submissions

View submission status history for the authenticated vendor user.