Categories

FurniOps files every product under one category of the FurniOps taxonomy: a single tree for furniture and furnishings, aligned to the GS1 GPC segment "Household/Office Furniture/Furnishings". Each category names the GPC class it falls under.

Vendors file products their own way (Upholstery › Sectionals, Living Room › Sofas & Loveseats). Category rules connect a source's paths to the taxonomy, per source.

The taxonomyCopy Anchor Link

GET /v1/categories returns the whole tree in one list, parents before their children:

{
  "object": "category",
  "id": "ctg_034XqBaL2mRLTZPXyRbaUk",
  "parent": "ctg_034XqBaL2mRLTZPXyRbaUs",
  "name": "Sofas",
  "slug": "sofas",
  "path": "Living Room › Sofas",
  "gpc_class": "75010200"
}

slug is stable and unique across the tree; path joins the names from the top with ›.

A source's pathsCopy Anchor Link

GET /v1/sources/{id}/categories lists every category path the source's current products name, and every path above them, in path order:

Products under a path with no rule, set or inherited, have no category.

RulesCopy Anchor Link

• A rule covers its path and every path below it, until a more specific rule: the most specific rule wins.
• A rule can sit at any level of the source's path. One rule on Living Room files everything below it; a second on Living Room › Accent Chairs takes those elsewhere.
• Suggestions are never applied on their own. A person confirms every rule, or an AI agent proposes one and the organisation's autonomy decides.
• Names are compared loosely when suggesting: case, & against "and", punctuation and a plural s are ignored, so "Bunk & Loft Beds" meets "bunk and loft bed".

POST /v1/sources/{id}/categories sets or removes the rules given, up to 500 in one request; other rules stay as they are. category: null removes the rule at that path.

// The source's category paths, with the rule each takes or a same-name suggestion.
const paths = await furniops.sources.listCategories("src_034XqBaL2mRLTZPXyRbaUc");
for (const p of paths.data)
  console.log(p.path.join(" › "), p.products, p.rule?.path ?? p.inherited?.path ?? "no category");
// One rule covers its path and every path below it, until a more specific rule.
await furniops.sources.saveCategoryRules("src_034XqBaL2mRLTZPXyRbaUc", {
  rules: [{ path: ["Living Room", "Sofas"], category: "ctg_034XqBaL2mRLTZPXyRbaUd" }],
});

Saving replays the source's current snapshot to apply the rules, and the answer holds the source's categories with the rules now in force and that replay. An unknown category, or the same path twice, answers 422. A source with a run under way, or a paused or disabled one, answers 409, and then nothing is saved.

The dashboard's Categories page is not available yet; set rules through the API, or accept the categories agent's proposals under Catalogue › Proposals.