Term
Term
The Term class creates, reads, updates, moves, localizes, and deletes the terms of one taxonomy. It also reads the ancestors and descendants of a term, and searches terms across all taxonomies of the stack.
When to Use This Class: Use this class when your code builds the hierarchy of a taxonomy term by term, or reorganizes it.
Conceptual Role: Acts as the Content Management API (CMA) client for the /taxonomies/<TAXONOMY_UID>/terms endpoint. Call stack.Taxonomy("<TAXONOMY_UID>").Terms() to get an instance.
Returns: Term. A handle for term operations in one taxonomy.
Instance State
The term UID you pass to Terms() decides which methods you can call on the instance:
- Call stack.Taxonomy("<TAXONOMY_UID>").Terms() without a term UID to work with the term collection, for example Query or Create.
- Call stack.Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>") to work with one term, for example Fetch or Move.
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 term UID throws InvalidOperationException, and a single-term method on an instance with no term UID throws ArgumentException. Terms() itself throws ArgumentException when the taxonomy instance has no UID.
Warning The SDK treats an empty string as no term UID, both in its checks and in the request path. Terms("") returns a collection instance, so a term UID variable that is unexpectedly empty makes Fetch throw ArgumentException and lets Create add a term. Check the variable before you pass it.
Warning Set the term UID only through Terms("<TERM_UID>"). The instance also has a settable Uid property, but the SDK builds the request path when you call Terms(). Setting Uid later changes which methods the SDK allows without changing which term 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 term request except Delete a term, which lists only the authtoken.
Locale.
- Every method that reads or writes term 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.
Hierarchy.
- A term with no ParentUid sits at the root level of the taxonomy. A term with a ParentUid sits under that parent.
- The API reference states that term order at one level starts from 1. Set the position with the Move method, because TermModel has no order property.
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 TermModel.
- 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 |
|---|---|---|
| Set the position of a new term in the same call | No | TermModel has no order property. Create the term, then call Move with TermMoveModel.Order. |
| Search terms in one taxonomy only | No | Search always searches every taxonomy. Pass typeahead in the Find collection of Query to search one taxonomy. |
| Remove the localized version of a term | No dedicated method | The CMA Unlocalize a term request is a DELETE on the same path as Delete, with a locale query parameter. |
| Publish a single term | No | The CMA publishes taxonomies as a whole, terms included. The SDK has no publish method for taxonomies. |
Method Index
The groups below follow the Instance State split.
Work with the term collection. Available on stack.Taxonomy("<TAXONOMY_UID>").Terms() when you pass no term UID.
| Method Name | Returns | Description |
|---|---|---|
| Query | A new query for the terms of the taxonomy. | Builds a query that lists the terms of the taxonomy. |
| Create | The API response with the created term. | Creates a term at the root level or under a parent term. |
| CreateAsync | The API response with the created term. | Creates a term asynchronously. |
| Search | The API response with the matching terms from all taxonomies. | Searches the terms of every taxonomy in the stack. |
| SearchAsync | The API response with the matching terms from all taxonomies. | Searches terms asynchronously. |
Work with one term. Available on stack.Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").
| Method Name | Returns | Description |
|---|---|---|
| Fetch | The API response with the requested term. | Retrieves one term. |
| FetchAsync | The API response with the requested term. | Retrieves one term asynchronously. |
| Update | The API response with the updated term. | Updates the name of a term. |
| UpdateAsync | The API response with the updated term. | Updates a term asynchronously. |
| Delete | The API response for the deletion. | Deletes a term and all its child terms. |
| DeleteAsync | The API response for the deletion. | Deletes a term asynchronously. |
| Ancestors | The API response with the ancestor terms. | Lists the terms above a term in the hierarchy. |
| AncestorsAsync | The API response with the ancestor terms. | Lists the ancestor terms asynchronously. |
| Descendants | The API response with the descendant terms. | Lists the terms below a term in the hierarchy. |
| DescendantsAsync | The API response with the descendant terms. | Lists the descendant terms asynchronously. |
| Move | The API response with the moved term. | Moves a term to another parent or position. |
| MoveAsync | The API response with the moved term. | Moves a term asynchronously. |
| Locales | The API response with the localized versions of the term. | Lists the locales a term has versions in. |
| LocalesAsync | The API response with the localized versions of the term. | Lists the localized versions asynchronously. |
| Localize | The API response with the localized term. | Adds a term version in another locale. |
| LocalizeAsync | The API response with the localized term. | Localizes a term asynchronously. |
Class-Level Snippet
The snippet below creates a root term and a child term, moves the child to the first position, and lists the ancestors of the child.
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>");
Taxonomy taxonomy = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>");
try
{
taxonomy.Terms().Create(new TermModel { Uid = "footwear", Name = "Footwear" });
taxonomy.Terms().Create(new TermModel { Uid = "running_shoes", Name = "Running Shoes", ParentUid = "footwear" });
ParameterCollection force = new ParameterCollection();
force.Add("force", true);
taxonomy.Terms("running_shoes").Move(new TermMoveModel { ParentUid = "footwear", Order = 1 }, force);
ContentstackResponse ancestors = taxonomy.Terms("running_shoes").Ancestors();
Console.WriteLine(ancestors.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects a request, for example a duplicate term UID
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Methods
Each method of the Term class has its own section below, with its parameters, validation rules, behavior, and examples.
Ancestors
Ancestors lists the terms above the term whose UID you passed to Terms() in the taxonomy hierarchy.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example limit. |
Returns: ContentstackResponse. The API response with the ancestor terms.
Validation
- Throws ArgumentException (parameter uid) if the instance has no term UID or an empty string, because Ancestors works on one term. Call Terms("<TERM_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>/terms/<TERM_UID>/ancestors, with the entries of collection as query parameters. See Get ancestors of a term in the Content Management API reference.
- The API reference lists these query parameters for the request, among others:
- locale and include_fallback read the terms in another locale.
- include_children_count, include_referenced_entries_count, and include_count add counts to the response.
- limit and skip page through the result.
- Does not page through the results for you. Without limit and skip, the API applies its own page size.
- Returns the raw API response. Each ancestor holds the fields that TermAncestorDescendant describes.
Example
Basic usage: list the ancestors of a term
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>").Terms("<TERM_UID>").Ancestors();
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: read one page of ancestors with counts
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("include_count", true);
collection.Add("include_children_count", true);
collection.Add("limit", 20);
collection.Add("skip", 0);
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").Ancestors(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}AncestorsAsync
AncestorsAsync lists the terms above the term whose UID you passed to Terms(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example limit. |
Returns: Task<ContentstackResponse>. The API response with the ancestor terms.
Validation
- Throws ArgumentException (parameter uid) if the instance has no term UID or an empty string, because AncestorsAsync works on one term.
- The SDK throws the exception above when you call AncestorsAsync, 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 request as Ancestors and completes the task when the API responds.
- Otherwise behaves like Ancestors.
Example
Basic usage: list the ancestors of a term
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>").Terms("<TERM_UID>").AncestorsAsync();
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: read one page of ancestors with counts
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("include_count", true);
collection.Add("include_children_count", true);
collection.Add("limit", 20);
collection.Add("skip", 0);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").AncestorsAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Create
Create creates a term in the taxonomy from the details in a TermModel, at the root level or under a parent term.
| Name | Type | Description |
|---|---|---|
| model (required) | [TermModel](../../TermModel/class_reference.md) | UID, name, and parent of the new term. |
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: ContentstackResponse. The API response with the created term.
Validation
- Throws InvalidOperationException if the instance has a term UID, because Create adds a term to the collection. Call Terms() with no term 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, a duplicate term UID, or a ParentUid that names no term 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/<TAXONOMY_UID>/terms with the body { "term": { ... } }. See Create a term in the Content Management API reference.
- Serializes only the properties of model that are not null:
- Leave ParentUid unset to create a root-level term. The body then has no parent_uid key.
- Set ParentUid to the UID of an existing term to create a child term under it.
- Leave the count, depth, and date properties unset. The API sets them.
- The API reference lists include_children_count and include_referenced_entries_count as query parameters that add counts to the response.
- Returns the raw API response. The new term sits under the term key.
Example
Basic usage: create a root-level term
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>");
TermModel model = new TermModel { Uid = "footwear", Name = "Footwear" };
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms().Create(model);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"Created term {json["term"]?["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 child term and return its 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();
TermModel model = new TermModel
{
Uid = "running_shoes",
Name = "Running Shoes",
ParentUid = "footwear"
};
ParameterCollection collection = new ParameterCollection();
collection.Add("include_children_count", true);
collection.Add("include_referenced_entries_count", true);
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms().Create(model, collection);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"{json["term"]?["uid"]} sits at depth {json["term"]?["depth"]}");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: create a term, then set its position
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>");
Taxonomy taxonomy = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>");
try
{
// TermModel has no order property, so the new term takes the position the API assigns.
taxonomy.Terms().Create(new TermModel { Uid = "sandals", Name = "Sandals", ParentUid = "footwear" });
ParameterCollection collection = new ParameterCollection();
collection.Add("force", true);
taxonomy.Terms("sandals").Move(new TermMoveModel { ParentUid = "footwear", Order = 1 }, collection);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}CreateAsync
CreateAsync creates a term in the taxonomy from the details in a TermModel, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | [TermModel](../../TermModel/class_reference.md) | UID, name, and parent of the new term. |
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: Task<ContentstackResponse>. The API response with the created term.
Validation
- Throws InvalidOperationException if the instance has a term UID, because CreateAsync adds a term to the collection.
- 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 request as Create and completes the task when the API responds.
- Otherwise behaves like Create.
Example
Basic usage: create a root-level term
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>");
TermModel model = new TermModel { Uid = "footwear", Name = "Footwear" };
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms().CreateAsync(model);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"Created term {json["term"]?["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 child term and return its 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();
TermModel model = new TermModel
{
Uid = "running_shoes",
Name = "Running Shoes",
ParentUid = "footwear"
};
ParameterCollection collection = new ParameterCollection();
collection.Add("include_children_count", true);
collection.Add("include_referenced_entries_count", true);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms().CreateAsync(model, collection);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"{json["term"]?["uid"]} sits at depth {json["term"]?["depth"]}");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Delete
Delete deletes the term whose UID you passed to Terms(), together with all its child 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 term UID or an empty string, because Delete works on one term. Call Terms("<TERM_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>/terms/<TERM_UID>, with the entries of collection as query parameters. See Delete a term in the Content Management API reference.
- The API deletes the term and every child term below it, and removes them 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 term is irreversible. The API removes the term, every child term below it, and their associations with your entries.
Example
Basic usage: delete a term
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>").Terms("<TERM_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: check the child terms before you delete
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>");
Term term = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>");
try
{
// The API deletes every descendant together with the term.
ContentstackResponse descendants = term.Descendants();
Console.WriteLine($"Also deleted: {descendants.OpenJsonObjectResponse().ToJsonString()}");
ParameterCollection collection = new ParameterCollection();
collection.Add("force", true);
term.Delete(collection);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}DeleteAsync
DeleteAsync deletes the term whose UID you passed to Terms(), together with all its child 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 term UID or an empty string, because DeleteAsync works on one term.
- The SDK throws the exception above 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 request as Delete and completes the task when the API responds.
- Otherwise behaves like Delete.
Warning Deleting a term is irreversible. The API removes the term, every child term below it, and their associations with your entries.
Example
Basic usage: delete a term
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>").Terms("<TERM_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: check the child terms before you delete
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>");
Term term = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>");
try
{
// The API deletes every descendant together with the term.
ContentstackResponse descendants = await term.DescendantsAsync();
Console.WriteLine($"Also deleted: {descendants.OpenJsonObjectResponse().ToJsonString()}");
ParameterCollection collection = new ParameterCollection();
collection.Add("force", true);
await term.DeleteAsync(collection);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Descendants
Descendants lists the terms below the term whose UID you passed to Terms() in the taxonomy hierarchy.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example limit. |
Returns: ContentstackResponse. The API response with the descendant terms.
Validation
- Throws ArgumentException (parameter uid) if the instance has no term UID or an empty string, because Descendants works on one term. Call Terms("<TERM_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>/terms/<TERM_UID>/descendants, with the entries of collection as query parameters. See Get descendants of a term in the Content Management API reference.
- The API reference lists these query parameters for the request, among others:
- locale and include_fallback read the terms in another locale.
- include_children_count, include_referenced_entries_count, and include_count add counts to the response.
- limit and skip page through the result.
- depth limits the number of levels below the term that the API returns.
- include_order set to true adds the position of each term at its level.
- Does not page through the results for you. Without limit and skip, the API applies its own page size.
- Returns the raw API response. Each descendant holds the fields that TermAncestorDescendant describes.
Example
Basic usage: list the descendants of a term
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>").Terms("<TERM_UID>").Descendants();
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: read one page of descendants with counts
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("include_count", true);
collection.Add("include_children_count", true);
collection.Add("limit", 20);
collection.Add("skip", 0);
collection.Add("depth", 2);
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").Descendants(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}DescendantsAsync
DescendantsAsync lists the terms below the term whose UID you passed to Terms(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example limit. |
Returns: Task<ContentstackResponse>. The API response with the descendant terms.
Validation
- Throws ArgumentException (parameter uid) if the instance has no term UID or an empty string, because DescendantsAsync works on one term.
- The SDK throws the exception above when you call DescendantsAsync, 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 request as Descendants and completes the task when the API responds.
- Otherwise behaves like Descendants.
Example
Basic usage: list the descendants of a term
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>").Terms("<TERM_UID>").DescendantsAsync();
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: read one page of descendants with counts
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("include_count", true);
collection.Add("include_children_count", true);
collection.Add("limit", 20);
collection.Add("skip", 0);
collection.Add("depth", 2);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").DescendantsAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Fetch
Fetch retrieves the details of the term whose UID you passed to Terms().
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example locale. |
Returns: ContentstackResponse. The API response with the requested term.
Validation
- Throws ArgumentException (parameter uid) if the instance has no term UID or an empty string, because Fetch works on one term. Call Terms("<TERM_UID>").
- The SDK does not check the UID format. A taxonomy or term UID that names nothing 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>/terms/<TERM_UID>, with the entries of collection as query parameters. See Get a single term in the Content Management API reference.
- The API reference lists these query parameters for the request:
- locale reads the term 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 term has no version in locale.
- include_children_count and include_referenced_entries_count set to true add those counts to the response.
- Returns the raw API response. The term sits under the term key and holds the fields that TermModel describes.
Example
Basic usage: fetch a term 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>").Terms("<TERM_UID>").Fetch();
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"Term name: {json["term"]?["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 a child count
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_children_count", true);
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").Fetch(collection);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"{json["term"]?["name"]} has {json["term"]?["children_count"]} child terms");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: read the response into TermModel
using System;
using System.Text.Json;
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>").Terms("<TERM_UID>").Fetch();
// The term sits under the "term" key, so deserialize that node, not the whole body.
TermModel? term = response.OpenJsonObjectResponse()["term"]?.Deserialize<TermModel>();
Console.WriteLine($"{term?.Name} sits at depth {term?.Depth} under {term?.ParentUid ?? "the root"}");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}FetchAsync
FetchAsync retrieves the details of the term whose UID you passed to Terms(), 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 term.
Validation
- Throws ArgumentException (parameter uid) if the instance has no term UID or an empty string, because FetchAsync works on one term.
- The SDK throws the exception above when you call FetchAsync, 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 request as Fetch and completes the task when the API responds.
- Otherwise behaves like Fetch.
Example
Basic usage: fetch a term 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>").Terms("<TERM_UID>").FetchAsync();
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"Term name: {json["term"]?["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 a child count
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_children_count", true);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").FetchAsync(collection);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"{json["term"]?["name"]} has {json["term"]?["children_count"]} child terms");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Locales
Locales lists the localized versions of the term whose UID you passed to Terms().
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: ContentstackResponse. The API response with the localized versions of the term.
Validation
- Throws ArgumentException (parameter uid) if the instance has no term UID or an empty string, because Locales works on one term. Call Terms("<TERM_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>/terms/<TERM_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 term
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>").Terms("<TERM_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>").Terms("<TERM_UID>").Locales(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}LocalesAsync
LocalesAsync lists the localized versions of the term whose UID you passed to Terms(), 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 term.
Validation
- Throws ArgumentException (parameter uid) if the instance has no term UID or an empty string, because LocalesAsync works on one term.
- The SDK throws the exception above 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 request as Locales and completes the task when the API responds.
- Otherwise behaves like Locales.
Example
Basic usage: list the localized versions of a term
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>").Terms("<TERM_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>").Terms("<TERM_UID>").LocalesAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Localize
Localize adds a version of the term whose UID you passed to Terms() in another locale, with the translated values from a TermModel.
| Name | Type | Description |
|---|---|---|
| model (required) | [TermModel](../../TermModel/class_reference.md) | Translated name of the term for the locale. |
| collection | ParameterCollection? | Query parameters. Pass locale to name the target locale. |
Returns: ContentstackResponse. The API response with the localized term.
Validation
- Throws ArgumentException (parameter uid) if the instance has no term UID or an empty string, because Localize works on one term. Call Terms("<TERM_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>/terms/<TERM_UID> with the body { "term": { ... } } and the entries of collection as query parameters. See Localize a term in the Content Management API reference.
- Serializes only the properties of model that are not null. Set the translated Name.
- 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 term sits under the term key.
Limitations
- Does not remove a localized version. The SDK has no method for the Unlocalize a term request.
Example
Basic usage: add a French version of a term
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>");
TermModel model = new TermModel { Name = "Chaussures" };
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "fr-fr");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").Localize(model, collection);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"Localized name: {json["term"]?["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 term for a locale from a variable
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();
string localeCode = "<LOCALE_CODE>";
TermModel model = new TermModel { Name = "<TRANSLATED_NAME>" };
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", localeCode);
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").Localize(model, collection);
Console.WriteLine((int)response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}LocalizeAsync
LocalizeAsync adds a version of the term whose UID you passed to Terms() in another locale, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | [TermModel](../../TermModel/class_reference.md) | Translated name of the term for the locale. |
| collection | ParameterCollection? | Query parameters. Pass locale to name the target locale. |
Returns: Task<ContentstackResponse>. The API response with the localized term.
Validation
- Throws ArgumentException (parameter uid) if the instance has no term UID or an empty string, because LocalizeAsync works on one term.
- 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 request as Localize and completes the task when the API responds.
- Otherwise behaves like Localize.
Example
Basic usage: add a French version of a term
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>");
TermModel model = new TermModel { Name = "Chaussures" };
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "fr-fr");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").LocalizeAsync(model, collection);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"Localized name: {json["term"]?["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 term for a locale from a variable
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();
string localeCode = "<LOCALE_CODE>";
TermModel model = new TermModel { Name = "<TRANSLATED_NAME>" };
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", localeCode);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").LocalizeAsync(model, collection);
Console.WriteLine((int)response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Move
Move moves the term whose UID you passed to Terms() to another parent term, another position at its level, or both.
| Name | Type | Description |
|---|---|---|
| moveModel (required) | [TermMoveModel](../../TermMoveModel/class_reference.md) | Target parent UID and position of the term. |
| collection | ParameterCollection? | Adds query parameters, for example force. |
Returns: ContentstackResponse. The API response with the moved term.
Validation
- Throws ArgumentException (parameter uid) if the instance has no term UID or an empty string, because Move works on one term. Call Terms("<TERM_UID>").
- Throws ArgumentNullException (parameter dataModel) if moveModel is null, because the request body comes from the model.
- The API rejects the move of a term that has child terms unless collection holds force=true. The API reference states that force is false by default.
- The API rejects a move that makes a term its own parent.
- 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>/terms/<TERM_UID>/move with the body { "term": { "parent_uid": ..., "order": ... } }. See Move/Reorder a term in the Content Management API reference.
- Order sets the position of the term among the terms at its level. The API reference states that positions start from 1.
- The SDK leaves a null property out of the body. A TermMoveModel with no ParentUid sends no parent_uid key, so the body cannot carry an explicit null parent.
- With force=true, the API moves the term together with its child terms, which changes the hierarchy below and above it.
- Returns the raw API response. The moved term sits under the term key.
Example
Basic usage: move a term to the first position under a parent
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>");
TermMoveModel moveModel = new TermMoveModel { ParentUid = "<PARENT_TERM_UID>", Order = 1 };
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").Move(moveModel);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"New parent: {json["term"]?["parent_uid"]}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: move a term that has child terms
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();
TermMoveModel moveModel = new TermMoveModel { ParentUid = "<PARENT_TERM_UID>", Order = 2 };
ParameterCollection collection = new ParameterCollection();
collection.Add("force", true);
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").Move(moveModel, collection);
Console.WriteLine((int)response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}MoveAsync
MoveAsync moves the term whose UID you passed to Terms() to another parent or position, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| moveModel (required) | [TermMoveModel](../../TermMoveModel/class_reference.md) | Target parent UID and position of the term. |
| collection | ParameterCollection? | Adds query parameters, for example force. |
Returns: Task<ContentstackResponse>. The API response with the moved term.
Validation
- Throws ArgumentException (parameter uid) if the instance has no term UID or an empty string, because MoveAsync works on one term.
- Throws ArgumentNullException (parameter dataModel) if moveModel is null.
- The SDK throws the exceptions above when you call MoveAsync, 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 request as Move and completes the task when the API responds.
- Otherwise behaves like Move.
Example
Basic usage: move a term to the first position under a parent
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>");
TermMoveModel moveModel = new TermMoveModel { ParentUid = "<PARENT_TERM_UID>", Order = 1 };
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").MoveAsync(moveModel);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"New parent: {json["term"]?["parent_uid"]}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: move a term that has child terms
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();
TermMoveModel moveModel = new TermMoveModel { ParentUid = "<PARENT_TERM_UID>", Order = 2 };
ParameterCollection collection = new ParameterCollection();
collection.Add("force", true);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").MoveAsync(moveModel, collection);
Console.WriteLine((int)response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Query
Query returns a query object that lists the terms of the taxonomy 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 the terms of the taxonomy.
Validation
- Throws InvalidOperationException if the instance has a term UID, because Query lists the term collection. Call Terms() with no term 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 Terms().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/<TAXONOMY_UID>/terms, with every parameter you set as a query parameter. See Get all terms of a taxonomy 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 terms in another locale
- depth to return terms from the root level down to that depth
- include_children_count, include_referenced_entries_count, and include_order to add counts and positions to each term
- typeahead to match terms in this taxonomy by a search string, and asc or desc to sort
- deleted set to true to list only deleted terms
- Returns the raw API response. The terms sit under the terms 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 terms per page. |
| Skip(double value) | Query | Sets the number of terms to skip. |
| IncludeCount() | Query | Adds the total term count. |
| Find(ParameterCollection? collection = null) | ContentstackResponse | Sends the request and returns the terms. |
| FindAsync(ParameterCollection? collection = null) | Task<ContentstackResponse> | Sends the request without blocking the thread. |
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
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms().Query().Find();
JsonArray? terms = response.OpenJsonObjectResponse()["terms"]?.AsArray();
foreach (JsonNode? term in terms ?? new JsonArray())
{
Console.WriteLine($"{term?["uid"]}: {term?["name"]} (parent: {term?["parent_uid"]})");
}
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Paging: read the top two levels one page at a time
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("depth", 2);
collection.Add("include_children_count", true);
try
{
ContentstackResponse response = await client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.Taxonomy("<TAXONOMY_UID>")
.Terms()
.Query()
.Limit(50)
.Skip(0)
.IncludeCount()
.FindAsync(collection);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"Showing {json["terms"]?.AsArray().Count} of {json["count"]} terms");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: calling Query on a single-term instance throws
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").Query();
}
catch (InvalidOperationException e)
{
// Fires before any request, because Query needs the term collection instance
Console.WriteLine(e.Message);
}Search
Search finds terms whose names match a search string, across every taxonomy in the stack.
| Name | Type | Description |
|---|---|---|
| typeahead (required) | string | Search string to match against terms. |
| collection | ParameterCollection? | Adds query parameters, for example limit. |
Returns: ContentstackResponse. The API response with the matching terms from all taxonomies.
Validation
- Throws InvalidOperationException if the instance has a term UID, because Search works on the term collection. Call Terms() with no term UID.
- typeahead set to null sends an empty typeahead parameter. The API reference requires either typeahead or query, so an empty search string without query fails at the API.
- Throws ArgumentException if collection already holds a typeahead key, because the SDK adds typeahead to the same collection and a parameter collection rejects duplicate keys.
- 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/$all/terms with typeahead and the entries of collection as query parameters. See Get all terms across all taxonomies in the Content Management API reference.
- Ignores the taxonomy UID of the instance. The request path uses $all, which the API reference describes as a reserved keyword for all taxonomies.
- Adds typeahead to the collection you pass, so the object holds it after the call. Build a new ParameterCollection for each search.
- Sends typeahead without URL encoding. Encode a search string that holds &, #, or + with Uri.EscapeDataString before you pass it.
- The API reference lists locale, include_fallback, include_children_count, include_referenced_entries_count, include_count, query, limit, and skip as further query parameters.
- Returns the raw API response. The matching terms sit under the terms key.
Example
Basic usage: search terms in every 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
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms().Search("shoe");
JsonArray? terms = response.OpenJsonObjectResponse()["terms"]?.AsArray();
foreach (JsonNode? term in terms ?? new JsonArray())
{
Console.WriteLine($"{term?["taxonomy_uid"]}/{term?["uid"]}: {term?["name"]}");
}
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: search with a count and a page size
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_count", true);
collection.Add("limit", 10);
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms().Search("running shoes", collection);
Console.WriteLine($"Matches: {response.OpenJsonObjectResponse()["count"]}");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: search for a string that holds special characters
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>");
// The SDK does not encode typeahead, so encode the "&" yourself.
string typeahead = Uri.EscapeDataString("shoes & boots");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms().Search(typeahead);
Console.WriteLine(response.OpenJsonObjectResponse()["terms"]?.AsArray().Count);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}SearchAsync
SearchAsync finds terms whose names match a search string, across every taxonomy in the stack, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| typeahead (required) | string | Search string to match against terms. |
| collection | ParameterCollection? | Adds query parameters, for example limit. |
Returns: Task<ContentstackResponse>. The API response with the matching terms from all taxonomies.
Validation
- Throws InvalidOperationException if the instance has a term UID, because SearchAsync works on the term collection.
- Throws ArgumentException if collection already holds a typeahead key.
- The SDK throws the exceptions above when you call SearchAsync, 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 request as Search and completes the task when the API responds.
- Otherwise behaves like Search.
Example
Basic usage: search terms in every 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
{
ContentstackResponse response = await client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms().SearchAsync("shoe");
JsonArray? terms = response.OpenJsonObjectResponse()["terms"]?.AsArray();
foreach (JsonNode? term in terms ?? new JsonArray())
{
Console.WriteLine($"{term?["taxonomy_uid"]}/{term?["uid"]}: {term?["name"]}");
}
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: search with a count and a page size
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_count", true);
collection.Add("limit", 10);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms().SearchAsync("running shoes", collection);
Console.WriteLine($"Matches: {response.OpenJsonObjectResponse()["count"]}");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Update
Update changes the details of the term whose UID you passed to Terms(), for example its name.
| Name | Type | Description |
|---|---|---|
| model (required) | [TermModel](../../TermModel/class_reference.md) | New values for the term fields. |
| collection | ParameterCollection? | Adds query parameters, for example locale. |
Returns: ContentstackResponse. The API response with the updated term.
Validation
- Throws ArgumentException (parameter uid) if the instance has no term UID or an empty string, because Update works on one term. Call Terms("<TERM_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>/terms/<TERM_UID> with the body { "term": { ... } }. See Update a term 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.
- 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 term.
- Does not move the term. Call the Move method to change its parent or position.
- Returns the raw API response. The updated term sits under the term key.
Example
Basic usage: rename a term
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>");
TermModel model = new TermModel { Name = "Shoes" };
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").Update(model);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"New name: {json["term"]?["name"]}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: rename the French version of a term
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();
TermModel model = new TermModel { Name = "Chaussures" };
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "fr-fr");
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").Update(model, collection);
Console.WriteLine((int)response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}UpdateAsync
UpdateAsync changes the details of the term whose UID you passed to Terms(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | [TermModel](../../TermModel/class_reference.md) | New values for the term fields. |
| collection | ParameterCollection? | Adds query parameters, for example locale. |
Returns: Task<ContentstackResponse>. The API response with the updated term.
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 term UID or an empty string, because UpdateAsync works on one term.
- 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 request as Update and completes the task when the API responds.
- Otherwise behaves like Update.
Example
Basic usage: rename a term
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>");
TermModel model = new TermModel { Name = "Shoes" };
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").UpdateAsync(model);
JsonObject json = response.OpenJsonObjectResponse();
Console.WriteLine($"New name: {json["term"]?["name"]}");
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: rename the French version of a term
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();
TermModel model = new TermModel { Name = "Chaussures" };
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "fr-fr");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>").UpdateAsync(model, collection);
Console.WriteLine((int)response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}