Developers & AI Agents

Colombo Cosmetics API & Agent Documentation

Colombo Cosmetics provides a public, read-only REST API, OpenAPI 3.1 specifications, and Markdown content negotiation so AI shopping assistants, LLM function-calling tools, and developer integrations can query authentic beauty, skincare, and perfume inventory in Sri Lanka (LKR) in real time.

OpenAPI 3.1 (JSON)

/openapi.json — Complete schema with operationIds for LLM function calling.

OpenAPI 3.1 (YAML)

/api/openapi.yaml — YAML format specification for API gateways and SDKs.

Agent Instructions (llms.txt)

/llms.txt — When-to-use guidance, best-fit tasks, and catalog overview.

Authentication & Rate Limits

Public Read Endpoints (`/api/public/*`): No API key or authentication token is required. All public catalog, category, brand, bundle, and store-info endpoints are openly accessible over HTTPS with CORS enabled (`Access-Control-Allow-Origin: *`).

Order Tracking (`/api/public/track-order`): Protected by verification of both the numeric order_number and the customer's checkout phone number, rate-limited to 10 requests per 15 minutes per IP.

Administrative Endpoints (`/api/expire-stale-orders`): Requires an Authorization: Bearer <CRON_SECRET> header.

Markdown Content Negotiation (`Accept: text/markdown`)

Colombo Cosmetics supports HTTP content negotiation for AI agents on the homepage, storefront pages, documentation, and 404 responses. Send Accept: text/markdown to receive a clean, token-efficient Markdown representation with Content-Type: text/markdown; charset=utf-8 and Vary: Accept.

# Fetch homepage as Markdown for LLM agents
curl -sS -L -i -H "Accept: text/markdown" https://colombocosmetics.lk/

# Non-existent routes return HTTP 404 with a structured Markdown error guide
curl -sS -L -i -H "Accept: text/markdown" https://colombocosmetics.lk/non-existent-path

REST API Endpoints Reference

GET/api/public/products

operationId: listProducts

Search, filter, and paginate active beauty & fragrance products in LKR.

Parameters: q, category, subcategory, brand, minPrice, maxPrice, inStock, minRating, sort, page, pageSize

curl -sS "https://colombocosmetics.lk/api/public/products?q=serum&inStock=true&pageSize=5"

GET/api/public/products/{slug}

operationId: getProductBySlug

Fetch full product details, variants, stock count, gallery images, and shipping fees by slug.

Parameters: slug (path parameter)

curl -sS "https://colombocosmetics.lk/api/public/products/chemist-at-play-underarm-roll-on"

GET/api/public/categories

operationId: listCategories

Retrieve the hierarchical tree of categories and subcategories with active product counts.

Parameters: None

curl -sS "https://colombocosmetics.lk/api/public/categories"

GET/api/public/brands

operationId: listBrands

List all stocked cosmetics, skincare, and fragrance brands with product counts.

Parameters: None

curl -sS "https://colombocosmetics.lk/api/public/brands"

GET/api/public/bundles

operationId: listBundles

List curated multi-product value bundles (eligible for free standard delivery when ordered alone).

Parameters: None

curl -sS "https://colombocosmetics.lk/api/public/bundles"

GET/api/public/store-info

operationId: getStoreInfo

Retrieve store contact details, Sri Lanka shipping fee rules, payment methods, and return policy.

Parameters: None

curl -sS "https://colombocosmetics.lk/api/public/store-info"

GET/api/public/track-order

operationId: trackOrderStatus

Check live order status using the customer's numeric order_number and phone number.

Parameters: order_number (required), phone (required)

curl -sS "https://colombocosmetics.lk/api/public/track-order?order_number=1042&phone=0771234567"

Structured JSON Error Format

All API endpoints return machine-readable JSON errors (`Content-Type: application/json`) with an uppercase code, descriptive message, HTTP status, actionable resolution hint, and docs_url.

{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "No active product found matching slug 'unknown-item'.",
    "status": 404,
    "resolution": "Search available products via GET /api/public/products?q=<keyword> to discover valid product slugs.",
    "docs_url": "https://colombocosmetics.lk/docs",
    "details": {
      "slug": "unknown-item"
    }
  }
}

Browse Shop Catalog·About Colombo Cosmetics·Contact Support·OpenAPI Spec (JSON)