Products - Search

Either search or categoryId is required.

Search the global catalog of products by text and/or category (with optional segments).
Use this to power product pickers, discovery, and faceted search.

Base URL: https://api.salescaddy.ai/api

Requirement: Provide either search or categoryId (or both).
Supports pagination via page/size.

---

Endpoint

POST /products/search (parameters in query string)

Query parameters

Name	Type	Required	Default	Description
search	string	No*	—	Text query (matches name/description, etc.)
categoryId	string	No*	—	Filter by product category ID
segment	array of string	No	—	Segment filter (multiple values allowed)
page	int	No	0	Page index (0‑based)
size	int	No	20	Page size (max 200)

* At least one of search or categoryId must be provided.

---

Example — Text search

Bash

curl -sS -X POST "https://api.salescaddy.ai/api/products/search?search=crm&page=0&size=10" \
  -H "Authorization: Bearer $TOKEN"

Node

const url = "https://api.salescaddy.ai/api/products/search?search=crm&page=0&size=10";
const res = await fetch(url, { method: "POST", headers: { Authorization: `Bearer ${process.env.TOKEN}` } });
console.log(await res.json());

Python

import os, requests
r = requests.post("https://api.salescaddy.ai/api/products/search",
                  params={"search":"crm","page":0,"size":10},
                  headers={"Authorization": f"Bearer {os.environ['TOKEN']}"})
print(r.json())

C#

using System.Net.Http.Headers;
var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", TOKEN);
var res = await http.PostAsync("https://api.salescaddy.ai/api/products/search?search=crm&page=0&size=10", null);
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample response (trimmed):

JSON

{
  "totalPages": 80,
  "totalElements": 400,
  "content": [
    {
      "id": "prod_hubspot_crm",
      "name": "HubSpot CRM",
      "description": "CRM platform for sales & marketing",
      "logo": "https://logo.example/hubspot.svg",
      "category": "CRM",
      "features": ["Pipeline","Email","Automation"],
      "reviewCount": 5321,
      "starRating": 4.4,
      "avgRating": 4.3,
      "vendor": { "id": "ven_hubspot", "name": "HubSpot", "domain": "hubspot.com" },
      "categoryId": "cat_crm"
    },
    {
      "id": "prod_salesforce_salescloud",
      "name": "Salesforce Sales Cloud",
      "description": "Sales CRM",
      "logo": "https://logo.example/salescloud.svg",
      "category": "CRM",
      "features": ["Accounts","Opportunities","Reporting"],
      "reviewCount": 10421,
      "starRating": 4.5,
      "avgRating": 4.4,
      "vendor": { "id": "ven_salesforce", "name": "Salesforce", "domain": "salesforce.com" },
      "categoryId": "cat_crm"
    }
  ]
}

---

Example — Category filter

Bash

curl -sS -X POST "https://api.salescaddy.ai/api/products/search?categoryId=cat_crm&page=0&size=10" \
  -H "Authorization: Bearer $TOKEN"

Node

const url = "https://api.salescaddy.ai/api/products/search?categoryId=cat_crm&page=0&size=10";
const res = await fetch(url, { method: "POST", headers: { Authorization: `Bearer ${process.env.TOKEN}` } });
console.log(await res.json());

Python

r = requests.post("https://api.salescaddy.ai/api/products/search",
                  params={"categoryId":"cat_crm","page":0,"size":10},
                  headers={"Authorization": f"Bearer {os.environ['TOKEN']}"})
print(r.json())

C#

var res = await http.PostAsync("https://api.salescaddy.ai/api/products/search?categoryId=cat_crm&page=0&size=10", null);
Console.WriteLine(await res.Content.ReadAsStringAsync());

---

Example — Text + Segments

Bash

curl -sS -X POST "https://api.salescaddy.ai/api/products/search?search=analytics&segment=midmarket&segment=enterprise&page=0&size=10" \
  -H "Authorization: Bearer $TOKEN"

Node

const url = "https://api.salescaddy.ai/api/products/search?search=analytics&segment=midmarket&segment=enterprise&page=0&size=10";
const res = await fetch(url, { method: "POST", headers: { Authorization: `Bearer ${process.env.TOKEN}` } });
console.log(await res.json());

Python

r = requests.post("https://api.salescaddy.ai/api/products/search",
                  params=[("search","analytics"),("segment","midmarket"),("segment","enterprise"),("page",0),("size",10)],
                  headers={"Authorization": f"Bearer {os.environ['TOKEN']}"})
print(r.json())

C#

var url = "https://api.salescaddy.ai/api/products/search?search=analytics&segment=midmarket&segment=enterprise&page=0&size=10";
var res = await http.PostAsync(url, null);
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample response (trimmed):

JSON

{
  "totalPages": 25,
  "totalElements": 245,
  "content": [
    {
      "id": "prod_snowflake",
      "name": "Snowflake",
      "description": "Cloud data platform",
      "logo": "https://logo.example/snowflake.svg",
      "category": "Data Warehouse",
      "features": ["SQL","Elastic compute","Secure data sharing"],
      "reviewCount": 3120,
      "starRating": 4.6,
      "avgRating": 4.5,
      "vendor": { "id": "ven_snowflake", "name": "Snowflake", "domain": "snowflake.com" },
      "categoryId": "cat_warehouse"
    },
    {
      "id": "prod_lookerstudio",
      "name": "Looker Studio",
      "description": "BI and visualization",
      "logo": "https://logo.example/looker.svg",
      "category": "Business Intelligence",
      "features": ["Dashboards","Connectors","Calculated fields"],
      "reviewCount": 980,
      "starRating": 4.2,
      "avgRating": 4.1,
      "vendor": { "id": "ven_google", "name": "Google", "domain": "google.com" },
      "categoryId": "cat_bi"
    }
  ]
}

---

Errors

Code	Meaning	How to fix
400	Bad request	Provide search or categoryId; validate page/size and query types.
401	Unauthorized	Provide/refresh Bearer token
404	Not found	No products match filters
429	Rate limit exceeded	Retry with exponential backoff
500	Internal server error	Retry later; contact support if persistent

---