API Reference

Products

Product catalog operations

Search products

GET
/v2/products

Query Parameters

q?string
limit?number
Default20
Range1 <= value <= 100
cursor?string

Cursor for pagination (from nextCursor)

sort?string

Sort field, prefix with - for descending

Default"name"
category_id?string
brand_id?string
product_type_id?string
product_group_id?string
min_price?|
max_price?|
model_number?string

Exact model number search

include_legacy?|

Include data_tier 3-4 products

Defaultfalse
data_tier?string

Comma-separated tier filter, e.g. 1,2

include_offers?|

Include retailer offers/pricing for each product

include_signals?|

Include price/lifecycle signals for each product

format?string

Response format: json (full), schemaorg (structured data), ai (token-efficient for agents)

Default"json"
Value in"json" | "schemaorg" | "ai"
group_variants?|

Deduplicate by product group, showing one per group with _variant_count

Response Body

application/json

application/json

curl -X GET "https://api.covala.com/v2/products"
{
  "success": true,
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "slug": "string",
      "description": "string",
      "gtin": "string",
      "mpn": "string",
      "model_number": "string",
      "current_best_price": 0,
      "min_price": 0,
      "max_price": 0,
      "avg_price": 0,
      "image_url": "string",
      "variant_attributes": null,
      "specifications": null,
      "data": null,
      "quality_score": 0,
      "data_tier": 0,
      "source_type": "string",
      "product_group_id": "string",
      "created_at": "string",
      "updated_at": "string",
      "brand": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "logo_url": "string",
        "website_url": "string",
        "created_at": "string"
      },
      "category": {
        "id": "string",
        "name": "string",
        "description": "string",
        "icon": "string",
        "is_featured": true,
        "parent_id": "string"
      },
      "product_type": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "subcategory_id": "string",
        "is_active": true,
        "level": 0,
        "path": "string"
      },
      "product_group": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "description": "string",
        "base_model": "string",
        "series_name": "string",
        "variant_dimensions": [
          "string"
        ],
        "original_msrp": 0,
        "current_market_value": 0,
        "product_status": "string",
        "brand_id": "string",
        "category_id": "string",
        "product_type_id": "string",
        "brand": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "logo_url": "string",
          "website_url": "string",
          "created_at": "string"
        },
        "category": {
          "id": "string",
          "name": "string",
          "description": "string",
          "icon": "string",
          "is_featured": true,
          "parent_id": "string"
        },
        "product_type": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "subcategory_id": "string",
          "is_active": true,
          "level": 0,
          "path": "string"
        },
        "variant_count": 0,
        "products": [
          null
        ]
      },
      "offers": [
        {
          "retailer_name": "string",
          "price": 0,
          "original_price": 0,
          "currency": "string",
          "in_stock": true,
          "availability": "string",
          "retailer_url": "string",
          "last_seen_at": "string"
        }
      ],
      "_variant_count": 0,
      "_naming_method": "string",
      "_naming_confidence": 0,
      "_category_profile_key": "string",
      "_spec_sources": {
        "property1": null,
        "property2": null
      },
      "_quality_breakdown": {
        "completeness": 0,
        "validity": 0,
        "confidence": 0,
        "crossValidation": 0,
        "attributeScore": 0,
        "nameScore": 0,
        "knowledgeScore": 0
      }
    }
  ],
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  },
  "pagination": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "page": 0,
    "cursor": "string",
    "hasMore": true,
    "nextCursor": "string",
    "prevCursor": "string"
  }
}
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "userMessage": "string",
    "details": null,
    "retryable": true,
    "retryAfter": 0
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  }
}

Get product by ID

GET
/v2/products/{id}

Path Parameters

id*string
Formatuuid

Query Parameters

include_variants?|
include_offers?|

Include retailer offers/pricing

include_attributes?|

Include typed product attributes

format?string

Response format: json (full), schemaorg (structured data), ai (token-efficient for agents)

Default"json"
Value in"json" | "schemaorg" | "ai"
include_knowledge?boolean

