Taxonomy API

The Taxonomy API allows you to create and manage taxonomies - hierarchical structures that organize categories and control access through role-based and language-based filtering.

What is a Taxonomy?

A taxonomy is a classification system that:

Groups related categories together
Can be assigned to specific roles (for RBAC)
Can be assigned to specific languages (for multilingual support)
Must be published before becoming active

Base Endpoint

All taxonomy endpoints use the base path:

/v1/workspaces/{workspaceId}/taxonomy

Authentication

All taxonomy API endpoints require API key authentication. See the Authentication guide for details on generating access tokens.

Available Endpoints

Taxonomy Management

List Taxonomies - Get all taxonomies
Create Taxonomy - Create a new taxonomy
Get Taxonomy - Get a specific taxonomy
Get by Language - Get taxonomies for a language
Update Taxonomy - Update taxonomy details
Delete Taxonomy - Remove a taxonomy
Publish Taxonomy - Activate a taxonomy
Unpublish Taxonomy - Deactivate a taxonomy
Clone Taxonomy - Duplicate a taxonomy

Category Associations

Get Categories - List categories in a taxonomy
Assign Categories - Add categories to a taxonomy
Remove Categories - Remove categories from a taxonomy

Role Associations (RBAC)

Assign Roles - Assign roles to a taxonomy
Remove Roles - Remove roles from a taxonomy

Language Associations

Assign Languages - Assign languages to a taxonomy
Remove Languages - Remove languages from a taxonomy

Common Workflow

Creating a Role-Based, Multilingual Taxonomy

// 1. Create the taxonomy
const taxonomy = await createTaxonomy({
  name: "Medical Knowledge Taxonomy",
  description: "Organized medical knowledge by specialty"
});
 
// 2. Assign languages
await assignLanguages(taxonomy.id, {
  languageIds: ["en", "es", "pt"]
});
 
// 3. Assign roles (using roleId UUIDs)
await assignRoles(taxonomy.id, {
  roleIds: ["physician-role-uuid", "nurse-role-uuid"]
});
 
// 4. Assign categories
await assignCategories(taxonomy.id, {
  categoryIds: ["cardiology-uuid", "pediatrics-uuid"]
});
 
// 5. Publish to activate
await publishTaxonomy(taxonomy.id);

Important Concepts

Published vs Unpublished

Unpublished: Taxonomy exists but is not active. Users won't see it.
Published: Taxonomy is active and visible to assigned roles.

Role-Based Access

When RBAC is enabled:

Users only see taxonomies assigned to their role
Within a taxonomy, users only see categories they have access to
Use roleId (UUID) when assigning roles, not customerRoleId

Language Filtering

When using language parameters:

JSWebControl can filter taxonomies by language
Useful for showing different content structures per language
A taxonomy can support multiple languages