---
title: "Taxonomy"
description: "Taxonomy"
url: "https://www.contentstack.com/docs/developers/sdks/content-management-sdk/dot-net/reference/taxonomy"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-09-22"
---

# Taxonomy

## Taxonomy

The Taxonomy class allows you to organize and categorize content using a hierarchical structure of terms. It serves as the central manager for taxonomy-level operations such as create, manage, export, or retrieve taxonomies, within a specific Stack.

**Initialization**

To interact with taxonomies, initialize the class through your stack instance.

*   **Syntax:**
    
    ```
    stack.Taxonomy(string uid = null)
    ```
    
*   **Returns:**
    *   **Type**: Taxonomy
    *   **Description**: Returns a Taxonomy instance.

**UID and Request Scope**

*   The uid determines the request scope. The SDK uses it to bind the Taxonomy instance either to the collection (/taxonomies) or to a single taxonomy (/taxonomies/{uid}), and validates this before sending the request. Using the wrong scope throws InvalidOperationException.
*   Use collection scope by calling stack.Taxonomy() (omit or pass null for uid). This maps to /taxonomies and supports:
    *   Create / CreateAsync
    *   Query().Find() / Query().FindAsync()
    *   Import / ImportAsync
*   Use single-taxonomy scope by calling stack.Taxonomy("<TAXONOMY\_UID>") with a non-empty UID. This maps to /taxonomies/{uid}.

**Method Index**

**Method Name**

**Description**

Find() / FindAsync()

Queries and retrieves a list of taxonomies with optional filters.

Create() / CreateAsync()

Creates a new taxonomy within the stack.

Update() / UpdateAsync()

Updates the details of an existing taxonomy.

Fetch() / FetchAsync()

Retrieves the complete details of a single taxonomy.

Delete() / DeleteAsync()

Permanently removes a taxonomy from the stack.

Export() / ExportAsync()

Exports taxonomy data as a payload.

Locales() / LocalesAsync()

Retrieves the localized versions for the targeted taxonomy.

Localize() / LocalizeAsync()

Creates or updates a localized version of the taxonomy.

Import() / ImportAsync()

Imports a taxonomy from a file stream.

Terms()

Returns a Term instance scoped to this taxonomy.

**Synchronous vs Asynchronous Methods**

**Synchronous**

*   Blocks the executing thread until the API responds.
*   Use for simple console scripts or background workers where blocking is acceptable.

**Asynchronous (****Async****)**

*   Releases the thread while waiting for the network response.
*   Recommended for modern .NET apps (e.g., ASP.NET Core) and UI apps.
*   Ensures better scalability and responsiveness.

**Common Usage Example**

Shows an end-to-end async workflow to initialize Taxonomy, authenticate the client, target a Stack, and create a "Categories" taxonomy with basic error handling.

```
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Services.Models;
using Contentstack.Management.Core.Exceptions;

namespace ContentstackExample
{
    class Program
    {
        static async Task Main(string[] args)
        {
            try 
            {
                // Initialize the Contentstack client with the authentication token
                ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");


                // Target the specific stack using its API key
                Stack stack = client.Stack("<API_KEY>");


                // Define the payload for the new taxonomy
                TaxonomyModel model = new TaxonomyModel
                {
                    Uid = "<TAXONOMY_UID>",
                    Name = "Categories",
                    Description = "Global categories taxonomy"
                };


                // Optional query parameters (merged as query string when non-empty); pass null if none
                ContentstackResponse response = await stack.Taxonomy().CreateAsync(model, collection: null);


                if (response.IsSuccessStatusCode)
                {
                    Console.WriteLine("Taxonomy created successfully.");
                }
                else
                {
                    Console.WriteLine($"Taxonomy create failed: HTTP {(int)response.StatusCode}");
                }
            } 
            catch (ContentstackException ex) 
            {
                Console.WriteLine($"Contentstack Error: {ex.ErrorMessage}");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"System Error: {ex.Message}");
            }
        }
    }
}
```

## Find / FindAsync

The Find and FindAsync methods retrieve all taxonomies available in the stack.

**Note:** Results are paginated, so a single Find() / FindAsync() may not return every taxonomy. Refer to the [Content Management API](/docs/developers/apis/content-management-api) documentation for page size and maximum limit.