Include inline knowledge enrichment (lifespan, maintenance, cost of ownership, buying guide). Requires Starter tier or above.

Response Body

application/json

application/json

curl -X GET "https://api.covala.com/v2/products/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "success": true,
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "slug": "string",
    "description": "string",
    "gtin": "string",
    "mpn": "string",
    "model_number": "string",
    "current_best_price": 0,
    "min_price": 0,
    "max_price": 0,
    "avg_price": 0,
    "image_url": "string",
    "variant_attributes": null,
    "specifications": null,
    "data": null,
    "quality_score": 0,
    "data_tier": 0,
    "source_type": "string",
    "product_group_id": "string",
    "created_at": "string",
    "updated_at": "string",
    "brand": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "logo_url": "string",
      "website_url": "string",
      "created_at": "string"
    },
    "category": {
      "id": "string",
      "name": "string",
      "description": "string",
      "icon": "string",
      "is_featured": true,
      "parent_id": "string"
    },
    "product_type": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "subcategory_id": "string",
      "is_active": true,
      "level": 0,
      "path": "string"
    },
    "product_group": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "description": "string",
      "base_model": "string",
      "series_name": "string",
      "variant_dimensions": [
        "string"
      ],
      "original_msrp": 0,
      "current_market_value": 0,
      "product_status": "string",
      "brand_id": "string",
      "category_id": "string",
      "product_type_id": "string",
      "brand": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "logo_url": "string",
        "website_url": "string",
        "created_at": "string"
      },
      "category": {
        "id": "string",
        "name": "string",
        "description": "string",
        "icon": "string",
        "is_featured": true,
        "parent_id": "string"
      },
      "product_type": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "subcategory_id": "string",
        "is_active": true,
        "level": 0,
        "path": "string"
      },
      "variant_count": 0,
      "products": [
        null
      ]
    },
    "offers": [
      {
        "retailer_name": "string",
        "price": 0,
        "original_price": 0,
        "currency": "string",
        "in_stock": true,
        "availability": "string",
        "retailer_url": "string",
        "last_seen_at": "string"
      }
    ],
    "_variant_count": 0,
    "_naming_method": "string",
    "_naming_confidence": 0,
    "_category_profile_key": "string",
    "_spec_sources": {
      "property1": null,
      "property2": null
    },
    "_quality_breakdown": {
      "completeness": 0,
      "validity": 0,
      "confidence": 0,
      "crossValidation": 0,
      "attributeScore": 0,
      "nameScore": 0,
      "knowledgeScore": 0
    },
    "variants": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "slug": "string",
        "description": "string",
        "gtin": "string",
        "mpn": "string",
        "model_number": "string",
        "current_best_price": 0,
        "min_price": 0,
        "max_price": 0,
        "avg_price": 0,
        "image_url": "string",
        "variant_attributes": null,
        "specifications": null,
        "data": null,
        "quality_score": 0,
        "data_tier": 0,
        "source_type": "string",
        "product_group_id": "string",
        "created_at": "string",
        "updated_at": "string",
        "brand": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "logo_url": "string",
          "website_url": "string",
          "created_at": "string"
        },
        "category": {
          "id": "string",
          "name": "string",
          "description": "string",
          "icon": "string",
          "is_featured": true,
          "parent_id": "string"
        },
        "product_type": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "subcategory_id": "string",
          "is_active": true,
          "level": 0,
          "path": "string"
        },
        "product_group": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "description": "string",
          "base_model": "string",
          "series_name": "string",
          "variant_dimensions": [
            "string"
          ],
          "original_msrp": 0,
          "current_market_value": 0,
          "product_status": "string",
          "brand_id": "string",
          "category_id": "string",
          "product_type_id": "string",
          "brand": {
            "id": "string",
            "name": "string",
            "slug": "string",
            "logo_url": "string",
            "website_url": "string",
            "created_at": "string"
          },
          "category": {
            "id": "string",
            "name": "string",
            "description": "string",
            "icon": "string",
            "is_featured": true,
            "parent_id": "string"
          },
          "product_type": {
            "id": "string",
            "name": "string",
            "slug": "string",
            "subcategory_id": "string",
            "is_active": true,
            "level": 0,
            "path": "string"
          },
          "variant_count": 0,
          "products": [
            null
          ]
        },
        "offers": [
          {
            "retailer_name": "string",
            "price": 0,
            "original_price": 0,
            "currency": "string",
            "in_stock": true,
            "availability": "string",
            "retailer_url": "string",
            "last_seen_at": "string"
          }
        ],
        "_variant_count": 0,
        "_naming_method": "string",
        "_naming_confidence": 0,
        "_category_profile_key": "string",
        "_spec_sources": {
          "property1": null,
          "property2": null
        },
        "_quality_breakdown": {
          "completeness": 0,
          "validity": 0,
          "confidence": 0,
          "crossValidation": 0,
          "attributeScore": 0,
          "nameScore": 0,
          "knowledgeScore": 0
        }
      }
    ],
    "attributes": [
      {
        "key": "string",
        "value": "string",
        "numericValue": 0,
        "unit": "string",
        "role": "variant"
      }
    ]
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  }
}
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "userMessage": "string",
    "details": null,
    "retryable": true,
    "retryAfter": 0
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  }
}

