Dictionary - Product Categories

The categories dictionary provides the taxonomy of all product categories.
Use it to enrich products, build filters, or power a category tree in your UI.

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

---

Endpoints

• GET /categories
  Returns the full dictionary (JSON). With export=true → CSV file (binary).

• GET /categories/{categoryId}
  Returns details for a specific category.

Headers

• Authorization: Bearer <token> — required
• X-On-Behalf-Of-User: [email protected] — required only when export=true

---

Example — Get all categories (JSON)

Bash

curl -sS "https://api.salescaddy.ai/api/categories"   -H "Authorization: Bearer $TOKEN"

Node

const url = "https://api.salescaddy.ai/api/categories";
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.TOKEN}` } });
console.log(await res.json());

Python

import os, requests
r = requests.get("https://api.salescaddy.ai/api/categories",
                 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.GetAsync("https://api.salescaddy.ai/api/categories");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample response (trimmed):

JSON

[
  { "id":"cat_crm", "name":"CRM", "description":"Customer Relationship Management", "parentId":null },
  { "id":"cat_marketing", "name":"Marketing Automation", "description":"Tools for marketing automation", "parentId":null },
  { "id":"cat_email", "name":"Email Marketing", "description":"Campaign and email tools", "parentId":"cat_marketing" }
]

---

Example — Export categories (CSV)

Bash

curl -sS "https://api.salescaddy.ai/api/categories?export=true"   -H "Authorization: Bearer $TOKEN"   -H "X-On-Behalf-Of-User: [email protected]"   --output categories.csv

Node

import fs from "fs";
const res = await fetch("https://api.salescaddy.ai/api/categories?export=true", {
  headers: { Authorization: `Bearer ${process.env.TOKEN}`, "X-On-Behalf-Of-User":"[email protected]" }
});
const file = fs.createWriteStream("categories.csv");
res.body.pipe(file);

Python

with requests.get("https://api.salescaddy.ai/api/categories",
                  params={"export":"true"},
                  headers={
                    "Authorization": f"Bearer {os.environ['TOKEN']}",
                    "X-On-Behalf-Of-User":"[email protected]"
                  },
                  stream=True) as r:
    with open("categories.csv","wb") as f:
        for chunk in r.iter_content(8192):
            if chunk: f.write(chunk)

C#

http.DefaultRequestHeaders.Add("X-On-Behalf-Of-User","[email protected]");
var bytes = await http.GetByteArrayAsync("https://api.salescaddy.ai/api/categories?export=true");
System.IO.File.WriteAllBytes("categories.csv", bytes);

CSV snippet:

csv

id,name,description,parentId
cat_crm,CRM,Customer Relationship Management,
cat_marketing,Marketing Automation,Tools for marketing automation,
cat_email,Email Marketing,Campaign and email tools,cat_marketing

---

Example — Single category by ID

Bash

curl -sS "https://api.salescaddy.ai/api/categories/cat_crm"   -H "Authorization: Bearer $TOKEN"

Node

const res = await fetch("https://api.salescaddy.ai/api/categories/cat_crm", {
  headers: { Authorization: `Bearer ${process.env.TOKEN}` }
});
console.log(await res.json());

Python

r = requests.get("https://api.salescaddy.ai/api/categories/cat_crm",
                 headers={"Authorization": f"Bearer {os.environ['TOKEN']}"})
print(r.json())

C#

var res2 = await http.GetAsync("https://api.salescaddy.ai/api/categories/cat_crm");
Console.WriteLine(await res2.Content.ReadAsStringAsync());

Sample response:

JSON

{ "id":"cat_crm", "name":"CRM", "description":"Customer Relationship Management", "parentId":null }

---

Tips & best practices

• Categories form a hierarchy (use parentId to build a tree).
• Use categoryId when searching products or joining usage metrics.
• Cache this dictionary (changes infrequently).
• For large analytics, prefer CSV export.

---

Errors

Code	Meaning	How to fix
400	Bad request	Validate query/path.
401	Unauthorized	Provide/refresh Bearer token.
403	Forbidden	Check client permissions; include X-On-Behalf-Of-User for CSV.
404	Not found	Category not found.
429	Rate limit exceeded	Retry with exponential backoff.
500	Internal server error	Retry later; contact support if persistent.

---