Create Taxonomy

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

Endpoint

POST /v1/workspaces/{workspaceId}/taxonomy

Authentication

Requires API key authentication with a valid access token.

Request

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/taxonomy' \
  -H 'Authorization: Bearer YOUR_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

ParameterTypeRequiredDescription
workspaceIdstring (UUID)YesThe unique identifier of the workspace

Headers

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

Body Parameters

ParameterTypeRequiredDescription
namestringYesTaxonomy name
descriptionstringNoTaxonomy 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

FieldTypeDescription
idstring (UUID)Taxonomy unique identifier
workspaceIdstring (UUID)Parent workspace ID
namestringTaxonomy name
descriptionstringTaxonomy description
publishedbooleanPublication status (always false for new taxonomies)
createdAtstring (ISO 8601)Creation timestamp
updatedAtstring (ISO 8601)Last update timestamp

Example Usage

const fetch = require('node-fetch');
 
async function createTaxonomy(workspaceId, data, accessToken, organizationId) {
  const response = await fetch(
    'https://api.sharely.ai/v1/workspaces/' + workspaceId + '/taxonomy',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ' + accessToken,
        'Content-Type': 'application/json',
        'organizationid': organizationId
      },
      body: JSON.stringify(data)
    }
  );
 
  if (!response.ok) {
    throw new Error('Failed to create taxonomy: ' + response.status);
  }
 
  return await response.json();
}
 
// Usage
const taxonomy = await createTaxonomy(
  workspaceId,
  {
    name: 'Medical Knowledge',
    description: 'Medical specialty taxonomy'
  },
  accessToken,
  organizationId
);
 
console.log('Created taxonomy:', taxonomy.id);

Next Steps

After creating a taxonomy:

  1. Assign languages to support multilingual content
  2. Assign roles for RBAC
  3. Assign categories to organize content
  4. Publish the taxonomy to make it active

Related Endpoints