```
Use the Query fluent helpers or pass a ParameterCollection into Find / FindAsync to page results (for example limit, skip, and include_count).
Example:
The following example shows how to asynchronously query the stack for taxonomies, page with Limit / Skip, and read the taxonomies array from the response.
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
using Contentstack.Management.Core.Exceptions;
using Newtonsoft.Json;

namespace ContentstackExample
{
    // GET /taxonomies → { "taxonomies": [ ... ] }
    class TaxonomiesResponseModel
    {
        [JsonProperty("taxonomies")]
        public List<TaxonomyModel> Taxonomies { get; set; }
    }

    class Program
    {
        static async Task Main(string[] args)
        {
            try
            {
                ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
                Stack stack = client.Stack("<API_KEY>");

                // Merge extra query params: .FindAsync(new ParameterCollection { ... })
                ContentstackResponse response = await stack.Taxonomy().Query()
                    .Limit(20)
                    .Skip(0)
                    .FindAsync();

                if (!response.IsSuccessStatusCode)
                {
                    Console.WriteLine($"Request failed: HTTP {(int)response.StatusCode}");
                    return;
                }

                var wrapper = response.OpenTResponse<TaxonomiesResponseModel>();
                if (wrapper?.Taxonomies != null)
                {
                    foreach (var taxonomy in wrapper.Taxonomies)
                    {
                        Console.WriteLine($"{taxonomy.Uid}: {taxonomy.Name}");
                    }
                }
            }
            catch (ContentstackException ex)
            {
                Console.WriteLine($"Error: {ex.ErrorMessage}");
            }
        }
    }
}
```

Query modifiers for Query().Find() provide values to refine retrieval results using applied filters.

## Create / CreateAsync

The Create and CreateAsync actions add a new taxonomy to the stack.

```
The following example shows how to asynchronously create a new taxonomy with a specific UID and Name.
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Exceptions;

try 
{
    // Initialize the Contentstack client and target the stack
    ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
    Stack stack = client.Stack("<API_KEY>");


    // Construct the payload with required taxonomy properties
    TaxonomyModel model = new TaxonomyModel
    {
        Uid = "<TAXONOMY_UID>",
        Name = "Product Taxonomy"
    };


    // Execute the creation request (second argument: optional ParameterCollection, or null)
    ContentstackResponse response = await stack.Taxonomy().CreateAsync(model, collection: null);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Taxonomy created successfully.");
    }
    else
    {
        Console.WriteLine($"Taxonomy create failed: HTTP {(int)response.StatusCode}");
    }
} 
catch (ContentstackException ex) 
{
    Console.WriteLine($"Error: {ex.ErrorMessage}");
}
```

The taxonomy payload for Create(). Provide UID, name, and optionally description to create a new taxonomy entity.

Defines optional query parameters for the creation request. Provide values to modify the default API response.

## Update / UpdateAsync

The Update and UpdateAsync actions modify the details of an existing taxonomy.

**Update Behavior and UID Requirement**

*   The taxonomy is identified only by the UID passed to stack.Taxonomy("<TAXONOMY\_UID>"), which is used in the request path PUT /taxonomies/{uid}. The SDK does not infer the target from TaxonomyModel.
*   You must call Update or UpdateAsync with a non-empty UID. Calling stack.Taxonomy() without a UID throws InvalidOperationException before any request is sent.
*   You can set TaxonomyModel.Uid in the request body for consistency, but it does not determine which taxonomy is updated.

**Deserializing the Response**

*   ContentstackResponse does not include a Result property.
*   Use OpenTResponse<T>() to deserialize the response, or OpenJObjectResponse() / OpenResponse() for raw access.
*   The API wraps the response inside a taxonomy field, so define a DTO with \[JsonProperty("taxonomy")\] to match the structure.

