Taxonomy

View as Markdown

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

CapabilitySupportedNotes / Alternative
Publish or unpublish a taxonomyNoThe SDK has no method for the Publish a taxonomy request.
Remove the localized version of a taxonomyNo dedicated methodThe CMA Unlocalize a taxonomy request is a DELETE on the same path as Delete, with a locale query parameter.
Return every taxonomy in one callNoPage through the list with the Limit and Skip methods of the Query result.
Create terms in the same call as the taxonomyNoCreate 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 NameReturnsDescription
QueryA new query for taxonomies.Builds a query that lists the taxonomies of the stack.
CreateThe API response with the created taxonomy.Creates a taxonomy.
CreateAsyncThe API response with the created taxonomy.Creates a taxonomy asynchronously.
ImportThe API response with the imported taxonomy.Imports a taxonomy and its terms from a JSON or CSV file.
ImportAsyncThe API response with the imported taxonomy.Imports a taxonomy file asynchronously.

Work with one taxonomy. Available on stack.Taxonomy("<TAXONOMY_UID>").

Method NameReturnsDescription
FetchThe API response with the requested taxonomy.Retrieves one taxonomy.
FetchAsyncThe API response with the requested taxonomy.Retrieves one taxonomy asynchronously.
UpdateThe API response with the updated taxonomy.Updates the name or description of a taxonomy.
UpdateAsyncThe API response with the updated taxonomy.Updates a taxonomy asynchronously.
DeleteThe API response for the deletion.Deletes a taxonomy and all its terms.
DeleteAsyncThe API response for the deletion.Deletes a taxonomy asynchronously.
ExportThe API response with the exported taxonomy file.Exports a taxonomy and its terms as JSON or CSV.
ExportAsyncThe API response with the exported taxonomy file.Exports a taxonomy asynchronously.
LocalesThe API response with the localized versions of the taxonomy.Lists the locales a taxonomy has versions in.
LocalesAsyncThe API response with the localized versions of the taxonomy.Lists the localized versions asynchronously.
LocalizeThe API response with the localized taxonomy.Adds or updates a taxonomy version in another locale.
LocalizeAsyncThe API response with the localized taxonomy.Localizes a taxonomy asynchronously.
TermsA 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.

NameTypeDescription
model (required)TaxonomyModel

UID, name, and description of the new taxonomy.

Default: Not applicable
collectionParameterCollection?

Adds query parameters to the request.

Default: null

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.

NameTypeDescription
model (required)TaxonomyModel

UID, name, and description of the new taxonomy.

Default: Not applicable
collectionParameterCollection?

Adds query parameters to the request.

Default: null

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.

NameTypeDescription
collectionParameterCollection?

Adds query parameters. Pass force=true to confirm deletion.

Default: null

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.

NameTypeDescription
collectionParameterCollection?

Adds query parameters. Pass force=true to confirm deletion.

Default: null

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.

NameTypeDescription
collectionParameterCollection?

Adds query parameters, for example format and locale.

Default: null

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.

NameTypeDescription
collectionParameterCollection?

Adds query parameters, for example format and locale.

Default: null

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().

NameTypeDescription
collectionParameterCollection?

Adds query parameters, for example locale.

Default: null

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.

NameTypeDescription
collectionParameterCollection?

Adds query parameters, for example locale.

Default: null

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.

NameTypeDescription
model (required)[TaxonomyImportModel](../../TaxonomyImportModel/class_reference.md)

The taxonomy file to upload.

Default: Not applicable
collectionParameterCollection?

Adds query parameters, for example locale.

Default: null

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.

NameTypeDescription
model (required)[TaxonomyImportModel](../../TaxonomyImportModel/class_reference.md)

The taxonomy file to upload.

Default: Not applicable
collectionParameterCollection?

Adds query parameters, for example locale.

Default: null

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().

NameTypeDescription
collectionParameterCollection?

Adds query parameters to the request.

Default: null

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.

NameTypeDescription
collectionParameterCollection?

Adds query parameters to the request.

Default: null

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.

NameTypeDescription
model (required)TaxonomyModel

Translated name and description for the locale.

Default: Not applicable
collectionParameterCollection?

Query parameters. Pass locale to name the target locale.

Default: null

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

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.

NameTypeDescription
model (required)TaxonomyModel

Translated name and description for the locale.

Default: Not applicable
collectionParameterCollection?

Query parameters. Pass locale to name the target locale.

Default: null

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:

MethodTypeDescription
Limit(double value)QuerySets the number of taxonomies per page.
Skip(double value)QuerySets the number of taxonomies to skip.
IncludeCount()QueryAdds the total taxonomy count.
Find(ParameterCollection? collection = null)ContentstackResponseSends 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.

NameTypeDescription
termUidstring?

UID of one term. Omit it to work with all terms.

Default: null

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().

NameTypeDescription
model (required)TaxonomyModel

New values for the taxonomy fields.

Default: Not applicable
collectionParameterCollection?

Adds query parameters, for example locale.

Default: null

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.

NameTypeDescription
model (required)TaxonomyModel

New values for the taxonomy fields.

Default: Not applicable
collectionParameterCollection?

Adds query parameters, for example locale.

Default: null

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);
}