Developer docs

BarCloud API Reference

REST API for BarCloud's catalog of 4 million+ products — lookup barcodes, fetch images, suggest edits, and contribute missing products.

Introduction

The BarCloud API is a REST HTTP API for barcode product data. All catalog routes live under the /cdb prefix and require your apiKey as a query parameter.

Send GET requests to read catalog data, or POST requests to submit edit suggestions or contribute products that are not yet in the database. JSON responses use a standard envelope; the image endpoint returns raw image bytes.

What is Central Database (CDB)?

CDB is BarCloud's product catalog with over 4 million barcode-linked records — name, category, brand, description, and images — powering lookup, recent products, and community-driven updates.

•Search over 4 million products by barcode (UPC/EAN, 8–14 digits)
•Fetch product images and recently added items
•Suggest edits to existing catalog entries
•Contribute new products when a barcode is not found

Base URL

Prepend this host to every endpoint path.

base url

https://api.barcloud.ph

Authentication

Pass your api key on every request as the apiKey query parameter.

query param

?apiKey=YOUR_API_KEY

Responses

JSON endpoints wrap payloads in a standard envelope.

response

{
  "status": 200,
  "message": "Success",
  "data": { ... }
}

status — HTTP-style status code
message — response message
data — payload or null on error
errors — error messages object

Endpoints

All catalog routes live under the /cdb prefix.

Method	Path	Description
GET	/cdb/recent	Recent added products
GET	/cdb/{barcode}	Lookup by barcode
GET	/cdb/image/{cdbId}	Product image
POST	/cdb/{barcode}/suggest-edit	Suggest product edit
POST	/cdb/not-found/contribute	Contribute not-found product

GET/cdb/recent

Recent added products

Returns the most recently added products. Useful for dashboards and homepage widgets.

Parameters

Name	In	Required	Description
apiKey	query	Yes	Your BarCloud serial key. e.g. 62054561xxxxxxxxx

Request

curl

curl -X GET "https://api.barcloud.ph/cdb/recent?apiKey=YOUR_API_KEY" \
  -H "Accept: application/json"

https://api.barcloud.ph/cdb/recent?apiKey=YOUR_API_KEY

Response (json)

application/json

{
  "status": 200,
  "message": "Success",
  "data": [
    {
      "id": "clx123abc",
      "barcode": "00815741",
      "name": "Example Product",
      "category": "Food > Snacks",
      "brand": "Example Brand",
      "createdAt": "2026-07-11T04:00:00.000Z"
    }
  ]
}

GET/cdb/{barcode}

Lookup by barcode

Fetch full product details for a barcode (8–14 digits). Returns 404 when no product is found.

Parameters

Name	In	Required	Description
barcode	path	Yes	Numeric barcode (UPC/EAN). e.g. 00815741
apiKey	query	Yes	Your BarCloud serial key. e.g. 62054561xxxxxxxxx

Request

curl

curl -X GET "https://api.barcloud.ph/cdb/00815741?apiKey=YOUR_API_KEY" \
  -H "Accept: application/json"

https://api.barcloud.ph/cdb/{barcode}?apiKey=YOUR_API_KEY

Response (json)

application/json

{
  "status": 200,
  "message": "Success",
  "data": {
    "id": "clx123abc",
    "barcode": "00815741",
    "name": "Example Product",
    "description": "Product description text.",
    "category": "Food > Snacks",
    "brand": "Example Brand",
    "meta": null,
    "createdAt": "2026-07-11T04:00:00.000Z",
    "updatedAt": "2026-07-11T04:00:00.000Z"
  }
}

GET/cdb/image/{cdbId}

Product image

Streams the product image as binary (JPEG, PNG, or WebP). Use the product id from lookup or recent responses.

Parameters

Name	In	Required	Description
cdbId	path	Yes	Product id (cdb record id). e.g. clx123abc
apiKey	query	Yes	Your BarCloud serial key. e.g. 62054561xxxxxxxxx