```
The following example shows how to update the name and description of an explicitly targeted taxonomy and verify the persisted values from the response body. It assumes a top-level statements entry file. If you use a classic Main method instead, define TaxonomyResponseEnvelope in another source file (or above Main in the same file) and invoke the same logic from Main.
using System;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Exceptions;

try 
{
    // Initialize the Contentstack client and target the stack
    ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
    Stack stack = client.Stack("<API_KEY>");


    // Define the properties to be updated
    TaxonomyModel model = new TaxonomyModel 
    { 
        Name = "<UPDATED_NAME>", 
        Description = "<UPDATED_DESCRIPTION>" 
    };


    // Target the taxonomy by UID and apply the updates (optional ParameterCollection as second arg)
    ContentstackResponse response = await stack.Taxonomy("<TAXONOMY_UID>").UpdateAsync(model, collection: null);

    if (response.IsSuccessStatusCode)
    {
        TaxonomyResponseEnvelope body = response.OpenTResponse<TaxonomyResponseEnvelope>();
        TaxonomyModel updated = body?.Taxonomy;

        if (updated != null
            && updated.Name == "<UPDATED_NAME>"
            && updated.Description == "<UPDATED_DESCRIPTION>")
        {
            Console.WriteLine($"Taxonomy updated successfully (uid: {updated.Uid}, updated_at: {updated.UpdatedAt}).");
        }
        else
        {
            Console.WriteLine("Update reported success but response body did not match expected fields.");
        }
    }
    else
    {
        Console.WriteLine($"Taxonomy update failed: HTTP {(int)response.StatusCode}");
    }
} 
catch (ContentstackException ex) 
{
    Console.WriteLine($"Error: {ex.ErrorMessage}");
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"Invalid operation: {ex.Message}");
}

// Matches the API envelope: { "taxonomy": { ... } }. In top-level programs, declare helper types after statements.
public class TaxonomyResponseEnvelope
{
    [JsonProperty("taxonomy")]
    public TaxonomyModel Taxonomy { get; set; }
}
```

Defines fields (Name, Description) for Update(). Provide values to update the taxonomy.

Defines optional query parameters for the update request. Provide values to modify the API response.

## Fetch / FetchAsync

The Fetch and FetchAsync actions retrieve the details of a single, specific taxonomy.

**Fetching a Taxonomy (UID Requirement)**

*   The taxonomy returned is determined only by the UID passed to stack.Taxonomy("<TAXONOMY\_UID>"), which maps to GET /taxonomies/{uid}.
*   Calling Fetch or FetchAsync on stack.Taxonomy() without a UID throws InvalidOperationException before any request is sent.
*   The same entry point without a UID is used for collection operations such as create or query, not for fetching a single taxonomy.

**Handling the Response**

*   ContentstackResponse does not include a Result property.
*   Use OpenTResponse<T>() to deserialize the response, or OpenJObjectResponse() / OpenResponse() for raw access.
*   The response is wrapped in a taxonomy field, so define a DTO with \[JsonProperty("taxonomy")\] to match the payload.

```
The following example fetches a taxonomy by UID and reads the returned TaxonomyModel from the body. It assumes top-level statements. If you use a classic Main method, define TaxonomyResponseEnvelope in another source file (or above Main) and call the same logic from Main.
using System;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Exceptions;

try 
{
    // Initialize the Contentstack client and target the stack
    ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
    Stack stack = client.Stack("<API_KEY>");
    ContentstackResponse response = await stack.Taxonomy("<TAXONOMY_UID>").FetchAsync(collection: null);

    if (response.IsSuccessStatusCode)
    {
        TaxonomyResponseEnvelope body = response.OpenTResponse<TaxonomyResponseEnvelope>();
        TaxonomyModel taxonomy = body?.Taxonomy;

        if (taxonomy != null && taxonomy.Uid == "<TAXONOMY_UID>")
        {
            Console.WriteLine($"Fetched taxonomy: {taxonomy.Name} (updated_at: {taxonomy.UpdatedAt}).");
        }
        else
        {
            Console.WriteLine("Fetch reported success but response body was missing or did not match the requested UID.");
        }
    }
    else
    {
        Console.WriteLine($"Taxonomy fetch failed: HTTP {(int)response.StatusCode}");
    }
} 
catch (ContentstackException ex) 
{
    Console.WriteLine($"Error: {ex.ErrorMessage}");
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"Invalid operation: {ex.Message}");
}

// Matches the API envelope: { "taxonomy": { ... } }. In top-level programs, declare helper types after statements.
public class TaxonomyResponseEnvelope
{
    [JsonProperty("taxonomy")]
    public TaxonomyModel Taxonomy { get; set; }
}
```

