Taxonomies

Organize content with hierarchical categories and filterable attributes

Taxonomies provide hierarchical categorization for nodes, products, services, and providers. Each taxonomy defines a schema of filterable fields that can then be attached to content as TaxonomyEntry values.

Create Taxonomy

POST /v1/businesses/{businessId}/taxonomies

SDK: sdk.taxonomy.createTaxonomy()

const taxonomy = await sdk.taxonomy.createTaxonomy({
  key: 'product-attributes',
  schema: [
    { type: 'text', id: 'fld_color', key: 'color', value: ['red', 'blue', 'green'] },
    { type: 'text', id: 'fld_size', key: 'size', value: ['S', 'M', 'L'] },
    { type: 'number', id: 'fld_weight', key: 'weight', min: 0, max: 100 },
  ],
});

// Create a child taxonomy
const child = await sdk.taxonomy.createTaxonomy({
  key: 'electronics',
  parentId: taxonomy.id,
  schema: [
    { type: 'boolean', id: 'fld_wireless', key: 'wireless' },
  ],
});

Parameters

Name	Type	Description
`key` required	`string`	Unique taxonomy identifier
`parentId` optional	`string \| null`	Parent taxonomy ID for nesting
`schema` optional	`TaxonomySchema[]`	Filterable field definitions

Schema Field Types

Type	Extra options
`text`	`value: string[]` (allowed values), `min`
`number`	`min`, `max`
`boolean`	—
`geo_location`	—

Response

{
  "id": "tax_abc123",
  "key": "product-attributes",
  "businessId": "biz_123",
  "parentId": null,
  "schema": [
    { "type": "text", "id": "fld_color", "key": "color", "value": ["red", "blue", "green"] }
  ],
  "status": "active",
  "createdAt": 1704067200,
  "updatedAt": 1704067200
}

Get Taxonomy

GET /v1/businesses/{businessId}/taxonomies/{id}

SDK: sdk.taxonomy.getTaxonomy()

Retrieve a taxonomy by ID or key.

// By ID
const taxonomy = await sdk.taxonomy.getTaxonomy({ id: 'tax_abc123' });

// By key
const taxonomy = await sdk.taxonomy.getTaxonomy({ key: 'product-attributes' });

List Taxonomies

GET /v1/businesses/{businessId}/taxonomies

SDK: sdk.taxonomy.getTaxonomies()

const { items, cursor } = await sdk.taxonomy.getTaxonomies({
  status: 'active',
  limit: 50,
});

Parameters

Name	Type	Description
`parentId` optional	`string`	Filter by parent taxonomy
`query` optional	`string`	Search in taxonomy keys
`key` optional	`string`	Filter by exact key
`ids` optional	`string[]`	Filter by specific taxonomy IDs
`status` optional	`string`	Filter by status
`limit` optional	`number`	Items per page
`cursor` optional	`string`	Pagination cursor
`sortField` optional	`string`	Sort field
`sortDirection` optional	`asc \| desc`	Sort direction
`createdAtFrom` optional	`number`	Filter by creation date (start)
`createdAtTo` optional	`number`	Filter by creation date (end)

Get Taxonomy Children

GET /v1/businesses/{businessId}/taxonomies/{id}/children

SDK: sdk.taxonomy.getTaxonomyChildren()

Get direct children of a taxonomy.

const children = await sdk.taxonomy.getTaxonomyChildren({ id: 'tax_abc123' });

Parameters

Name	Type	Description
`id` required	`string`	Parent taxonomy ID

Update Taxonomy

PUT /v1/businesses/{businessId}/taxonomies/{id}

SDK: sdk.taxonomy.updateTaxonomy()

await sdk.taxonomy.updateTaxonomy({
  id: 'tax_abc123',
  schema: [
    { type: 'text', id: 'fld_color', key: 'color', value: ['red', 'blue', 'green', 'black'] },
    { type: 'text', id: 'fld_size', key: 'size', value: ['XS', 'S', 'M', 'L', 'XL'] },
    { type: 'text', id: 'fld_material', key: 'material', value: ['cotton', 'wool'] },
  ],
});

Parameters

Name	Type	Description
`id` required	`string`	Taxonomy ID
`key` optional	`string`	Updated key
`parentId` optional	`string \| null`	Move to new parent
`schema` optional	`TaxonomySchema[]`	Updated filter schema
`status` optional	`ACTIVE \| ARCHIVED`	Updated status

Delete Taxonomy

DELETE /v1/businesses/{businessId}/taxonomies/{id}

SDK: sdk.taxonomy.deleteTaxonomy()

Deletes the taxonomy and all its children. Removes taxonomy references from nodes, products, services, and providers.

await sdk.taxonomy.deleteTaxonomy({ id: 'tax_abc123' });

Warning

Deleting a taxonomy cascades to all child taxonomies and removes references from any nodes, products, services, and providers that use it.

Attaching a Taxonomy to Content

Once a taxonomy is defined, attach it to a node, product, service, or provider via a TaxonomyEntry:

await sdk.cms.updateNode({
  id: 'node_xyz789',
  taxonomies: [
    {
      taxonomyId: 'tax_abc123',
      fields: [
        { type: 'text', id: 'fld_color', key: 'color', value: ['red'] },
        { type: 'text', id: 'fld_size', key: 'size', value: ['M'] },
      ],
    },
  ],
});