Get product by slug

GET
/v2/products/by-slug/{slug}

Path Parameters

slug*string
Match^[a-z0-9-]+$
Length1 <= length

Query Parameters

include_variants?|
include_offers?|

Include retailer offers/pricing

format?string

Response format: json (full), schemaorg (structured data), ai (token-efficient for agents)

Default"json"
Value in"json" | "schemaorg" | "ai"
include_knowledge?boolean

Include inline knowledge enrichment (lifespan, maintenance, cost of ownership, buying guide). Requires Starter tier or above.

Response Body

application/json

application/json

curl -X GET "https://api.covala.com/v2/products/by-slug/string"
{
  "success": true,
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "slug": "string",
    "description": "string",
    "gtin": "string",
    "mpn": "string",
    "model_number": "string",
    "current_best_price": 0,
    "min_price": 0,
    "max_price": 0,
    "avg_price": 0,
    "image_url": "string",
    "variant_attributes": null,
    "specifications": null,
    "data": null,
    "quality_score": 0,
    "data_tier": 0,
    "source_type": "string",
    "product_group_id": "string",
    "created_at": "string",
    "updated_at": "string",
    "brand": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "logo_url": "string",
      "website_url": "string",
      "created_at": "string"
    },
    "category": {
      "id": "string",
      "name": "string",
      "description": "string",
      "icon": "string",
      "is_featured": true,
      "parent_id": "string"
    },
    "product_type": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "subcategory_id": "string",
      "is_active": true,
      "level": 0,
      "path": "string"
    },
    "product_group": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "description": "string",
      "base_model": "string",
      "series_name": "string",
      "variant_dimensions": [
        "string"
      ],
      "original_msrp": 0,
      "current_market_value": 0,
      "product_status": "string",
      "brand_id": "string",
      "category_id": "string",
      "product_type_id": "string",
      "brand": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "logo_url": "string",
        "website_url": "string",
        "created_at": "string"
      },
      "category": {
        "id": "string",
        "name": "string",
        "description": "string",
        "icon": "string",
        "is_featured": true,
        "parent_id": "string"
      },
      "product_type": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "subcategory_id": "string",
        "is_active": true,
        "level": 0,
        "path": "string"
      },
      "variant_count": 0,
      "products": [
        null
      ]
    },
    "offers": [
      {
        "retailer_name": "string",
        "price": 0,
        "original_price": 0,
        "currency": "string",
        "in_stock": true,
        "availability": "string",
        "retailer_url": "string",
        "last_seen_at": "string"
      }
    ],
    "_variant_count": 0,
    "_naming_method": "string",
    "_naming_confidence": 0,
    "_category_profile_key": "string",
    "_spec_sources": {
      "property1": null,
      "property2": null
    },
    "_quality_breakdown": {
      "completeness": 0,
      "validity": 0,
      "confidence": 0,
      "crossValidation": 0,
      "attributeScore": 0,
      "nameScore": 0,
      "knowledgeScore": 0
    },
    "variants": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "slug": "string",
        "description": "string",
        "gtin": "string",
        "mpn": "string",
        "model_number": "string",
        "current_best_price": 0,
        "min_price": 0,
        "max_price": 0,
        "avg_price": 0,
        "image_url": "string",
        "variant_attributes": null,
        "specifications": null,
        "data": null,
        "quality_score": 0,
        "data_tier": 0,
        "source_type": "string",
        "product_group_id": "string",
        "created_at": "string",
        "updated_at": "string",
        "brand": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "logo_url": "string",
          "website_url": "string",
          "created_at": "string"
        },
        "category": {
          "id": "string",
          "name": "string",
          "description": "string",
          "icon": "string",
          "is_featured": true,
          "parent_id": "string"
        },
        "product_type": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "subcategory_id": "string",
          "is_active": true,
          "level": 0,
          "path": "string"
        },
        "product_group": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "description": "string",
          "base_model": "string",
          "series_name": "string",
          "variant_dimensions": [
            "string"
          ],
          "original_msrp": 0,
          "current_market_value": 0,
          "product_status": "string",
          "brand_id": "string",
          "category_id": "string",
          "product_type_id": "string",
          "brand": {
            "id": "string",
            "name": "string",
            "slug": "string",
            "logo_url": "string",
            "website_url": "string",
            "created_at": "string"
          },
          "category": {
            "id": "string",
            "name": "string",
            "description": "string",
            "icon": "string",
            "is_featured": true,
            "parent_id": "string"
          },
          "product_type": {
            "id": "string",
            "name": "string",
            "slug": "string",
            "subcategory_id": "string",
            "is_active": true,
            "level": 0,
            "path": "string"
          },
          "variant_count": 0,
          "products": [
            null
          ]
        },
        "offers": [
          {
            "retailer_name": "string",
            "price": 0,
            "original_price": 0,
            "currency": "string",
            "in_stock": true,
            "availability": "string",
            "retailer_url": "string",
            "last_seen_at": "string"
          }
        ],
        "_variant_count": 0,
        "_naming_method": "string",
        "_naming_confidence": 0,
        "_category_profile_key": "string",
        "_spec_sources": {
          "property1": null,
          "property2": null
        },
        "_quality_breakdown": {
          "completeness": 0,
          "validity": 0,
          "confidence": 0,
          "crossValidation": 0,
          "attributeScore": 0,
          "nameScore": 0,
          "knowledgeScore": 0
        }
      }
    ]
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  }
}
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "userMessage": "string",
    "details": null,
    "retryable": true,
    "retryAfter": 0
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  }
}

