# Taxonomies operations
## Overview
Classifications are used to organize content in your website. You can apply them to all Sitefinity CMS content items.
In Sitefinity CMS, there are two types of taxonomies:
* Flat
* Hierarchical
For each type there is a build-in classification in the CMS – *Tags* (flat) and *Categories* (hierarchical). You can also create custom taxonomies to fit your business needs.
## Terminology
* Taxonomy\
A taxonomy is a classification, it can be flat or hierarchical, or built-in or custom.\
For example, *Categories* is a built-in hierarchical taxonomy.
* Taxon\
A taxon is an item or a group of items, which the taxonomist identifies as a separate unit. Taxa is the plural for taxon. A taxonomy contains multiple taxa.\
For example, *Sports* and *Business* can be two taxa from the *Categories* taxonomy, applied to news items.
* TaxonName\
This is the single item name for all taxa in the taxonomy.
For example, in the custom taxonomy *Press releases*, the single item name for the taxa can be *Press release*.
## Create a taxonomy
To create a taxonomy, you must execute a `POST` request to the following endpoint:
`{baseurl}/api/default/taxonomies`
**Sample request**
> info **POST** `http://mysite.com/api/default/taxonomies`
```JSON
{
"Title":"MyCustomFlatTaxonomy",
"TaxonName":"FlatTaxon",
"Type":"0",
"Name":"mycustomflattaxonomy"
}
```
> info **NOTE**: The Type property controls whether the created taxonomy should be flat or hierarchical:
>
> * `0` – creates a flat taxonomy
> * `1` – creates a hierarchical taxonomy
**Sample response**
```JSON
{
"Id": "10f8b2ce-c951-4e55-94b3-96680e0d840e",
"LastModified": "2021-05-12T08:37:35Z",
"Name": "mycustomflattaxonomy",
"Title": "MyCustomFlatTaxonomy",
"Description": "",
"TaxonName": "FlatTaxon",
"RootTaxonomyId": null,
"TaxaUrl": "flat-taxa",
"Type": "Flat",
"DefaultTitle": "MyCustomFlatTaxonomy",
"DefaultTaxonName": "FlatTaxon",
"TaxonomySharedWith": 1
}
```
## Get a collection of taxonomies
To get all classifications, you must execute a `GET` request to the following endpoint:
`{baseurl}/api/default/taxonomies`
**Sample request**
> success **GET** `http://mysite.com/api/default/taxonomies`
**Sample response**
```JSON
{
"value": [
{
"Id": "07f5952f-f983-47ce-baa8-416be0597af7",
"LastModified": "2021-05-12T08:29:55Z",
"Name": "mycustomflattaxonomy",
"Title": "MyCustomFlatTaxonomy",
"Description": "",
"TaxonName": "FlatTaxon",
"RootTaxonomyId": null,
"TaxaUrl": "flat-taxa",
"Type": "Flat",
"DefaultTitle": "MyCustomFlatTaxonomy",
"DefaultTaxonName": "FlatTaxon",
"TaxonomySharedWith": 1
},
{
"Id": "e5cd6d69-1543-427b-ad62-688a99f5e7d4",
"LastModified": "2021-05-10T12:30:05Z",
"Name": "Categories",
"Title": "Categories",
"Description": null,
"TaxonName": "Category",
"RootTaxonomyId": null,
"TaxaUrl": "hierarchy-taxa",
"Type": "Hierarchical",
"DefaultTitle": "Categories",
"DefaultTaxonName": "Category",
"TaxonomySharedWith": 1
},
{
"Id": "cb0f3a19-a211-48a7-88ec-77495c0f5374",
"LastModified": "2021-05-12T06:28:59Z",
"Name": "Tags",
"Title": "Tags",
"Description": null,
"TaxonName": "Tag",
"RootTaxonomyId": null,
"TaxaUrl": "flat-taxa",
"Type": "Flat",
"DefaultTitle": "Tags",
"DefaultTaxonName": "Tag",
"TaxonomySharedWith": 1
}
]
}
```
> info **NOTE**: The request returns both flat and hierarchical taxonomies.
## Create a taxon
To create a taxon, you must execute a `POST` request to the following endpoint:
`{baseurl}/api/default/{taxaUrl}`
Where `{taxaUrl}` is one of the following:
* `flat-taxa` – for creating a flat taxon
* `hierarchy-taxa` – for creating a hierarchical taxon
**Sample request**
> success **POST** `http://mysite.com/api/default/flat-taxa`
```JSON
{
"Title": "MyTaxon",
"UrlName": "mytaxon",
"Name": "MyTaxon",
"TaxonomyId": "07f5952f-f983-47ce-baa8-416be0597af7"
}
```
`TaxonomyId` is the ID of the taxonomy under which the taxon will be created. For example, the ID of `Tags` taxonomy.
> info **NOTE**: If you are creating a taxon, you must add the `ParentId` property to the body of the request. The `ParientId` is the ID of the taxon, under which the current taxon must be added. For example, if you want to add `Tennis` under `Sports`, you must include the ID of Sports taxon. If you want to add the taxon on root level of the taxonomy, set the `ParentId` value to `00000000-0000-0000-0000-000000000000`.
**Sample response**
## Get a collection of taxa
To get all flat or all hierarchical taxa, you must execute a `GET` request to the following endpoint:
`{baseurl}/api/default/{taxaUrl}`
Where `{taxaUrl}` is one of the following:
* `flat-taxa` – for getting all flat taxa
* `hierarchy-taxa` – for getting all hierarchical taxa
**Sample request**
> success **GET** `http://mysite.com/api/default/flat-taxa`
**Sample response**
```JSON
{
"value": [
{
"Id": "71219a80-18ee-47ef-85c8-f7a82fadda95",
"LastModified": "2021-05-12T09:10:07Z",
"Title": " MyTaxon",
"Description": "",
"UrlName": "mytaxon",
"Name": " MyTaxon",
"Synonyms": "",
"TaxonomyId": "07f5952f-f983-47ce-baa8-416be0597af7",
"Ordinal": 0
}
]
}
```
## Set taxon to a content item
Once you have created taxonomies and taxa, you can start relating them to content items.
To apply a taxon to a content item, execute a `PATCH` request to the following endpoint:
`{baseurl}/api/default/{entity}({itemId})`
Where:
* `{entity}` is the entity of the module that the item belongs to
* `{itemId}` is the ID of the item
In the request body, you must pass the name of the taxonomy (built-in or custom), which the taxon you want to apply belongs to, and the ID of the taxon that you want to set to the content item.
**Sample request**
> success **PATCH** `http://mysite.com/api/default/newsitems(3b177186-8b09-497c-8def-58613183d670)`
```JSON
{
"Tags": ["71219a80-18ee-47ef-85c8-f7a82fadda95"]
}
```
> info **NOTE**: The value of the taxon ID property is an array and you can pass multiple taxon IDs.
**Sample response**
No response body