Request

curl

curl -X GET "https://api.barcloud.ph/cdb/image/clx123abc?apiKey=YOUR_API_KEY" \
  -H "Accept: application/json"

https://api.barcloud.ph/cdb/image/{cdbId}?apiKey=YOUR_API_KEY

Response (binary)

binary

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Disposition: inline; filename="clx123abc.jpg"

<binary image data>

POST/cdb/{barcode}/suggest-edit

Suggest product edit

Submit corrected product details for an existing catalog item. Creates a review record with PENDING status. Each API key may submit up to 2 pending suggestions per product.

Parameters

Name	In	Required	Description
barcode	path	Yes	Numeric barcode (UPC/EAN) of the existing product. e.g. 7676400001573
apiKey	query	Yes	Your BarCloud serial key. e.g. 6205456173246802
name	body	Yes	Suggested product name. e.g. MARLBORO MERAH SLOF 20*S
category	body	No	Suggested product category. e.g. Cigarette
brand	body	No	Suggested brand name. e.g. MARLBORO

Request body

application/json

{
    "name": "MARLBORO MERAH SLOF 20*S",
    "category": "Cigarette",
    "brand": "MARLBORO"
}

Request

curl

curl --location 'https://api.barcloud.ph/cdb/7676400001573/suggest-edit?apiKey=YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "name": "MARLBORO MERAH SLOF 20*S",
    "category": "Cigarette",
    "brand": "MARLBORO"
}'

https://api.barcloud.ph/cdb/{barcode}/suggest-edit?apiKey=YOUR_API_KEY

Response (json)

application/json

{
  "status": 200,
  "message": "Suggestion submitted successfully",
  "data": null,
}

Error responses

400 max suggestions

{
  "status": 400,
  "message": "Maximum suggestions reached",
  "data": null
}

POST/cdb/not-found/contribute

Contribute not-found product

Submit product details when a barcode lookup returns no match. Creates a review record with PENDING status. Trusted API keys may be auto-approved.

Parameters

Name	In	Required	Description
apiKey	query	Yes	Your BarCloud serial key. e.g. 62054561xxxxxxxxx
barcode	body	Yes	Numeric barcode (UPC/EAN) that was not found in the catalog. e.g. 7676400001573
name	body	Yes	Product name as shown on the package. e.g. MARLBORO MERAH SLOF 20*S
category	body	No	Product category. e.g. Cigarette
brand	body	No	Brand name. e.g. MARLBORO

Request body

application/json

{
    "barcode": "7676400001573",
    "name": "MARLBORO MERAH SLOF 20*S ",
    "category": "Cigarette",
    "brand": "MARLBORO"
}

Request

curl

curl --location 'https://api.barcloud.ph/cdb/not-found/contribute?apiKey=YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "barcode": "7676400001573",
    "name": "MARLBORO MERAH SLOF 20*S ",
    "category": "Cigarette",
    "brand": "MARLBORO"
}'

https://api.barcloud.ph/cdb/not-found/contribute?apiKey=YOUR_API_KEY

Response (json)

application/json

{
  "status": 200,
  "message": "Contributed successfully",
  "data": null,
}

Error responses

422 validation

{
  "status": 422,
  "message": "Validation failed",
  "data": null,
  "errors": {
    "barcode": "\"barcode\" is not allowed to be empty"
  }
}

400 max reviews

{
  "status": 400,
  "message": "Maximum reviews reached",
  "data": null
}

409 product already exists

{
  "status": 409,
  "message": "Product already exists in the master list",
  "data": null
}

Errors

Errors use the same JSON envelope with data: null.

error example

{
  "status": 401,
  "message": "API key is required",
  "data": null
}

Code	Meaning
400	Bad request (e.g. maximum reviews reached)
401	Missing or invalid API key
404	Product or image not found
409	Product already exists
422	Validation failed
500	Server error