Products API

List and search agricultural products and commodities

List Products

GET/api/v1/productsPublic Key

Get a paginated list of all available products

Query Parameters

Parameters

pageintegerdefault: 1

Page number for pagination

page_sizeintegerdefault: 20

Items per page (max: 100)

categorystring

Filter by product category

searchstring

Search products by name or description

Example Request

Request

curl -X GET "https://api.shambarecords.com/api/v1/products?category=Cereals&page=1" \
  -H "X-API-Key: sr_pub_your_public_key"

Response

{
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Maize",
      "category": "Cereals",
      "sub_category": "Grains",
      "description": "White and yellow maize grain",
      "common_units": ["90kg bag", "50kg bag", "2kg tin"],
      "is_active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    },
    {
      "uuid": "661f9511-f39c-52e5-b827-557766551111",
      "name": "Wheat",
      "category": "Cereals",
      "sub_category": "Grains",
      "description": "Hard and soft wheat varieties",
      "common_units": ["90kg bag", "50kg bag"],
      "is_active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 20,
    "total": 45,
    "total_pages": 3
  }
}

Get Product by UUID

GET/api/v1/products/:uuidPublic Key

Retrieve detailed information about a specific product

Path Parameters

Parameters

uuidstring (UUID)required

The unique identifier of the product

Example Request

Request

curl -X GET "https://api.shambarecords.com/api/v1/products/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: sr_pub_your_public_key"

Response

{
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Maize",
    "category": "Cereals",
    "sub_category": "Grains",
    "description": "White and yellow maize grain, primary cereal crop in Kenya",
    "common_units": ["90kg bag", "50kg bag", "2kg tin"],
    "alternative_names": ["Corn", "Mahindi"],
    "season": "Short rains (Oct-Dec), Long rains (Mar-May)",
    "storage_requirements": "Cool, dry place. Moisture content below 13%",
    "is_active": true,
    "metadata": {
      "scientific_name": "Zea mays",
      "varieties": ["H614", "H516", "DH04", "DH06"],
      "maturity_period": "90-120 days"
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

Search Products

POST/api/v1/products/searchPublic Key

Advanced product search with multiple filters

Request Body

Parameters

querystring

Search term to match against name and description

categoriesarray of strings

Filter by multiple categories

sub_categoriesarray of strings

Filter by sub-categories

is_activebooleandefault: true

Filter by active status

Example Request

Request

curl -X POST "https://api.shambarecords.com/api/v1/products/search" \
  -H "X-API-Key: sr_pub_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "bean",
    "categories": ["Legumes"],
    "is_active": true
  }'

Response

{
  "data": [
    {
      "uuid": "772f9522-f39c-52e5-b827-557766552222",
      "name": "Beans (Red)",
      "category": "Legumes",
      "sub_category": "Pulses",
      "description": "Red kidney beans and mwezi moja varieties",
      "common_units": ["90kg bag", "2kg packet"],
      "is_active": true
    },
    {
      "uuid": "883f9533-f39c-52e5-b827-557766553333",
      "name": "Beans (White)",
      "category": "Legumes",
      "sub_category": "Pulses",
      "description": "White haricot beans",
      "common_units": ["90kg bag", "2kg packet"],
      "is_active": true
    }
  ],
  "meta": {
    "total": 2
  }
}

Get Product Categories

GET/api/v1/products/categoriesPublic Key

Get a list of all product categories with counts

Example Request

Request

curl -X GET "https://api.shambarecords.com/api/v1/products/categories" \
  -H "X-API-Key: sr_pub_your_public_key"

Response

{
  "data": [
    {
      "name": "Cereals",
      "product_count": 8,
      "sub_categories": [
        { "name": "Grains", "product_count": 5 },
        { "name": "Flour", "product_count": 3 }
      ]
    },
    {
      "name": "Legumes",
      "product_count": 12,
      "sub_categories": [
        { "name": "Pulses", "product_count": 8 },
        { "name": "Oil Seeds", "product_count": 4 }
      ]
    },
    {
      "name": "Vegetables",
      "product_count": 25,
      "sub_categories": [
        { "name": "Leafy Greens", "product_count": 10 },
        { "name": "Root Vegetables", "product_count": 8 },
        { "name": "Other Vegetables", "product_count": 7 }
      ]
    }
  ]
}

Product Object Schema

Response Schema

uuidstring (UUID)

Unique identifier for the product

namestring

Product name

categorystring

Primary category (e.g., Cereals, Legumes, Vegetables)

sub_categorystringnullable

Sub-category classification

descriptionstring

Detailed product description

common_unitsarray of strings

Common units of measurement for this product

alternative_namesarray of stringsnullable

Alternative names and local language names

seasonstringnullable

Growing/harvest season information

storage_requirementsstringnullable

Storage and handling requirements

is_activeboolean

Whether the product is currently tracked

metadataobjectnullable

Additional product metadata (varieties, scientific names, etc.)

created_atstring (ISO 8601)

Timestamp when the product was added

updated_atstring (ISO 8601)

Timestamp when the product was last updated