Get product attributes

GET
/v2/products/{id}/attributes

Path Parameters

id*string
Formatuuid

Query Parameters

role?string

Filter by attribute role

Value in"variant" | "identity" | "spec"

Response Body

application/json

application/json

curl -X GET "https://api.covala.com/v2/products/497f6eca-6276-4993-bfeb-53cbbbba6f08/attributes"
{
  "success": true,
  "data": {
    "productId": "string",
    "attributes": [
      {
        "key": "string",
        "value": "string",
        "numericValue": 0,
        "unit": "string",
        "role": "variant"
      }
    ],
    "count": 0
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  }
}
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "userMessage": "string",
    "details": null,
    "retryable": true,
    "retryAfter": 0
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  }
}

Get product relationships

GET
/v2/products/{id}/relationships

Path Parameters

id*string
Formatuuid

Query Parameters

type?string

Filter by relationship type

Default"all"
Value in"successor" | "similar" | "consumable" | "accessory" | "series" | "all"

Response Body

application/json

application/json

curl -X GET "https://api.covala.com/v2/products/497f6eca-6276-4993-bfeb-53cbbbba6f08/relationships"
{
  "success": true,
  "data": {
    "productId": "string",
    "successor": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "slug": "string",
      "current_best_price": 0,
      "image_url": "string",
      "brand": {
        "id": "string",
        "name": "string"
      }
    },
    "predecessor": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "slug": "string",
      "current_best_price": 0,
      "image_url": "string",
      "brand": {
        "id": "string",
        "name": "string"
      }
    },
    "similar": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "slug": "string",
        "current_best_price": 0,
        "image_url": "string",
        "brand": {
          "id": "string",
          "name": "string"
        }
      }
    ],
    "consumables": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "slug": "string",
        "current_best_price": 0,
        "image_url": "string",
        "brand": {
          "id": "string",
          "name": "string"
        }
      }
    ],
    "series": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "slug": "string",
        "current_best_price": 0,
        "image_url": "string",
        "brand": {
          "id": "string",
          "name": "string"
        }
      }
    ]
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  }
}
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "userMessage": "string",
    "details": null,
    "retryable": true,
    "retryAfter": 0
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  }
}

