Taxonomies
A taxonomy contains a list of values that you can associate with content items, making it easier to find those items because of their common properties. For example, a taxonomy for a food site could be used to classify recipes into appetizers, main courses, desserts, or drinks. Before you start working with taxonomies, you must authenticate.
The base URL when working with taxonomies is https://content-api.sitecorecloud.io/. For a full list of fields, parameters, and technical limitations, see the data model. For guidance on API syntax, see Syntax.
Get all taxonomies
Use this method to retrieve a list of all taxonomies.
GET {Base URL}/api/content/v1/taxonomiesRequest
This code sample returns a list of taxonomies and associated taxonomy values.
GET {Base URL}/api/content/v1/taxonomies?pageSize=5&pageNumber=1Response
{
"totalCount": 4,
"pageSize": 5,
"pageNumber": 1,
"data": [
{
"id": "vacationType",
"name": {
"en-US": "Vacation type"
},
"values": [
{
"id": "allInclusive",
"name": {
"en-US": "All inclusive"
}
},
{
"id": "adultOnly",
"name": {
"en-US": "Adult only"
}
},
{
"id": "cruise",
"name": {
"en-US": "Cruise"
}
},
{
"id": "disneyThemed",
"name": {
"en-US": "Disney themed"
}
}
],
"system": {
"type": "Taxonomy",
"version": "nBAyyxW57IU0/OmN0eF/zvjIgt1wwR6EW+CRVpaJ2GQ=",
"createdBy": {
"type": "Link",
"relatedType": "User",
"id": "jake.b@sitecore.com",
"uri": "http://content-api.sitecorecloud.io/api/content/v1/users/jake.b@sitecore.com"
},
"createdAt": "2023-06-08T17:43:00.4788128Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "jake.b@sitecore.com",
"uri": "http://content-api.sitecorecloud.io/api/content/v1/users/jake.b@sitecore.com"
},
"updatedAt": "2023-06-08T17:43:00.4788128Z"
}
},
{
"id": "amenities",
"name": {
"en-US": "Amenities"
},
"values": [
{
"id": "airConditioning",
"name": {
"en-US": "Air conditioning"
}
},
{
"id": "parking",
"name": {
"en-US": "Parking"
}
},
{
"id": "restaurant",
"name": {
"en-US": "Restaurant"
}
},
{
"id": "wheelchairAccessible",
"name": {
"en-US": "Wheelchair accessible"
}
},
{
"id": "wifi",
"name": {
"en-US": "WiFi"
}
}
],
"system": {
"type": "Taxonomy",
"version": "wy45Wxsp7oIvDKPZlqexmpj4MMP2HbXA8BOJFpy8VhY=",
"createdBy": {
"type": "Link",
"relatedType": "User",
"id": "jake.b@sitecore.com",
"uri": "http://content-api.sitecorecloud.io/api/content/v1/users/jake.b@sitecore.com"
},
"createdAt": "2023-06-08T18:21:08.362753Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "jake.b@sitecore.com",
"uri": "http://content-api.sitecorecloud.io/api/content/v1/users/jake.b@sitecore.com"
},
"updatedAt": "2023-06-08T18:21:08.362753Z"
}
},
{
"id": "roomType",
"name": {
"en-US": "Room type"
},
"values": [
{
"id": "twinBeds",
"name": {
"en-US": "Twin beds"
}
},
{
"id": "queenBed",
"name": {
"en-US": "Queen bed"
}
},
{
"id": "kingBed",
"name": {
"en-US": "King bed"
}
}
],
"system": {
"type": "Taxonomy",
"version": "kEZzXzyqjBdUxsw61dBnNl88Bf03z+WqoV2sGiIew6c=",
"createdBy": {
"type": "Link",
"relatedType": "User",
"id": "jake.b@sitecore.com",
"uri": "http://content-api.sitecorecloud.io/api/content/v1/users/jake.b@sitecore.com"
},
"createdAt": "2023-06-09T14:34:23.1493095Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "jake.b@sitecore.com",
"uri": "http://content-api.sitecorecloud.io/api/content/v1/users/jake.b@sitecore.com"
},
"updatedAt": "2023-06-09T14:34:23.1493095Z"
}
},
{
"id": "test",
"name": {
"en-US": "Test"
},
"values": [
{
"id": "test1",
"name": {
"en-US": "test1"
}
},
{
"id": "test2",
"name": {
"en-US": "test2"
}
}
],
"system": {
"type": "Taxonomy",
"version": "mPfgxZcYrTd8p0ZlQWRHsjx8KPtmDROCzlJ7rIrrw7s=",
"createdBy": {
"type": "Link",
"relatedType": "User",
"id": "jake.b@sitecore.com",
"uri": "http://content-api.sitecorecloud.io/api/content/v1/users/jake.b@sitecore.com"
},
"createdAt": "2023-06-11T21:16:53.1717766Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "jake.b@sitecore.com",
"uri": "http://content-api.sitecorecloud.io/api/content/v1/users/jake.b@sitecore.com"
},
"updatedAt": "2023-06-11T21:16:53.1717766Z"
}
}
]
}Get a taxonomy using the ID
Use this method to retrieve a taxonomy with a specific ID. For a list of all available IDs, run the GET api/content/v1/taxonomies method. To view a specific taxonomy ID, open the relevant taxonomy's details page.
GET {Base URL}/api/content/v1/taxonomies/id={taxonomyId}Request
This code sample returns a taxonomy with the ID of hotels and associated taxonomy values:
GET {Base URL}/api/content/v1/taxonomies/id=hotelsResponse
{
"totalCount": 1,
"pageSize": 20,
"pageNumber": 1,
"data": [
{
"id": "hotels",
"taxonomy": null,
"name": {
"en-US": "hotels"
},
"values": [
{
"id": "luxury",
"name": {
"en-US": "luxury"
}
},
{
"id": "economy",
"name": {
"en-US": "economy"
}
}
],
"system": {
"type": "Taxonomy",
"version": "WK2wLsElsbjLhFK+n3/ZaJ6vcD/KLfKNHSSnMr0r58U=",
"createdBy": {
"type": "Link",
"relatedType": "User",
"id": "elise.d@sitecore.com",
"uri": "http://content-api.sitecore.cloud.io/api/content/v1/users/elise.d@sitecore.com"
},
"createdAt": "2023-11-07T17:22:58.1564067Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "elise.d@sitecore.com",
"uri": "http://content-api.sitecore.cloud.io/api/content/v1/users/elise.d@sitecore.com"
},
"updatedAt": "2023-11-07T17:22:58.1564067Z"
}
}
]
}Create a taxonomy
Use this method to create a taxonomy. During this process you can also create associated taxonomy values, even if you want to add more later.
POST {Base URL}/api/content/v1/taxonomiesRequest
This code sample creates a taxonomy called MealPlan with four taxonomy values (Breakfast, Lunch, Dinner, and allMeals).
POST {Base URL}/api/content/v1/taxonomiesThe request includes the following request body:
{
"name": {
"en-US": "MealPlan"
},
"id": "mealPlan",
"description": {
"en-US": "Meal plans included"
},
"values": [
{
"id": "Breakfast",
"name": {
"en-US": "Breakfast included"
}
},
{
"id": "Lunch",
"name": {
"en-US": "Lunch included"
}
},
{
"id": "Dinner",
"name": {
"en-US": "Dinner included"
}
},
{
"id": "allMeals",
"name": {
"en-US": "All meals included"
}
}
]
}Response
{
"id": "mealPlan",
"name": {
"en-US": "MealPlan"
},
"values": [
{
"id": "Breakfast",
"name": {
"en-US": "Breakfast included"
}
},
{
"id": "Lunch",
"name": {
"en-US": "Lunch included"
}
},
{
"id": "Dinner",
"name": {
"en-US": "Dinner included"
}
},
{
"id": "allMeals",
"name": {
"en-US": "All meals included"
}
}
],
"system": {
"type": "Taxonomy",
"version": "x1DGFdiurth1ZJ8Gjv5V2adMlnoGkVNY7SdExLF9L8g=",
"createdBy": {
"type": "Link",
"relatedType": "User",
"id": "thomas.louis@sitecore.com",
"uri": "http://content-api.sitecorecloud.io/api/content/v1/users/thomas.louis@sitecore.com"
},
"createdAt": "2023-06-22T16:53:17.4993418Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "thomas.louis@sitecore.com",
"uri": "http://content-api.sitecorecloud.io/api/content/v1/users/thomas.louis@sitecore.com"
},
"updatedAt": "2023-06-22T16:53:17.4993418Z"
}
}Update a taxonomy
Use this method to update a taxonomy. You can, for example, add new taxonomy values, delete existing values, or change properties associated with the taxonomy or its values.
The Update method does not merge content; rather, it fully replaces the existing content using the body of the request. For this reason, your request must include the new version of all the content, including your updates and any data you want to retain. Anything not included in your request will be replaced.
PUT {Base URL}/api/content/v1/taxonomies/{taxonomyId}Request
This code sample updates the taxonomy vacationType by adding another value to the list called Pet friendly.
PUT {Base URL}/api/content/v1/taxonomies/vacationTypeThe request includes the following request body:
{
"id": "vacationType",
"name": {
"en-US": "Vacation type"
},
"values": [
{
"id": "allInclusive",
"name": {
"en-US": "All inclusive"
}
},
{
"id": "adultOnly",
"name": {
"en-US": "Adult only"
}
},
{
"id": "cruise",
"name": {
"en-US": "Cruise"
}
},
{
"id": "disneyThemed",
"name": {
"en-US": "Disney themed"
}
},
{
"id": "petFriendly",
"name": {
"en-US": "Pet friendly"
}
},
],
"system": {
"type": "Taxonomy",
"version": "nBAyyxW57IU0/OmN0eF/zvjIgt1wwR6EW+CRVpaJ2GQ=",
"createdBy": {
"type": "Link",
"relatedType": "User",
"id": "suzie.q@sitecore.com",
"uri": "http://content-api.sitecorecloud.io/api/content/v1/users/suzie.q@sitecore.com"
},
"createdAt": "2023-06-08T17:43:00.4788128Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "suzie.q@sitecore.com",
"uri": "http://content-api.sitecorecloud.io/api/content/v1/users/suzie.q@sitecore.com"
},
"updatedAt": "2023-06-08T17:43:00.4788128Z"
}
} Response
{
"id": "vacationType",
"name": {
"en-US": "Vacation type"
},
"values": [
{
"id": "allInclusive",
"name": {
"en-US": "All inclusive"
}
},
{
"id": "adultOnly",
"name": {
"en-US": "Adult only"
}
},
{
"id": "cruise",
"name": {
"en-US": "Cruise"
}
},
{
"id": "disneyThemed",
"name": {
"en-US": "Disney themed"
}
},
{
"id": "petFriendly",
"name": {
"en-US": "Pet friendly"
}
}
],
"system": {
"type": "Taxonomy",
"version": "eWFKQGuiOiKosTVms8Ue927eetLgTn8SOgIFfwEXBTA=",
"createdBy": {
"type": "Link",
"relatedType": "User",
"id": "suzie.q@sitecore.com",
"uri": "http://content-api.sitecorecloud.io/api/content/v1/users/suzie.q@sitecore.com"
},
"createdAt": "2023-06-08T17:43:00.4788128Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "suzie.q@sitecore.com",
"uri": "http://content-api.sitecorecloud.io/api/content/v1/users/suzie.q@sitecore.com"
},
"updatedAt": "2023-06-13T12:27:00.2602067Z"
}
}Delete a taxonomy
Use this method to delete a taxonomy with a specific ID. You cannot delete a taxonomy if it is being used by a content type.
DELETE {Base URL}/api/content/v1/taxonomies/{taxonomyId}Request
This code sample deletes a taxonomy with the ID rating.
DELETE {Base URL}/api/content/v1/taxonomies/rating