Defines optional query parameters for Fetch(). Provide values to modify the retrieved payload.

## Delete / DeleteAsync

The Delete and DeleteAsync actions remove a taxonomy from the stack.

**Warning:** Deleting a taxonomy is permanent and cannot be undone. This action removes all associated terms and breaks their links with entries. Use only when you intend to remove this structure from the stack.

**Validation**

*   You must call Delete or DeleteAsync on stack.Taxonomy("<TAXONOMY\_UID>"). Calling stack.Taxonomy() without a UID throws InvalidOperationException before the request is sent.
*   If the API rejects the request (for example, due to permissions, dependencies, or a missing resource), the client throws ContentstackErrorException.
*   Errors are not returned as a failed ContentstackResponse. Inspect StatusCode, ErrorMessage, and ErrorCode on the exception.

**Behavior**

*   Optional flags are sent as query parameters using ParameterCollection.
*   Boolean values are serialized as lowercase (true / false) in the URL.
*   For example, to force delete (if supported):
    
    ```
    ParameterCollection collection = new ParameterCollection();
    collection.Add("force", true);   // becomes ?force=true
    ContentstackResponse response = await stack
     .Taxonomy("<TAXONOMY_UID>")
     .DeleteAsync(collection);
    ```
    
*   Use of parameters not supported by the Management API for taxonomies may be ignored or throw errors.

```
The following example removes a taxonomy by UID. It omits collection for a plain delete and adds a ParameterCollection with force only when your API contract requires it.
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

try 
{
    // Initialize the Contentstack client and target the stack
    ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
    Stack stack = client.Stack("<API_KEY>");


    // Execute the deletion request for a targeted taxonomy asynchronously
    ContentstackResponse response = await stack.Taxonomy("<TAXONOMY_UID>").DeleteAsync(collection: null);


    Console.WriteLine("Taxonomy deleted successfully.");
} 
catch (ContentstackErrorException ex) 
{
    Console.WriteLine($"API error ({(int)ex.StatusCode}): {ex.ErrorMessage}");
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"Invalid operation: {ex.Message}");
}
```

Defines optional query parameters for Delete(). Provide values to control deletion behavior.

## Export / ExportAsync

The Export and ExportAsync actions retrieve a full export of a single taxonomy for backup, migration, or external processing.

The response body is the raw export payload (JSON document or CSV text). The SDK does not provide a typed model. Use OpenResponse(), OpenJObjectResponse(), or OpenTResponse<T>() with your own DTOs. Inspect ContentType and ContentLength to distinguish JSON vs CSV.

**Validation**

*   Calling stack.Taxonomy() without a UID and then Export / ExportAsync throws InvalidOperationException before the request.
*   If the client is not authorized, ThrowIfNotLoggedIn() is thrown before the request.
*   Unsupported ParameterCollection value types can throw ContentstackException.
*   Passing null for collection is valid and only fails at the API or during response parsing.

**Behavior**

*   The taxonomy is selected only by the UID passed to stack.Taxonomy("<TAXONOMY\_UID>").
*   Each call maps to a single GET /taxonomies/{uid}/export request.
*   Optional flags are sent via ParameterCollection as query parameters. Supported keys and behavior are defined by the Management API.
*   The response shape depends on the API.
*   The response is not written to disk automatically. Persist the output from OpenResponse() if needed.
*   Use Import / ImportAsync to re-upload exports, and Fetch / FetchAsync for live taxonomy data without export.

```
The following example requests a JSON export using an optional format query parameter, reads the body as JSON, and handles API and client-side errors.
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
using Newtonsoft.Json.Linq;

try 
{
    ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
    Stack stack = client.Stack("<API_KEY>");

    ParameterCollection collection = new ParameterCollection();
    collection.Add("format", "json");

    ContentstackResponse response = await stack.Taxonomy("<TAXONOMY_UID>").ExportAsync(collection);

    JObject json = response.OpenJObjectResponse();

    Console.WriteLine($"Export succeeded. Content-Type: {response.ContentType}, length: {response.ContentLength}");
    Console.WriteLine(json.ToString(Newtonsoft.Json.Formatting.None));
}
catch (ContentstackErrorException ex)
{
    Console.WriteLine($"API error ({(int)ex.StatusCode}): {ex.ErrorMessage}");
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"Invalid operation: {ex.Message}");
}
```