Look up product by model number

GET
/v2/products/lookup

Query Parameters

model*string

Model number to look up

Length2 <= length
brand?string

Brand hint to narrow decoder matching

Response Body

application/json

curl -X GET "https://api.covala.com/v2/products/lookup?model=string"
{
  "success": true,
  "data": {
    "match_type": "exact",
    "product": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "slug": "string",
      "description": "string",
      "gtin": "string",
      "mpn": "string",
      "model_number": "string",
      "current_best_price": 0,
      "min_price": 0,
      "max_price": 0,
      "avg_price": 0,
      "image_url": "string",
      "variant_attributes": null,
      "specifications": null,
      "data": null,
      "quality_score": 0,
      "data_tier": 0,
      "source_type": "string",
      "product_group_id": "string",
      "created_at": "string",
      "updated_at": "string",
      "brand": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "logo_url": "string",
        "website_url": "string",
        "created_at": "string"
      },
      "category": {
        "id": "string",
        "name": "string",
        "description": "string",
        "icon": "string",
        "is_featured": true,
        "parent_id": "string"
      },
      "product_type": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "subcategory_id": "string",
        "is_active": true,
        "level": 0,
        "path": "string"
      },
      "product_group": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "description": "string",
        "base_model": "string",
        "series_name": "string",
        "variant_dimensions": [
          "string"
        ],
        "original_msrp": 0,
        "current_market_value": 0,
        "product_status": "string",
        "brand_id": "string",
        "category_id": "string",
        "product_type_id": "string",
        "brand": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "logo_url": "string",
          "website_url": "string",
          "created_at": "string"
        },
        "category": {
          "id": "string",
          "name": "string",
          "description": "string",
          "icon": "string",
          "is_featured": true,
          "parent_id": "string"
        },
        "product_type": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "subcategory_id": "string",
          "is_active": true,
          "level": 0,
          "path": "string"
        },
        "variant_count": 0,
        "products": [
          null
        ]
      },
      "offers": [
        {
          "retailer_name": "string",
          "price": 0,
          "original_price": 0,
          "currency": "string",
          "in_stock": true,
          "availability": "string",
          "retailer_url": "string",
          "last_seen_at": "string"
        }
      ],
      "_variant_count": 0,
      "_naming_method": "string",
      "_naming_confidence": 0,
      "_category_profile_key": "string",
      "_spec_sources": {
        "property1": null,
        "property2": null
      },
      "_quality_breakdown": {
        "completeness": 0,
        "validity": 0,
        "confidence": 0,
        "crossValidation": 0,
        "attributeScore": 0,
        "nameScore": 0,
        "knowledgeScore": 0
      }
    },
    "decoded": {
      "brand": "string",
      "productType": "string",
      "modelNumber": "string",
      "specs": {
        "property1": "string",
        "property2": "string"
      },
      "confidence": 0
    }
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  }
}

Look up product by barcode (GTIN/UPC/EAN)

GET
/v2/products/barcode/{gtin}

Path Parameters

gtin*string
Match^\d+$
Length8 <= length <= 14

Response Body

application/json

application/json

