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.
The properties available for taxonomies are determined by the data model. You can use query attributes to control the set of items returned. Before you start working with taxonomies, you must authenticate.
Get all taxonomies
Use this method to retrieve a list of taxonomies. If you don't specify any filtering parameters, you will retrieve all available taxonomies.
curl --location --request GET <BASE_URL>/api/content/v1/taxonomies' \
--header 'Accept: text/plain' \
--header 'Authorization: <BEARER_TOKEN>'
{
"totalCount": 4,
"pageSize": 20,
"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": "[email protected]",
"uri": "<Base_URL>/api/content/v1/users/[email protected]"
},
"createdAt": "2023-06-08T17:43:00.4788128Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": " <Base_URL>/api/content/v1/users/[email protected]"
},
"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": "[email protected]",
"uri": "<Base_URL>/api/content/v1/users/[email protected]"
},
"createdAt": "2023-06-08T18:21:08.362753Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": "<Base_URL>/api/content/v1/users/[email protected]"
},
"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": "[email protected]",
"uri": "<Base_URL>/api/content/v1/users/[email protected]"
},
"createdAt": "2023-06-09T14:34:23.1493095Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": "<Base_URL>/api/content/v1/users/[email protected]"
},
"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": "[email protected]",
"uri": "<Base_URL>/api/content/v1/users/[email protected]"
},
"createdAt": "2023-06-11T21:16:53.1717766Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": " <Base_URL>/api/content/v1/users/[email protected]"
},
"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. This request returns a taxonomy with the ID hotels and associated taxonomy values.
curl --location <BASE_URL>/api/content/v1/taxonomies/hotels' \
--header 'Authorization: <BEARER_TOKEN>'
{
"id": "hotels",
"taxonomy": null,
"name": {
"en-US": "hotels"
},
"values": [
{
"id": "luxury",
"name": {
"en-US": "luxury"
}
},
{
"id": "economy",
"name": {
"en-US": "economy"
}
}
],
}
}
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. This request creates a taxonomy called MealPlan with four taxonomy values (Breakfast, Lunch, Dinner, and allMeals).
curl --location <BASE_URL>/api/content/v1/taxonomies' \
--header 'Content-Type: application/json' \
--header 'Authorization: <BEARER_TOKEN>' \
--data '{
"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"
}
}
]
}'
{
"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": "[email protected]",
"uri": "<Base_URL>/api/content/v1/users/[email protected]"
},
"createdAt": "2023-06-22T16:53:17.4993418Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": "<Base_URL>/api/content/v1/users/[email protected]"
},
"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. This request updates a taxonomy with the ID vacationType by adding another value to the list called Pet friendly.
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.
curl --location --request PUT '<Base_URL>/api/content/v1/taxonomies/vacationType' \
--header 'Content-Type: application/json' \
--header 'Authorization: <BEARER_TOKEN>' \
--data-raw '{
"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"
}
},
],
}
}'
{
"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": "[email protected]",
"uri": " <Base_URL> /api/content/v1/users/[email protected]"
},
"createdAt": "2023-06-08T17:43:00.4788128Z",
"updatedBy": {
"type": "Link",
"relatedType": "User",
"id": "[email protected]",
"uri": " <Base_URL> /api/content/v1/users/[email protected]"
},
"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. This request deletes a taxonomy with the taxonomy ID rating.
curl --location --request DELETE <BASE_URL>/api/content/v1/taxonomies/rating' \
--header 'Authorization: <BEARER_TOKEN>'