Defines optional query parameters for the Export() method. Provide values to control exported data.

## Locales / LocalesAsync

The Locales and LocalesAsync actions return the localized versions available for the targeted taxonomy.

The response body is raw JSON from the API. The SDK does not provide a dedicated typed model for this response.

**Validation**

*   Unsupported ParameterCollection value types can throw ContentstackException.
*   Passing null for collection is valid. Some query keys or values may be ignored by the API or only fail after the server response.

**Behavior**

*   Each call maps to a single HTTP GET request.
*   The response shape depends on the Management API. Do not assume a fixed schema unless using your own DTOs.
*   Use Localize / LocalizeAsync to create or update localized content.
*   Use stack.Locale().Query() to list stack-level locale definitions (separate from taxonomy or term locale payloads).

```
The following example builds a client and stack, calls LocalesAsync for one taxonomy UID, reads JSON with OpenJObjectResponse(), and handles API failures and invalid SDK targeting.
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Newtonsoft.Json.Linq;

try
{
    ContentstackClient client = new ContentstackClient("AUTHTOKEN");
    Stack stack = client.Stack("APIKEY");

    ContentstackResponse response = await stack.Taxonomy("TAXONOMYUID").LocalesAsync();
    JObject json = response.OpenJObjectResponse();

    Console.WriteLine($"HTTP {(int)response.StatusCode}; taxonomies node present: {json["taxonomies"] != null}");
}
catch (ContentstackErrorException ex)
{
    Console.WriteLine($"API error ({(int)ex.StatusCode}): {ex.ErrorMessage}");
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"Invalid operation: {ex.Message}");
}
```

Defines optional query parameters for Locales(). Provide values to control the returned locale list.

## Localize / LocalizeAsync

The Localize and LocalizeAsync actions create or update the localized fields for an existing taxonomy, using optional query parameters (typically locale) to select the target locale.

**Validation**

*   A non-empty taxonomy UID must be provided; otherwise, stack.Taxonomy() throws InvalidOperationException.
*   Passing null for model throws ArgumentNullException when the internal CreateUpdateService is constructed.
*   You can pass null for collection. The SDK does not validate query parameters and defers validation to the API.

**Behavior**

*   Add entries to ParameterCollection to send query parameters (for example, locale). The SDK forwards these values without validation.
*   The SDK sends one HTTP POST request to /taxonomies/{taxonomy\_uid} with the body { "taxonomy": … }. Query parameters are included only when collection is non-empty.
*   The API returns a JSON response. Deserialize it using OpenTResponse<T>() or similar if needed.
*   Call Locales / LocalesAsync to read locale data, and call stack.Locale().Query() to list available locale codes.

```
The following example shows how to create a localized version for the taxonomy targeting the fr-fr locale.
Note: The targeted locale must exist on the stack.

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
using Contentstack.Management.Core.Exceptions;

try 
{
    // Initialize the Contentstack client and target the stack
    ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
    Stack stack = client.Stack("<API_KEY>");


    // Define the translated properties for the taxonomy
    TaxonomyModel model = new TaxonomyModel
    {
        Uid = "<TAXONOMY_UID>",
        Name = "Catégories",
        Description = "Catégories globales"
    };


    // Initialize query parameters to target the specific locale (e.g., 'fr-fr')
    ParameterCollection collection = new ParameterCollection();
    collection.Add("locale", "fr-fr");


    // Execute the localization request asynchronously passing both model and params
    ContentstackResponse response = await stack.Taxonomy("<TAXONOMY_UID>").LocalizeAsync(model, collection);


    // Output success message
    Console.WriteLine("Taxonomy localized.");
} 
catch (ContentstackException ex) 
{
    Console.WriteLine($"Error: {ex.ErrorMessage}");
}
```

Defines the localized taxonomy data for Localize(). Provide values to send the localized payload to the server.