curl -X GET "https://api.covala.com/v2/products/barcode/stringst"
{
  "success": true,
  "data": {
    "gtin": "string",
    "name": "string",
    "brand": "string",
    "category": "string",
    "product_type": "string",
    "image_url": "string",
    "current_best_price": 0,
    "specifications": null,
    "retailers": [
      {
        "name": "string",
        "price": 0,
        "in_stock": true
      }
    ]
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  }
}
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "userMessage": "string",
    "details": null,
    "retryable": true,
    "retryAfter": 0
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  }
}

Get price intelligence for a product

GET
/v2/products/{id}/prices

Path Parameters

id*string
Formatuuid

Query Parameters

days?number

Number of days of price history

Default30
Range1 <= value <= 365

Response Body

application/json

application/json

curl -X GET "https://api.covala.com/v2/products/497f6eca-6276-4993-bfeb-53cbbbba6f08/prices"
{
  "success": true,
  "data": {
    "product_id": "string",
    "product_name": "string",
    "current": {
      "best_price": 0,
      "retailer_count": 0,
      "retailers": [
        {
          "retailer": "string",
          "price": 0,
          "in_stock": true,
          "last_seen_at": "string"
        }
      ]
    },
    "summary": {
      "min_ever": 0,
      "max_ever": 0,
      "avg_30d": 0,
      "trend": "rising"
    },
    "history": [
      {
        "date": "string",
        "price": 0
      }
    ]
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  }
}
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "userMessage": "string",
    "details": null,
    "retryable": true,
    "retryAfter": 0
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  }
}
POST
/v2/products/search

Request Body

application/json

query?string
filters?
sort?
pagination?
mode?string

Search mode: keyword (full-text), semantic (vector), or hybrid (RRF fusion of both)

Default"keyword"
Value in"keyword" | "semantic" | "hybrid"

Response Body

application/json

curl -X POST "https://api.covala.com/v2/products/search" \  -H "Content-Type: application/json" \  -d '{}'
{
  "success": true,
  "data": {
    "products": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "slug": "string",
        "description": "string",
        "gtin": "string",
        "mpn": "string",
        "model_number": "string",
        "current_best_price": 0,
        "min_price": 0,
        "max_price": 0,
        "avg_price": 0,
        "image_url": "string",
        "variant_attributes": null,
        "specifications": null,
        "data": null,
        "quality_score": 0,
        "data_tier": 0,
        "source_type": "string",
        "product_group_id": "string",
        "created_at": "string",
        "updated_at": "string",
        "brand": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "logo_url": "string",
          "website_url": "string",
          "created_at": "string"
        },
        "category": {
          "id": "string",
          "name": "string",
          "description": "string",
          "icon": "string",
          "is_featured": true,
          "parent_id": "string"
        },
        "product_type": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "subcategory_id": "string",
          "is_active": true,
          "level": 0,
          "path": "string"
        },
        "product_group": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "description": "string",
          "base_model": "string",
          "series_name": "string",
          "variant_dimensions": [
            "string"
          ],
          "original_msrp": 0,
          "current_market_value": 0,
          "product_status": "string",
          "brand_id": "string",
          "category_id": "string",
          "product_type_id": "string",
          "brand": {
            "id": "string",
            "name": "string",
            "slug": "string",
            "logo_url": "string",
            "website_url": "string",
            "created_at": "string"
          },
          "category": {
            "id": "string",
            "name": "string",
            "description": "string",
            "icon": "string",
            "is_featured": true,
            "parent_id": "string"
          },
          "product_type": {
            "id": "string",
            "name": "string",
            "slug": "string",
            "subcategory_id": "string",
            "is_active": true,
            "level": 0,
            "path": "string"
          },
          "variant_count": 0,
          "products": [
            null
          ]
        },
        "offers": [
          {
            "retailer_name": "string",
            "price": 0,
            "original_price": 0,
            "currency": "string",
            "in_stock": true,
            "availability": "string",
            "retailer_url": "string",
            "last_seen_at": "string"
          }
        ],
        "_variant_count": 0,
        "_naming_method": "string",
        "_naming_confidence": 0,
        "_category_profile_key": "string",
        "_spec_sources": {
          "property1": null,
          "property2": null
        },
        "_quality_breakdown": {
          "completeness": 0,
          "validity": 0,
          "confidence": 0,
          "crossValidation": 0,
          "attributeScore": 0,
          "nameScore": 0,
          "knowledgeScore": 0
        }
      }
    ],
    "facets": {
      "categories": [
        {
          "id": "string",
          "name": "string",
          "count": 0
        }
      ],
      "brands": [
        {
          "id": "string",
          "name": "string",
          "count": 0
        }
      ],
      "price_ranges": [
        {
          "range": "string",
          "count": 0
        }
      ]
    }
  },
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  },
  "pagination": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "page": 0,
    "cursor": "string",
    "hasMore": true,
    "nextCursor": "string",
    "prevCursor": "string"
  }
}
POST
/v2/products/semantic-search

