--- title: "Taxonomies" slug: "taxonomies" abstract: "How to use taxonomies to tag and categorize content." --- # Taxonomies A [taxonomy](https://doc.sitecore.com/ch-one/en/users/content-hub-one/content-modeling.html) 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](https://doc.sitecore.com/ch-one/en/developers/content-hub-one/content-management-api/data-model.html#UUID-02356f01-623b-81c7-5313-ab2a9987f7ab_N1710870037322). You can use query attributes to control the set of items returned. Before you start working with taxonomies, you must [authenticate](https://doc.sitecore.com/ch-one/en/developers/content-hub-one/content-management-api/authentication.html "Authentication"). > [!note] > The [base URL](https://doc.sitecore.com/ch-one/en/developers/content-hub-one/content-management-api.html "Content Management API") when working with taxonomies is `https://content-api.sitecorecloud.io/`. For guidance on API syntax, see [Syntax](https://doc.sitecore.com/ch-one/en/developers/content-hub-one/content-management-api/syntax.html "Syntax"). ## Get all taxonomies Use this method to retrieve a list of taxonomies. If you don't specify any [filtering parameters](https://doc.sitecore.com/ch-one/en/developers/content-hub-one/content-management-api/search-and-filter-parameters.html#UUID-01d7a72f-def1-375d-906f-3ef71fdb5351_title-idm273423993491036), you will retrieve all available taxonomies. ```curl curl --location --request GET /api/content/v1/taxonomies' \ --header 'Accept: text/plain' \ --header 'Authorization: ' ``` ```json { "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": "jake.b@sitecore.com", "uri": "/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": " /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": "/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": "/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": "/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": "/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": "/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": " /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](https://doc.sitecore.com/ch-one/en/users/content-hub-one/en/edit-a-taxonomy.html). This request returns a taxonomy with the ID *hotels* and associated taxonomy values. ```curl curl --location /api/content/v1/taxonomies/hotels' \ --header 'Authorization: ' ``` ```json { "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 curl --location /api/content/v1/taxonomies' \ --header 'Content-Type: application/json' \ --header 'Authorization: ' \ --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" } } ] }' ``` ```json { "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": "/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": "/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. This request updates a taxonomy with the ID *vacationType* by adding another value to the list called *Pet friendly*. > [!warning] > 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. ```json curl --location --request PUT '/api/content/v1/taxonomies/vacationType' \ --header 'Content-Type: application/json' \ --header 'Authorization: ' \ --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" } }, ], } }' ``` ```json { "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": " /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": " /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. This request deletes a taxonomy with the taxonomy ID *rating*. ```curl curl --location --request DELETE /api/content/v1/taxonomies/rating' \ --header 'Authorization: ' ```