Defines query parameters for Localize() that specify the target locale. Provide values to ensure the payload is assigned to the correct locale code.

## Import / ImportAsync

The Import and ImportAsync actions upload a taxonomy configuration file into the stack via multipart form data.

**Validation**

*   Use stack.Taxonomy() (no UID) for import. Calling stack.Taxonomy("TAXONOMYUID").Import(...) throws InvalidOperationException before the request.
*   Passing null for the model parameter throws ArgumentNullException when constructing the upload service.
*   Provide valid inputs to TaxonomyImportModel:
    *   filePath must be non-null and accessible. Invalid paths or permissions throw IOException (or related System.IO exceptions).
    *   A null stream throws ArgumentNullException.
*   Passing a null or empty collection does not throw. The API validates any query parameters after the request.

```
The following example shows how to read a taxonomy JSON file from the local disk and import it into the stack.
using System;
using System.IO;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Exceptions;

try 
{
    // Initialize the Contentstack client and target the stack
    ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
    Stack stack = client.Stack("<API_KEY>");


    // Open the local JSON file containing the taxonomy data as a stream
    using Stream stream = File.OpenRead("path/to/taxonomy.json");


    // Assign the file stream and expected file name to the import model
    TaxonomyImportModel model = new TaxonomyImportModel(stream, "taxonomy.json");


    // Execute the import process asynchronously
    ContentstackResponse response = await stack.Taxonomy().ImportAsync(model);


    // Output success message
    Console.WriteLine("Taxonomy imported successfully.");
} 
catch (ContentstackException ex) 
{
    Console.WriteLine($"Error: {ex.ErrorMessage}");
}
catch (IOException ex)
{
    Console.WriteLine($"File Error: {ex.Message}");
}
```

Defines the file stream and filename for Import(). Provide values to upload the taxonomy configuration file to the stack.

Defines optional query parameters for Import(). Provide values to control import processing rules.

## Terms

The Terms() method returns a Term instance scoped to the parent taxonomy. It does not make an API call.

The SDK constructs the resourcePath based on scope:

*   **Collection scope:** /taxonomies/{taxonomy\_uid}/terms
*   **Single-term scope:** /taxonomies/{taxonomy\_uid}/terms/{term\_uid}

Use this method to navigate to term-level APIs within a taxonomy.

**Note:** The Terms() method acts as a navigation layer and does not execute an API request. It returns a Term instance scoped to the parent taxonomy, which is used to perform term-level operations such as Create(), Fetch(), Move(), Delete(), and Descendants().

**Validation**

*   Calling Terms() on stack.Taxonomy("TAXONOMYUID") with an empty taxonomy UID throws InvalidOperationException before any HTTP request.
*   Pass null or omit termUid to use collection scope. Terms() does not throw in this case.
*   Pass a non-empty termUid only when you need single-term scope. Methods that require a term UID (for example Descendants) throw InvalidOperationException if called on a collection-scoped instance.
*   The SDK does not validate whether termUid exists. Invalid or unknown UIDs produce ContentstackErrorException only when a terminal API call is executed.
*   Passing an empty string for termUid behaves like null (collection scope) for path construction. Methods requiring a term UID still fail client-side.

**Behavior**

*   Each terminal method you call on the returned Term maps to one HTTP request.
*   The SDK does not fetch data automatically; use Query().Find() / FindAsync() for listing and handle pagination explicitly if supported.

```
The following example shows how to obtain a general term collection scope versus a single specific term scope.
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;

// Initialize the Contentstack client with the authentication token
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

// Target the specific stack using its API key
Stack stack = client.Stack("<API_KEY>");

// Collection Context (returns a Terms instance for creation or multi-item queries)
Term termsCollection = stack.Taxonomy("<TAXONOMY_UID>").Terms();

// Single Term Context (returns a specific Term instance for fetch, update, delete)
Term singleTerm = stack.Taxonomy("<TAXONOMY_UID>").Terms("<TERM_UID>");
```

Defines the term UID for Terms(termUid). Provide a value to target a specific term, or use null to operate on a collection.

## Taxonomy | .NET Management SDK | Contentstack

Taxonomy organizes content into a hierarchy of terms and manages create, export, and retrieval operations per stack in the .NET Management SDK.