List Taxonomies

Retrieve all taxonomies in your workspace, optionally filtered by role or language.

Endpoint

GET /v1/workspaces/{workspaceId}/taxonomy

Authentication

Requires API key authentication with a valid access token.

Request

curl -X GET \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/taxonomy?includeRoles=true' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id'

Path Parameters

ParameterTypeRequiredDescription
workspaceIdstring (UUID)YesThe unique identifier of the workspace

Query Parameters

ParameterTypeRequiredDescription
roleIdstring (UUID)NoFilter taxonomies assigned to this role
languageIdstringNoFilter taxonomies assigned to this language (e.g., "en", "es")
includeRolesbooleanNoInclude role assignments in response (default: false)
includeLanguagesbooleanNoInclude language assignments in response (default: false)
includeCategoriesbooleanNoInclude category assignments in response (default: false)

Headers

HeaderTypeRequiredDescription
AuthorizationstringYesBearer token with access token
organizationidstring (UUID)YesYour organization ID
Content-TypestringYesMust be application/json

Response

Success Response (200 OK)

[
  {
    "id": "taxonomy-uuid-1",
    "workspaceId": "workspace-uuid",
    "name": "Medical Knowledge",
    "description": "Medical specialty taxonomy",
    "published": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-11-14T15:45:00Z",
    "roles": [
      {
        "id": "role-uuid-1",
        "name": "Physician",
        "metadata": {
          "uniqueCustomerRoleId": "workspace-uuid.physician"
        }
      }
    ],
    "languages": [
      {"languageId": "en"},
      {"languageId": "es"}
    ],
    "categoryCount": 12
  }
]

Response Fields

FieldTypeDescription
idstring (UUID)Taxonomy unique identifier
workspaceIdstring (UUID)Parent workspace ID
namestringTaxonomy name
descriptionstringTaxonomy description
publishedbooleanWhether the taxonomy is active
createdAtstring (ISO 8601)Creation timestamp
updatedAtstring (ISO 8601)Last update timestamp
rolesarrayAssigned roles (if includeRoles=true)
languagesarrayAssigned languages (if includeLanguages=true)
categoryCountnumberNumber of categories in taxonomy

Example Usage

List All Taxonomies

const fetch = require('node-fetch');
 
async function listTaxonomies(workspaceId, accessToken, organizationId) {
  const response = await fetch(
    `https://api.sharely.ai/v1/workspaces/${workspaceId}/taxonomy`,
    {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
        'organizationid': organizationId
      }
    }
  );
 
  if (!response.ok) {
    throw new Error(`Failed to list taxonomies: ${response.status}`);
  }
 
  return await response.json();
}

Filter by Role

curl -X GET \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/taxonomy?roleId=role-uuid&includeRoles=true' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id'

Filter by Language

curl -X GET \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/taxonomy?languageId=en&includeLanguages=true' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id'

Related Endpoints