Request Body

application/json

query*string
Length2 <= length <= 500
limit?number
Default20
Range1 <= value <= 100
threshold?number
Default0.3
Range0 <= value <= 1
filters?

Response Body

application/json

curl -X POST "https://api.covala.com/v2/products/semantic-search" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'
{
  "success": true,
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "slug": "string",
      "description": "string",
      "gtin": "string",
      "mpn": "string",
      "model_number": "string",
      "current_best_price": 0,
      "min_price": 0,
      "max_price": 0,
      "avg_price": 0,
      "image_url": "string",
      "variant_attributes": null,
      "specifications": null,
      "data": null,
      "quality_score": 0,
      "data_tier": 0,
      "source_type": "string",
      "product_group_id": "string",
      "created_at": "string",
      "updated_at": "string",
      "brand": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "logo_url": "string",
        "website_url": "string",
        "created_at": "string"
      },
      "category": {
        "id": "string",
        "name": "string",
        "description": "string",
        "icon": "string",
        "is_featured": true,
        "parent_id": "string"
      },
      "product_type": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "subcategory_id": "string",
        "is_active": true,
        "level": 0,
        "path": "string"
      },
      "product_group": {
        "id": "string",
        "name": "string",
        "slug": "string",
        "description": "string",
        "base_model": "string",
        "series_name": "string",
        "variant_dimensions": [
          "string"
        ],
        "original_msrp": 0,
        "current_market_value": 0,
        "product_status": "string",
        "brand_id": "string",
        "category_id": "string",
        "product_type_id": "string",
        "brand": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "logo_url": "string",
          "website_url": "string",
          "created_at": "string"
        },
        "category": {
          "id": "string",
          "name": "string",
          "description": "string",
          "icon": "string",
          "is_featured": true,
          "parent_id": "string"
        },
        "product_type": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "subcategory_id": "string",
          "is_active": true,
          "level": 0,
          "path": "string"
        },
        "variant_count": 0,
        "products": [
          null
        ]
      },
      "offers": [
        {
          "retailer_name": "string",
          "price": 0,
          "original_price": 0,
          "currency": "string",
          "in_stock": true,
          "availability": "string",
          "retailer_url": "string",
          "last_seen_at": "string"
        }
      ],
      "_variant_count": 0,
      "_naming_method": "string",
      "_naming_confidence": 0,
      "_category_profile_key": "string",
      "_spec_sources": {
        "property1": null,
        "property2": null
      },
      "_quality_breakdown": {
        "completeness": 0,
        "validity": 0,
        "confidence": 0,
        "crossValidation": 0,
        "attributeScore": 0,
        "nameScore": 0,
        "knowledgeScore": 0
      },
      "_similarity": 0
    }
  ],
  "meta": {
    "requestId": "string",
    "timestamp": "string",
    "responseTime": 0,
    "version": "string",
    "cached": true
  },
  "pagination": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "page": 0,
    "cursor": "string",
    "hasMore": true,
    "nextCursor": "string",
    "prevCursor": "string"
  }
}

Authentication

How to authenticate with the Covala API using API keys.

Product Groups

Product variant management