Create Taxonomy

Create a new taxonomy to organize categories and control access through roles and languages.

Endpoint

POST /v1/workspaces/{workspaceId}/taxonomy

Authentication

This endpoint requires a Bearer token obtained through the two-step authentication flow:

First, generate an access token using your API key
Use that access token in the Authorization header

See Authentication for the complete authentication flow.

Request

# Step 1: Generate access token (do this once, reuse for multiple requests)
ACCESS_TOKEN=$(curl -s -X POST \
  'https://api.sharely.ai/workspaces/{workspaceId}/generate-access-key-token' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -d '{}' | jq -r '.token')
 
# Step 2: Create taxonomy using the access token
curl -X POST \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/taxonomy' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id' \
  -d '{
    "name": "Medical Knowledge Taxonomy",
    "description": "Organized medical knowledge by specialty"
  }'

Path Parameters

Parameter	Type	Required	Description
`workspaceId`	string (UUID)	Yes	The unique identifier of the workspace

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token with access token
`organizationid`	string (UUID)	Yes	Your organization ID
`Content-Type`	string	Yes	Must be `application/json`

Body Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Taxonomy name
`description`	string	No	Taxonomy description

Response

Success Response (201 Created)

{
  "id": "taxonomy-uuid",
  "workspaceId": "workspace-uuid",
  "name": "Medical Knowledge Taxonomy",
  "description": "Organized medical knowledge by specialty",
  "published": false,
  "createdAt": "2024-11-14T15:30:00Z",
  "updatedAt": "2024-11-14T15:30:00Z"
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Taxonomy unique identifier
`workspaceId`	string (UUID)	Parent workspace ID
`name`	string	Taxonomy name
`description`	string	Taxonomy description
`published`	boolean	Publication status (always false for new taxonomies)
`createdAt`	string (ISO 8601)	Creation timestamp
`updatedAt`	string (ISO 8601)	Last update timestamp

Example Usage

const fetch = require('node-fetch');
 
const API_KEY = 'sk-sharely-your-api-key';
const WORKSPACE_ID = 'your-workspace-id';
const ORGANIZATION_ID = 'your-organization-id';
const API_BASE_URL = 'https://api.sharely.ai';
 
// Step 1: Generate access token
async function getAccessToken() {
  const response = await fetch(
    `${API_BASE_URL}/workspaces/${WORKSPACE_ID}/generate-access-key-token`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': API_KEY
      },
      body: JSON.stringify({})
    }
  );
  const data = await response.json();
  return data.token;
}
 
// Step 2: Create taxonomy
async function createTaxonomy(accessToken, data) {
  const response = await fetch(
    `${API_BASE_URL}/v1/workspaces/${WORKSPACE_ID}/taxonomy`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
        'organizationid': ORGANIZATION_ID
      },
      body: JSON.stringify(data)
    }
  );
 
  if (!response.ok) {
    throw new Error(`Failed to create taxonomy: ${response.status}`);
  }
 
  return await response.json();
}
 
// Usage
const accessToken = await getAccessToken();
const taxonomy = await createTaxonomy(accessToken, {
  name: 'Medical Knowledge',
  description: 'Medical specialty taxonomy'
});
 
console.log('Created taxonomy:', taxonomy.id);

Next Steps

After creating a taxonomy:

Assign languages to support multilingual content
Assign roles for RBAC
Assign categories to organize content
Publish the taxonomy to make it active