Taxonomy
Taxonomy
The Taxonomy class creates, reads, updates, and deletes the taxonomies of a stack. It also localizes, imports, and exports them, and opens the terms of one taxonomy.
When to Use This Class: Use this class when your code builds or maintains the hierarchy that entries use for classification. For example, import a product category tree from a file.
Conceptual Role: Acts as the Content Management API (CMA) client for the /taxonomies endpoint. Call stack.Taxonomy() to get an instance, and call Terms on it to reach the Term class.
Returns: Taxonomy. A handle for taxonomy operations.
Instance State
The UID you pass to stack.Taxonomy() decides which methods you can call on the instance:
- Call stack.Taxonomy() without a UID to work with the taxonomy collection, for example Query or Import.
- Call stack.Taxonomy("<TAXONOMY_UID>") to work with one taxonomy, for example Fetch or Terms.
The Method Index below lists every method in each group.
If you call a method from the other group, it throws before any request leaves the SDK. A collection method on an instance with a UID throws InvalidOperationException, and a single-taxonomy method on an instance with no UID throws ArgumentException.
Warning The SDK checks an empty string as if it were no UID, but it builds the request path from the string you pass. stack.Taxonomy("") therefore allows Create, Query, and Import, and sends them to /taxonomies/ instead of /taxonomies. Pass null, or call stack.Taxonomy() with no argument, when you mean the collection.
Warning Set the taxonomy UID only through stack.Taxonomy("<TAXONOMY_UID>"). The instance also has a settable Uid property, but the SDK builds the request path when you call stack.Taxonomy(). Setting Uid later changes which methods the SDK allows without changing which taxonomy the request targets.
Class-Level Notes
Authentication.
- stack.Taxonomy() throws InvalidOperationException when the client has no authtoken and the Stack has no management token, and when the Stack has no API key.
- The CMA reference lists both the authtoken and the management token (authorization) for every taxonomy request except Delete a taxonomy, which lists only the authtoken.
- When the Stack has a management token, the SDK sends it instead of the client's authtoken.
Locale.
- Every method that reads or writes taxonomy content works on the master locale unless you add a locale parameter to collection.
- Localize is the exception: the API requires locale on that request.
Branch.
- The branchUid argument of client.Stack() adds a branch header to every request from that Stack. The CMA reference uses the header to pick the branch whose locale fallback hierarchy applies when you pass include_fallback.
Errors and responses.
- The SDK throws ContentstackErrorException when the API returns an error status. Read StatusCode, ErrorCode, ErrorMessage, and Errors on the exception to see what the API rejected.
- Every request method returns the raw API response as a ContentstackResponse. Read the body with OpenJsonObjectResponse(), or deserialize it with OpenTResponse<T>() into a class that holds a TaxonomyModel.
- Each async method runs its client-side checks when you call it and throws before it returns a task. await every async method so that a catch (ContentstackErrorException) block receives API errors.
Rate Limiting & Retry.
- This SDK automatically retries on 429 with configurable delay and attempt limits.
Additional Resource For more information on retry limits and delays, refer to the ContentstackClientOptions documentation.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Publish or unpublish a taxonomy | No | The SDK has no method for the Publish a taxonomy request. |
| Remove the localized version of a taxonomy | No dedicated method | The CMA Unlocalize a taxonomy request is a DELETE on the same path as Delete, with a locale query parameter. |
| Return every taxonomy in one call | No | Page through the list with the Limit and Skip methods of the Query result. |
| Create terms in the same call as the taxonomy | No | Create the taxonomy, then call Terms and create each term, or Import a file that holds the taxonomy and its terms. |
Method Index
The groups below follow the Instance State split.
Work with the taxonomy collection. Available on stack.Taxonomy() when you pass no UID.
| Method Name | Returns | Description |
|---|---|---|
| Query | A new query for taxonomies. | Builds a query that lists the taxonomies of the stack. |
| Create | The API response with the created taxonomy. | Creates a taxonomy. |
| CreateAsync | The API response with the created taxonomy. | Creates a taxonomy asynchronously. |
| Import | The API response with the imported taxonomy. | Imports a taxonomy and its terms from a JSON or CSV file. |
| ImportAsync | The API response with the imported taxonomy. | Imports a taxonomy file asynchronously. |
Work with one taxonomy. Available on stack.Taxonomy("<TAXONOMY_UID>").
| Method Name | Returns | Description |
|---|---|---|
| Fetch | The API response with the requested taxonomy. | Retrieves one taxonomy. |
| FetchAsync | The API response with the requested taxonomy. | Retrieves one taxonomy asynchronously. |
| Update | The API response with the updated taxonomy. | Updates the name or description of a taxonomy. |
| UpdateAsync | The API response with the updated taxonomy. | Updates a taxonomy asynchronously. |
| Delete | The API response for the deletion. | Deletes a taxonomy and all its terms. |
| DeleteAsync | The API response for the deletion. | Deletes a taxonomy asynchronously. |
| Export | The API response with the exported taxonomy file. | Exports a taxonomy and its terms as JSON or CSV. |
| ExportAsync | The API response with the exported taxonomy file. | Exports a taxonomy asynchronously. |
| Locales | The API response with the localized versions of the taxonomy. | Lists the locales a taxonomy has versions in. |
| LocalesAsync | The API response with the localized versions of the taxonomy. | Lists the localized versions asynchronously. |
| Localize | The API response with the localized taxonomy. | Adds or updates a taxonomy version in another locale. |
| LocalizeAsync | The API response with the localized taxonomy. | Localizes a taxonomy asynchronously. |
| Terms | A new term object. | Opens the terms of this taxonomy, or one term. |
Class-Level Snippet
The snippet below creates a taxonomy, adds a root term to it, and lists the taxonomies of the stack with a total count.
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Stack stack = client.Stack("<API_KEY>");
try
{
TaxonomyModel taxonomy = new TaxonomyModel
{
Uid = "product_category",
Name = "Product Category",
Description = "Categories for the product catalog"
};
stack.Taxonomy().Create(taxonomy);
TermModel term = new TermModel { Uid = "footwear", Name = "Footwear" };
stack.Taxonomy("product_category").Terms().Create(term);
ContentstackResponse list = stack.Taxonomy().Query().IncludeCount().Find();
JsonObject json = list.OpenJsonObjectResponse();
Console.WriteLine($"Taxonomies in the stack: {json["count"]}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects a request, for example a duplicate taxonomy UID
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Methods
Each method of the Taxonomy class has its own section below, with its parameters, validation rules, behavior, and examples.
Create
Create creates a taxonomy in the stack from the details in a TaxonomyModel.
| Name | Type | Description |
|---|---|---|
| model (required) | TaxonomyModel | UID, name, and description of the new taxonomy. |
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: ContentstackResponse. The API response with the created taxonomy.
Validation
- Throws InvalidOperationException if the instance has a taxonomy UID, because Create adds a taxonomy to the collection. Call stack.Taxonomy() with no UID.
- Throws ArgumentNullException (parameter dataModel) if model is null, because the request body comes from the model.
- The SDK does not check the fields of model. A missing name or a UID that another taxonomy uses reaches the API and fails there.
- collection set to null sends no query parameters.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one POST request to /taxonomies with the body { "taxonomy": { ... } }. See Create a taxonomy in the Content Management API reference.
- Serializes only the properties of model that are not null. The fields the API sets, such as TermsCount and CreatedAt, stay out of the body when you leave them unset.
- Creates the taxonomy without terms. Call Terms on the new taxonomy to add terms, or use the Import method to create a taxonomy and its terms from one file.
- Returns the raw API response. The new taxonomy sits under the taxonomy key.
Example
Basic usage: create a taxonomy
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
TaxonomyModel model = new TaxonomyModel
{
Uid = "product_category",
Name = "Product Category"
};
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy().Create(model);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"Created taxonomy {json["taxonomy"]?["uid"]}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: create a taxonomy with a description and query parameters
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
TaxonomyModel model = new TaxonomyModel
{
Uid = "region",
Name = "Region",
Description = "Sales regions for regional content"
};
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy().Create(model, collection);
Console.WriteLine((int)response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: calling Create on an instance with a UID throws
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
TaxonomyModel model = new TaxonomyModel { Uid = "product_category", Name = "Product Category" };
try
{
// The UID belongs in the model, not in stack.Taxonomy().
client.Stack("<API_KEY>").Taxonomy("product_category").Create(model);
}
catch (InvalidOperationException e)
{
// Fires before any request, because Create needs the collection instance
Console.WriteLine(e.Message);
}CreateAsync
CreateAsync creates a taxonomy in the stack from the details in a TaxonomyModel, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | TaxonomyModel | UID, name, and description of the new taxonomy. |
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: Task<ContentstackResponse>. The API response with the created taxonomy.
Validation
- Throws InvalidOperationException if the instance has a taxonomy UID, because CreateAsync adds a taxonomy to the collection. Call stack.Taxonomy() with no UID.
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token. CreateAsync runs this check itself, and Create does not.
- Throws ArgumentNullException (parameter dataModel) if model is null.
- The SDK throws the exceptions above when you call CreateAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same POST request as Create and completes the task when the API responds.
- Otherwise behaves like Create.
Example
Basic usage: create a taxonomy
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
TaxonomyModel model = new TaxonomyModel
{
Uid = "product_category",
Name = "Product Category"
};
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Taxonomy().CreateAsync(model);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"Created taxonomy {json["taxonomy"]?["uid"]}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: create a taxonomy with a description and query parameters
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
TaxonomyModel model = new TaxonomyModel
{
Uid = "region",
Name = "Region",
Description = "Sales regions for regional content"
};
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy().CreateAsync(model, collection);
Console.WriteLine((int)response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Delete
Delete deletes the taxonomy whose UID you passed to stack.Taxonomy(), together with all its terms.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters. Pass force=true to confirm deletion. |
Returns: ContentstackResponse. The API response for the deletion.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Delete removes one taxonomy. Call stack.Taxonomy("<TAXONOMY_UID>").
- The SDK does not add force=true for you. The API reference lists force as a required query parameter that confirms the deletion, so pass it in collection.
- The API reference lists only the authtoken header for this request. Call Delete on a Stack without a management token.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one DELETE request to /taxonomies/<TAXONOMY_UID>, with the entries of collection as query parameters. See Delete a taxonomy in the Content Management API reference.
- The API deletes the taxonomy and every term in it. It also removes the taxonomy from the content types that use it, and removes its terms from the entries that carry them.
- The API reference lists a 204 status for a successful deletion, so the response has no body to read.
Warning Deleting a taxonomy is irreversible. The API removes the taxonomy, all its terms, and every association between those terms and your entries and content types. Export the taxonomy first with the Export method if you need a copy.
Example
Basic usage: delete a taxonomy
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("force", true);
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Delete(collection);
Console.WriteLine($"Deleted: {(int)response.StatusCode}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Edge case: export a taxonomy before you delete it
using System;
using System.IO;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Taxonomy taxonomy = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>");
try
{
ContentstackResponse export = taxonomy.Export();
File.WriteAllText("<FILE_PATH>", export.OpenResponse());
ParameterCollection collection = new ParameterCollection();
collection.Add("force", true);
taxonomy.Delete(collection);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}DeleteAsync
DeleteAsync deletes the taxonomy whose UID you passed to stack.Taxonomy(), together with all its terms, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters. Pass force=true to confirm deletion. |
Returns: Task<ContentstackResponse>. The API response for the deletion.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because DeleteAsync removes one taxonomy. The SDK throws it when you call DeleteAsync, before it returns a task.
- The SDK does not add force=true for you. Pass it in collection.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same DELETE request as Delete and completes the task when the API responds.
- Otherwise behaves like Delete.
Warning Deleting a taxonomy is irreversible. The API removes the taxonomy, all its terms, and every association between those terms and your entries and content types.
Example
Basic usage: delete a taxonomy
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("force", true);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").DeleteAsync(collection);
Console.WriteLine($"Deleted: {(int)response.StatusCode}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Edge case: delete several taxonomies in a row
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Stack stack = client.Stack("<API_KEY>");
foreach (string uid in new[] { "<TAXONOMY_UID>", "<OTHER_TAXONOMY_UID>" })
{
// A parameter collection rejects duplicate keys, so build one per request.
ParameterCollection collection = new ParameterCollection();
collection.Add("force", true);
try
{
await stack.Taxonomy(uid).DeleteAsync(collection);
Console.WriteLine($"Deleted {uid}");
}
catch (ContentstackErrorException e)
{
Console.WriteLine($"{uid}: {e.ErrorMessage}");
}
}Export
Export returns the taxonomy whose UID you passed to stack.Taxonomy(), together with its terms, as a JSON or CSV file.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example format and locale. |
Returns: ContentstackResponse. The API response with the exported taxonomy file.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Export reads one taxonomy. Call stack.Taxonomy("<TAXONOMY_UID>").
- collection set to null sends no query parameters, and the API returns the master locale version in JSON.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one GET request to /taxonomies/<TAXONOMY_UID>/export, with the entries of collection as query parameters. See Export a taxonomy in the Content Management API reference.
- The API reference lists two query parameters for the request:
- format sets the file format. The API returns JSON unless you pass csv.
- locale exports that locale version. Without it, the API exports the master locale version.
- The response body is the file content. Read it as text with OpenResponse() and write it to a file yourself. The SDK does not save the file.
Example
Basic usage: export a taxonomy as JSON
using System;
using System.IO;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Export();
File.WriteAllText("<FILE_PATH>", response.OpenResponse());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: export the French version as CSV
using System;
using System.IO;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
ParameterCollection collection = new ParameterCollection();
collection.Add("format", "csv");
collection.Add("locale", "fr-fr");
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Export(collection);
File.WriteAllText("<FILE_PATH>", response.OpenResponse());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}ExportAsync
ExportAsync returns the taxonomy whose UID you passed to stack.Taxonomy(), together with its terms, as a JSON or CSV file, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example format and locale. |
Returns: Task<ContentstackResponse>. The API response with the exported taxonomy file.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because ExportAsync reads one taxonomy. The SDK throws it when you call ExportAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same GET request as Export and completes the task when the API responds.
- Otherwise behaves like Export.
Example
Basic usage: export a taxonomy as JSON
using System;
using System.IO;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").ExportAsync();
await File.WriteAllTextAsync("<FILE_PATH>", response.OpenResponse());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: export the French version as CSV
using System;
using System.IO;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
ParameterCollection collection = new ParameterCollection();
collection.Add("format", "csv");
collection.Add("locale", "fr-fr");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").ExportAsync(collection);
await File.WriteAllTextAsync("<FILE_PATH>", response.OpenResponse());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Fetch
Fetch retrieves the details of the taxonomy whose UID you passed to stack.Taxonomy().
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example locale. |
Returns: ContentstackResponse. The API response with the requested taxonomy.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Fetch reads one taxonomy. Call stack.Taxonomy("<TAXONOMY_UID>").
- The SDK does not check the UID format. A UID that names no taxonomy reaches the API, and the SDK throws the rejection as ContentstackErrorException.
- collection set to null sends no query parameters.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one GET request to /taxonomies/<TAXONOMY_UID>, with the entries of collection as query parameters. See Get a single taxonomy in the Content Management API reference.
- The API reference lists these query parameters for the request:
- locale reads the taxonomy in that locale. Without it, the API returns the master locale version.
- include_fallback set to true returns the version from the fallback locale when the taxonomy has no version in locale.
- include_terms_count, include_referenced_terms_count, and include_referenced_entries_count set to true add those counts to the response.
- Returns the raw API response. The taxonomy sits under the taxonomy key and holds the fields that TaxonomyModel describes.
Example
Basic usage: fetch a taxonomy by UID
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Fetch();
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"Taxonomy name: {json["taxonomy"]?["name"]}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: fetch the French version with term counts
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "fr-fr");
collection.Add("include_fallback", true);
collection.Add("include_terms_count", true);
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Fetch(collection);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"{json["taxonomy"]?["name"]} has {json["taxonomy"]?["terms_count"]} terms");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Management token: read the response into TaxonomyModel
using System;
using System.Text.Json;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient();
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Fetch();
// The taxonomy sits under the "taxonomy" key, so deserialize that node, not the whole body.
TaxonomyModel? taxonomy = response.OpenJsonObjectResponse()["taxonomy"]?.Deserialize<TaxonomyModel>();
Console.WriteLine($"{taxonomy?.Uid}: {taxonomy?.Name}, updated {taxonomy?.UpdatedAt}");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}FetchAsync
FetchAsync retrieves the details of the taxonomy whose UID you passed to stack.Taxonomy(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example locale. |
Returns: Task<ContentstackResponse>. The API response with the requested taxonomy.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because FetchAsync reads one taxonomy. The SDK throws it when you call FetchAsync, before it returns a task.
- collection set to null sends no query parameters.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same GET request as Fetch and completes the task when the API responds.
- Otherwise behaves like Fetch.
Example
Basic usage: fetch a taxonomy by UID
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").FetchAsync();
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"Taxonomy name: {json["taxonomy"]?["name"]}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: fetch the French version with term counts
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "fr-fr");
collection.Add("include_fallback", true);
collection.Add("include_terms_count", true);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").FetchAsync(collection);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"{json["taxonomy"]?["name"]} has {json["taxonomy"]?["terms_count"]} terms");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Import
Import creates a taxonomy and its terms in the stack from a JSON or CSV file.
| Name | Type | Description |
|---|---|---|
| model (required) | [TaxonomyImportModel](../../TaxonomyImportModel/class_reference.md) | The taxonomy file to upload. |
| collection | ParameterCollection? | Adds query parameters, for example locale. |
Returns: ContentstackResponse. The API response with the imported taxonomy.
Validation
- Throws InvalidOperationException if the instance has a taxonomy UID, because Import adds a taxonomy to the collection. Call stack.Taxonomy() with no UID.
- Throws ArgumentNullException (parameter uploadInterface) if model is null.
- The TaxonomyImportModel constructor checks the file before Import runs. See TaxonomyImportModel for the exceptions it throws.
- The SDK does not read or check the file content. A file in a shape the API does not accept reaches the API and fails there.
- Throws ContentstackErrorException when the API rejects the request, for example when the file holds a taxonomy UID that the stack already has.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one POST request to /taxonomies/import as multipart/form-data, with the file in a form field named taxonomy. See Import a taxonomy in the Content Management API reference.
- Sends the entries of collection as query parameters. The API reference lists locale as the target locale of the import. Without it, the API imports into the master locale.
- Returns the raw API response. The imported taxonomy sits under the taxonomy key. The API reference states that the response reports the number of imported terms in terms_count instead of listing the terms.
- Reads the stream of model from its current position to the end and does not close it. A TaxonomyImportModel therefore serves one Import call. Create a new one for each request.
Example
Basic usage: import a taxonomy from a file
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
TaxonomyImportModel model = new TaxonomyImportModel("<FILE_PATH>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy().Import(model);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"Imported {json["taxonomy"]?["uid"]} with {json["taxonomy"]?["terms_count"]} terms");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: import a JSON taxonomy from memory into a locale
using System;
using System.IO;
using System.Text;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
string json = "{\"taxonomy\":{\"uid\":\"region\",\"name\":\"Region\",\"description\":\"Sales regions\"}}";
using MemoryStream stream = new MemoryStream(Encoding.UTF8.GetBytes(json));
TaxonomyImportModel model = new TaxonomyImportModel(stream, "taxonomy.json");
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "en-us");
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy().Import(model, collection);
Console.WriteLine((int)response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: close the file after the import
using System;
using System.IO;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
// Open the file yourself so that the using block closes it after the request.
using FileStream file = File.OpenRead("<FILE_PATH>");
TaxonomyImportModel model = new TaxonomyImportModel(file, Path.GetFileName("<FILE_PATH>"));
try
{
client.Stack("<API_KEY>").Taxonomy().Import(model);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}ImportAsync
ImportAsync creates a taxonomy and its terms in the stack from a JSON or CSV file, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | [TaxonomyImportModel](../../TaxonomyImportModel/class_reference.md) | The taxonomy file to upload. |
| collection | ParameterCollection? | Adds query parameters, for example locale. |
Returns: Task<ContentstackResponse>. The API response with the imported taxonomy.
Validation
- Throws InvalidOperationException if the instance has a taxonomy UID, because ImportAsync adds a taxonomy to the collection. Call stack.Taxonomy() with no UID.
- Throws ArgumentNullException (parameter uploadInterface) if model is null.
- The SDK throws the exceptions above when you call ImportAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same POST request as Import and completes the task when the API responds.
- Keep the stream of model open until the task completes, because the SDK reads it while it sends the request.
- Otherwise behaves like Import.
Example
Basic usage: import a taxonomy from a file
using System;
using System.IO;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
using FileStream file = File.OpenRead("<FILE_PATH>");
TaxonomyImportModel model = new TaxonomyImportModel(file, Path.GetFileName("<FILE_PATH>"));
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Taxonomy().ImportAsync(model);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"Imported {json["taxonomy"]?["uid"]} with {json["taxonomy"]?["terms_count"]} terms");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: import a JSON taxonomy from memory into a locale
using System;
using System.IO;
using System.Text;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
string json = "{\"taxonomy\":{\"uid\":\"region\",\"name\":\"Region\",\"description\":\"Sales regions\"}}";
using MemoryStream stream = new MemoryStream(Encoding.UTF8.GetBytes(json));
TaxonomyImportModel model = new TaxonomyImportModel(stream, "taxonomy.json");
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "en-us");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy().ImportAsync(model, collection);
Console.WriteLine((int)response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Locales
Locales lists the localized versions of the taxonomy whose UID you passed to stack.Taxonomy().
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: ContentstackResponse. The API response with the localized versions of the taxonomy.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Locales reads one taxonomy. Call stack.Taxonomy("<TAXONOMY_UID>").
- collection set to null sends no query parameters.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one GET request to /taxonomies/<TAXONOMY_UID>/locales, with the entries of collection as query parameters.
- The Content Management API reference lists no request for this path, so it documents no query parameters or response shape for it.
- Returns the raw API response. Read it with OpenJsonObjectResponse() and check the keys before you rely on them.
Example
Basic usage: list the localized versions of a taxonomy
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Locales();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: pass query parameters with a management token
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Locales(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}LocalesAsync
LocalesAsync lists the localized versions of the taxonomy whose UID you passed to stack.Taxonomy(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: Task<ContentstackResponse>. The API response with the localized versions of the taxonomy.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because LocalesAsync reads one taxonomy. The SDK throws it when you call LocalesAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same GET request as Locales and completes the task when the API responds.
- Otherwise behaves like Locales.
Example
Basic usage: list the localized versions of a taxonomy
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").LocalesAsync();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: pass query parameters with a management token
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").LocalesAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Localize
Localize adds a version of the taxonomy whose UID you passed to stack.Taxonomy() in another locale, with translated values from a TaxonomyModel.
| Name | Type | Description |
|---|---|---|
| model (required) | TaxonomyModel | Translated name and description for the locale. |
| collection | ParameterCollection? | Query parameters. Pass locale to name the target locale. |
Returns: ContentstackResponse. The API response with the localized taxonomy.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Localize writes one taxonomy. Call stack.Taxonomy("<TAXONOMY_UID>").
- Throws ArgumentNullException (parameter dataModel) if model is null, because the request body comes from the model.
- The SDK does not require locale. The API reference lists locale as a required query parameter, so a collection that is null or has no locale reaches the API and fails there.
- Throws ContentstackErrorException when the API rejects the request, for example for a locale code that the stack does not have.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one POST request to /taxonomies/<TAXONOMY_UID> with the body { "taxonomy": { ... } } and the entries of collection as query parameters. See Localize a taxonomy in the Content Management API reference.
- Serializes only the properties of model that are not null. Set the translated Name and Description.
- Leaves the master locale version unchanged. To change an existing localized version, call Update with the same locale parameter.
- Returns the raw API response. The localized taxonomy sits under the taxonomy key.
Limitations
- Does not remove a localized version. The SDK has no method for the Unlocalize a taxonomy request.
Example
Basic usage: add a French version of a taxonomy
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
TaxonomyModel model = new TaxonomyModel
{
Name = "Catégorie de produit",
Description = "Catégories du catalogue de produits"
};
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "fr-fr");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Localize(model, collection);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"{json["taxonomy"]?["locale"]}: {json["taxonomy"]?["name"]}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Management token: localize a taxonomy for a locale from a variable
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
string localeCode = "<LOCALE_CODE>";
TaxonomyModel model = new TaxonomyModel { Name = "<TRANSLATED_NAME>" };
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", localeCode);
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Localize(model, collection);
Console.WriteLine((int)response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: a call without locale fails at the API
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
TaxonomyModel model = new TaxonomyModel { Name = "Catégorie de produit" };
try
{
// No collection, so the request carries no locale parameter.
client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Localize(model);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}LocalizeAsync
LocalizeAsync adds a version of the taxonomy whose UID you passed to stack.Taxonomy() in another locale, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | TaxonomyModel | Translated name and description for the locale. |
| collection | ParameterCollection? | Query parameters. Pass locale to name the target locale. |
Returns: Task<ContentstackResponse>. The API response with the localized taxonomy.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because LocalizeAsync writes one taxonomy.
- Throws ArgumentNullException (parameter dataModel) if model is null.
- The SDK throws the exceptions above when you call LocalizeAsync, before it returns a task.
- The SDK does not require locale. The API rejects a request without it.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same POST request as Localize and completes the task when the API responds.
- Otherwise behaves like Localize.
Example
Basic usage: add a French version of a taxonomy
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
TaxonomyModel model = new TaxonomyModel
{
Name = "Catégorie de produit",
Description = "Catégories du catalogue de produits"
};
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "fr-fr");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").LocalizeAsync(model, collection);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"{json["taxonomy"]?["locale"]}: {json["taxonomy"]?["name"]}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Management token: localize a taxonomy for a locale from a variable
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
string localeCode = "<LOCALE_CODE>";
TaxonomyModel model = new TaxonomyModel { Name = "<TRANSLATED_NAME>" };
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", localeCode);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").LocalizeAsync(model, collection);
Console.WriteLine((int)response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Query
Query returns a query object that lists the taxonomies of the stack when you call Find or FindAsync on it.
This method takes no parameters. Chain Limit, Skip, and IncludeCount on the query object to page through the results, then call Find or FindAsync to send the request.
Returns: Query. A new query for taxonomies.
Validation
- Throws InvalidOperationException if the instance has a taxonomy UID, because Query lists the taxonomy collection. Call stack.Taxonomy() with no UID.
- Query sends no request. Errors that do occur come from the Find or FindAsync call that follows, not from Query.
- Limit, Skip, and IncludeCount each add a query parameter, and the SDK stores parameters in a dictionary that rejects duplicate keys. Two cases throw ArgumentException before any request:
- chaining the same method twice
- passing a key in the Find collection that a chained method already set
- A query object keeps every parameter it has sent. If you call Find or FindAsync on it again with a collection that repeats one of those keys, it throws ArgumentException. Build a new query with stack.Taxonomy().Query() for each request.
- Find and FindAsync throw ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Find and FindAsync send one GET request to /taxonomies, with every parameter you set as a query parameter. See Get all taxonomies in the Content Management API reference.
- The API reference lists more query parameters for the request than the three chained methods set. Pass them in the Find collection, for example:
- locale and include_fallback to read the taxonomies in another locale
- include_terms_count, include_referenced_terms_count, and include_referenced_entries_count to add counts to each taxonomy
- deleted set to true to list only deleted taxonomies
- typeahead to match taxonomies by a search string, and asc or desc to sort
- Returns the raw API response. The taxonomies sit under the taxonomies key, and count holds the total when you call IncludeCount.
- Does not page through the results for you. Without Limit and Skip, the API applies its own page size. To read the next page, build a new query and pass a higher Skip value.
The query object has five methods:
| Method | Type | Description |
|---|---|---|
| Limit(double value) | Query | Sets the number of taxonomies per page. |
| Skip(double value) | Query | Sets the number of taxonomies to skip. |
| IncludeCount() | Query | Adds the total taxonomy count. |
| Find(ParameterCollection? collection = null) | ContentstackResponse | Sends the request and returns the taxonomies. |
| FindAsync(ParameterCollection? collection = null) | Task<ContentstackResponse> | Sends the request without blocking the thread. |
Example
Basic usage: list the taxonomies of a stack
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy().Query().Find();
JsonArray? taxonomies = response.OpenJsonObjectResponse()["taxonomies"]?.AsArray();
foreach (JsonNode? taxonomy in taxonomies ?? new JsonArray())
{
Console.WriteLine($"{taxonomy?["uid"]}: {taxonomy?["name"]}");
}
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Paging: read one page of taxonomies with term counts
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
ParameterCollection collection = new ParameterCollection();
collection.Add("include_terms_count", true);
try
{
ContentstackResponse response = await client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.Taxonomy()
.Query()
.Limit(10)
.Skip(0)
.IncludeCount()
.FindAsync(collection);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"Showing {json["taxonomies"]?.AsArray().Count} of {json["count"]} taxonomies");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: setting a query parameter twice throws
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Query query = client.Stack("<API_KEY>").Taxonomy().Query().Limit(5);
ParameterCollection collection = new ParameterCollection();
collection.Add("limit", 10);
try
{
// "limit" is already set by Limit(5), so adding it again fails.
query.Find(collection);
}
catch (ArgumentException e)
{
// Fires before any request, when a query parameter is set twice
Console.WriteLine(e.Message);
}Terms
Terms returns a Term object for the terms of the taxonomy whose UID you passed to stack.Taxonomy(), or for one term in it.
| Name | Type | Description |
|---|---|---|
| termUid | string? | UID of one term. Omit it to work with all terms. |
Returns: Term. A new term object.
Validation
- Throws ArgumentException (parameter uid) if the taxonomy instance has no UID or an empty string, because every term belongs to one taxonomy. Call stack.Taxonomy("<TAXONOMY_UID>").Terms().
- Terms sends no request. Errors from the API come from the method you call on the returned object.
- The SDK does not check whether the taxonomy or the term exists. An unknown UID fails at the API on the first request.
Behavior
- Returns a new Term object on each call. The object targets /taxonomies/<TAXONOMY_UID>/terms, or /taxonomies/<TAXONOMY_UID>/terms/<TERM_UID> when you pass termUid.
- termUid decides which Term methods you can call:
- Without termUid, or with null or an empty string, the object works with the term collection, for example Query and Create.
- With termUid, the object works with one term, for example Fetch and Move.
Example
Basic usage: list the terms of a taxonomy
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
Term terms = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms();
ContentstackResponse response = terms.Query().Find();
Console.WriteLine($"Terms: {response.OpenJsonObjectResponse()["terms"]?.AsArray().Count}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: fetch one term of a taxonomy
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient();
try
{
Term term = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>");
ContentstackResponse response = term.Fetch();
Console.WriteLine($"Term name: {response.OpenJsonObjectResponse()["term"]?["name"]}");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: calling Terms on the taxonomy collection throws
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
client.Stack("<API_KEY>").Taxonomy().Terms();
}
catch (ArgumentException e)
{
// Fires before any request, because the taxonomy instance has no UID
Console.WriteLine(e.Message);
}Update
Update changes the name or description of the taxonomy whose UID you passed to stack.Taxonomy().
| Name | Type | Description |
|---|---|---|
| model (required) | TaxonomyModel | New values for the taxonomy fields. |
| collection | ParameterCollection? | Adds query parameters, for example locale. |
Returns: ContentstackResponse. The API response with the updated taxonomy.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Update changes one taxonomy. Call stack.Taxonomy("<TAXONOMY_UID>").
- Throws ArgumentNullException (parameter dataModel) if model is null, because the request body comes from the model.
- collection set to null sends no query parameters.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one PUT request to /taxonomies/<TAXONOMY_UID> with the body { "taxonomy": { ... } }. See Update a taxonomy in the Content Management API reference.
- Serializes only the properties of model that are not null. Set only the fields you change, for example Name and Description.
- Updates the master locale version unless collection holds a locale parameter. The API reference lists locale as the locale in which the API updates the taxonomy.
- Returns the raw API response. The updated taxonomy sits under the taxonomy key.
Example
Basic usage: rename a taxonomy
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
TaxonomyModel model = new TaxonomyModel { Name = "Product Categories" };
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Update(model);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"New name: {json["taxonomy"]?["name"]}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: update the description of the French version
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
TaxonomyModel model = new TaxonomyModel
{
Name = "Catégorie de produit",
Description = "Catégories du catalogue"
};
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "fr-fr");
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Update(model, collection);
Console.WriteLine((int)response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}UpdateAsync
UpdateAsync changes the name or description of the taxonomy whose UID you passed to stack.Taxonomy(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | TaxonomyModel | New values for the taxonomy fields. |
| collection | ParameterCollection? | Adds query parameters, for example locale. |
Returns: Task<ContentstackResponse>. The API response with the updated taxonomy.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token. UpdateAsync runs this check itself, and Update does not.
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because UpdateAsync changes one taxonomy.
- Throws ArgumentNullException (parameter dataModel) if model is null.
- The SDK throws the exceptions above when you call UpdateAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same PUT request as Update and completes the task when the API responds.
- Otherwise behaves like Update.
Example
Basic usage: rename a taxonomy
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
TaxonomyModel model = new TaxonomyModel { Name = "Product Categories" };
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").UpdateAsync(model);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"New name: {json["taxonomy"]?["name"]}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: update the description of the French version
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
TaxonomyModel model = new TaxonomyModel
{
Name = "Catégorie de produit",
Description = "Catégories du catalogue"
};
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "fr-fr");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").UpdateAsync(model, collection);
Console.WriteLine((int)response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}