Release

View as Markdown

Release

The Release class creates, reads, updates, and deletes the releases of a stack. It also clones and deploys a release, and opens the items of one release.

When to Use This Class: Use this class to publish or unpublish a set of entries and assets together. For example, a product launch that goes live in several locales at once.

Conceptual Role: Acts as the Content Management API (CMA) client for the /releases endpoint. Call stack.Release() to get an instance, and call Item on it to reach the ReleaseItem class.

Returns: Release. A handle for release operations.

Instance State

The UID you pass to stack.Release() decides which methods you can call on the instance:

  • Call stack.Release() without a UID to work with the release collection, for example Query or Create.
  • Call stack.Release("<RELEASE_UID>") to work with one release, for example Deploy or Item.

The Method Index below lists every method in each group.

If you call a method from the other group, it throws before any request leaves the SDK. A collection method on an instance with a UID throws InvalidOperationException, and a single-release method on an instance with no UID throws ArgumentException.

Warning The SDK checks an empty string as if it were no UID, but it builds the request path from the string you pass. stack.Release("") therefore allows Create and Query, and sends them to /releases/ instead of /releases. Pass null, or call stack.Release() with no argument, when you mean the collection.

Warning Set the release UID only through stack.Release("<RELEASE_UID>"). The instance also has a settable Uid property, but the SDK builds the request path when you call stack.Release(). Setting Uid later changes which methods the SDK allows without changing which release the request targets.

Class-Level Notes

Authentication.

  • stack.Release() 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 release request. When the Stack has a management token, the SDK sends it instead of the client's authtoken.

Branch.

  • The branchUid argument of client.Stack() adds a branch header to every request from that Stack, so the request works on the releases of that branch.

Locked and archived flags.

  • ReleaseModel declares Locked and Archived as bool, so every Create and Update request carries both flags, false unless you set them.

The CMA reference documents Lock a Release and the request that removes the lock as the same PUT request as Update, with locked set to true or false. Set Locked = true on every Update of a release you want to keep locked.

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>().
  • Each async method runs its client-side checks when you call it and throws before it returns a task. await every async method so that a catch (ContentstackErrorException) block receives API errors.

Rate Limiting & Retry.

  • This SDK automatically retries on 429 with configurable delay and attempt limits.

Additional Resource For more information on retry limits and delays, refer to the ContentstackClientOptions documentation.

Capability Matrix

CapabilitySupportedNotes / Alternative
Send the release_version headerNoThe CMA reference mentions a release_version header for the latest Releases version. The SDK has no option to add it.
Lock a release, or remove its lockYesCall Update with ReleaseModel.Locked set to true or false.
Give a clone its own descriptionNoClone does not apply the description. Call Update on the clone to set it.
Deploy to environments by UIDNoDeployModel.Environments takes environment names.

Method Index

The groups below follow the Instance State split.

Work with the release collection. Available on stack.Release() when you pass no UID.

Method NameReturnsDescription
QueryA new query for releases.Builds a query that lists the releases of the stack.
CreateThe API response with the created release.Creates a release.
CreateAsyncThe API response with the created release.Creates a release asynchronously.

Work with one release. Available on stack.Release("<RELEASE_UID>").

Method NameReturnsDescription
FetchThe API response with the requested release.Retrieves one release.
FetchAsyncThe API response with the requested release.Retrieves one release asynchronously.
UpdateThe API response with the updated release.Updates the name, description, or lock state of a release.
UpdateAsyncThe API response with the updated release.Updates a release asynchronously.
DeleteThe API response for the deletion.Deletes a release.
DeleteAsyncThe API response for the deletion.Deletes a release asynchronously.
DeployThe API response for the deployment.Publishes or unpublishes every item of a release.
DeployAsyncThe API response for the deployment.Deploys a release asynchronously.
CloneThe API response with the cloned release.Copies a release under a new name.
CloneAsyncThe API response with the cloned release.Copies a release asynchronously.
ItemA new release item object.Opens the items of this release.

Class-Level Snippet

The snippet below creates a release, adds an entry to it, and deploys it to one environment and locale.

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

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

try
{
    ReleaseModel release = new ReleaseModel { Name = "Spring Launch", Description = "Spring product pages" };
    ContentstackResponse created = stack.Release().Create(release);
    string releaseUid = created.OpenJsonObjectResponse()["release"]?["uid"]?.ToString() ?? "";

    ReleaseItemModel item = new ReleaseItemModel
    {
        Uid = "<ENTRY_UID>",
        ContentTypeUID = "<CONTENT_TYPE_UID>",
        Version = 1,
        Locale = "en-us",
        Action = "publish"
    };
    stack.Release(releaseUid).Item().CreateMultiple(new List<ReleaseItemModel> { item });

    DeployModel deploy = new DeployModel
    {
        Environments = new List<string> { "<ENVIRONMENT_NAME>" },
        Locales = new List<string> { "en-us" },
        Action = "publish"
    };
    stack.Release(releaseUid).Deploy(deploy);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects a request, for example an unknown environment
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Methods

Each method of the Release class has its own section below, with its parameters, validation rules, behavior, and examples.

Clone

Clone copies the release whose UID you passed to stack.Release() into a new release with the name you give.

NameTypeDescription
name (required)string

Name of the new release.

Default: Not applicable
description (required)string

Description for the new release. Pass "" to send none.

Default: Not applicable

Returns: ContentstackResponse. The API response with the cloned release.

Validation

  • Throws ArgumentNullException (parameter name) if name is null or empty, because the API needs a name for the new release. The SDK runs this check first, before the UID check.
  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Clone copies one release. Call stack.Release("<RELEASE_UID>").
  • description set to null or "" leaves the description out of the request.
  • Throws ContentstackErrorException when the API rejects the request, for example an unknown release UID.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one POST request to /releases/<RELEASE_UID>/clone with the body {"release": {"name": ...}}. See Clone a Release in the Content Management API reference.
  • Takes no query parameter collection.
  • Returns the raw API response. The new release sits under the release key, with its own uid.
  • Known issue: The clone does not get the description you pass, because the SDK sends it under a misspelled key. Call Update on the new release with Name and Description set to add the description.

Example

Basic usage: clone a release and set its description

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

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

try
{
    ContentstackResponse response = stack.Release("<RELEASE_UID>").Clone("Spring Launch Copy", "Copy for the EU rollout");
    string cloneUid = response.OpenJsonObjectResponse()["release"]?["uid"]?.ToString() ?? "";

    // Clone does not apply the description, so set it with Update.
    stack.Release(cloneUid).Update(new ReleaseModel { Name = "Spring Launch Copy", Description = "Copy for the EU rollout" });
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Management token: clone a release without a description

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient();

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Release("<RELEASE_UID>").Clone("Spring Launch Copy", "");
    Console.WriteLine($"Clone UID: {response.OpenJsonObjectResponse()["release"]?["uid"]}");
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Edge case: an empty name throws before any request

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    client.Stack("<API_KEY>").Release("<RELEASE_UID>").Clone("", "Copy for the EU rollout");
}
catch (ArgumentNullException ex)
{
    // Fires before any request, because name is empty
    Console.WriteLine(ex.ParamName);
}

CloneAsync

CloneAsync copies the release whose UID you passed to stack.Release() into a new release, without blocking the calling thread.

NameTypeDescription
name (required)string

Name of the new release.

Default: Not applicable
description (required)string

Description for the new release. Pass "" to send none.

Default: Not applicable

Returns: Task<ContentstackResponse>. The API response with the cloned release.

Validation

  • Throws ArgumentNullException (parameter name) if name is null or empty, and ArgumentException (parameter uid) if the instance has no UID. The SDK throws both when you call CloneAsync, before it returns a task.
  • description set to null or "" leaves the description out of the request.
  • Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends the same POST request as Clone and completes the task when the API responds.
  • Known issue: The clone does not get the description you pass. Call UpdateAsync on the new release to add it.
  • Otherwise behaves like Clone.

Example

Basic usage: clone a release and set its description

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

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

try
{
    ContentstackResponse response = await stack.Release("<RELEASE_UID>").CloneAsync("Spring Launch Copy", "Copy for the EU rollout");
    string cloneUid = response.OpenJsonObjectResponse()["release"]?["uid"]?.ToString() ?? "";

    // CloneAsync does not apply the description, so set it with UpdateAsync.
    await stack.Release(cloneUid).UpdateAsync(new ReleaseModel { Name = "Spring Launch Copy", Description = "Copy for the EU rollout" });
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Management token: clone a release without a description

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient();

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Release("<RELEASE_UID>").CloneAsync("Spring Launch Copy", "");
    Console.WriteLine($"Clone UID: {response.OpenJsonObjectResponse()["release"]?["uid"]}");
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Create

Create creates a release in the stack from the name and description you set on a ReleaseModel.

NameTypeDescription
model (required)ReleaseModel

Name, description, and flags of the new release.

Default: Not applicable
collectionParameterCollection?

Adds query parameters, for example include_branch.

Default: null

Returns: ContentstackResponse. The API response with the created release.

Validation

  • Throws InvalidOperationException if the instance has a release UID, because Create adds a release to the collection. Call stack.Release() with no UID.
  • Throws ArgumentNullException (parameter dataModel) if model is null, before any request.
  • The SDK does not check Name. The API reference requires a name to create a release, so a model without one 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 /releases with the body {"release": {...}}, and the entries of collection as query parameters. See Create a Release in the Content Management API reference.
  • The body holds every ReleaseModel property that is not null. locked and archived are always present, false unless you set them.
  • Returns the raw API response. The new release sits under the release key, and its uid is the value to pass to stack.Release() later.
  • Creates an empty release. Add entries and assets with the Item method afterwards.

Example

Basic usage: create a release

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

ReleaseModel model = new ReleaseModel { Name = "Spring Launch", Description = "Spring product pages" };

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Release().Create(model);
    JsonObject json = response.OpenJsonObjectResponse();
    Console.WriteLine($"Release UID: {json["release"]?["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 locked release with a branch key in the response

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

ReleaseModel model = new ReleaseModel
{
    Name = "Holiday Campaign",
    Description = "Holiday landing pages",
    Locked = true,
    Archived = false
};

ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Release().Create(model, collection);
    JsonObject json = response.OpenJsonObjectResponse();
    Console.WriteLine($"Created on branch {json["release"]?["_branch"]}");
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

CreateAsync

CreateAsync creates a release in the stack from a ReleaseModel, without blocking the calling thread.

NameTypeDescription
model (required)ReleaseModel

Name, description, and flags of the new release.

Default: Not applicable
collectionParameterCollection?

Adds query parameters, for example include_branch.

Default: null

Returns: Task<ContentstackResponse>. The API response with the created release.

Validation

  • Throws InvalidOperationException if the instance has a release UID, because CreateAsync adds a release to the collection. The SDK throws it when you call CreateAsync, before it returns a task.
  • Throws ArgumentNullException (parameter dataModel) if model is null, before it returns a task.
  • collection set to null sends no query parameters.
  • Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends the same POST request as Create and completes the task when the API responds.
  • Otherwise behaves like Create.

Example

Basic usage: create a release

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

ReleaseModel model = new ReleaseModel { Name = "Spring Launch", Description = "Spring product pages" };

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Release().CreateAsync(model);
    JsonObject json = response.OpenJsonObjectResponse();
    Console.WriteLine($"Release UID: {json["release"]?["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 locked release with a branch key in the response

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

ReleaseModel model = new ReleaseModel { Name = "Holiday Campaign", Description = "Holiday landing pages", Locked = true };

ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Release().CreateAsync(model, collection);
    Console.WriteLine(response.OpenJsonObjectResponse()["release"]?["name"]);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Delete

Delete deletes the release whose UID you passed to stack.Release().

NameTypeDescription
collectionParameterCollection?

Adds query parameters to the request.

Default: null

Returns: ContentstackResponse. The API response for the deletion.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Delete removes one release. Call stack.Release("<RELEASE_UID>").
  • The SDK does not check the UID format. A UID that names no release 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 DELETE request to /releases/<RELEASE_UID>, with the entries of collection as query parameters. See Delete a Release in the Content Management API reference.
  • Sends the request without a Content-Type header, because the request has no body.
  • Returns the raw API response.

Warning Deleting a release is irreversible. The SDK and the API offer no way to restore a deleted release.

Example

Basic usage: delete a release

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>").Release("<RELEASE_UID>").Delete();
    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}");
}

All parameters: delete with a query parameter collection

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>").Release("<RELEASE_UID>").Delete(collection);
    Console.WriteLine(response.OpenResponse());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

DeleteAsync

DeleteAsync deletes the release whose UID you passed to stack.Release(), without blocking the calling thread.

NameTypeDescription
collectionParameterCollection?

Adds query parameters to the request.

Default: null

Returns: Task<ContentstackResponse>. The API response for the deletion.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because DeleteAsync removes one release. The SDK throws it when you call DeleteAsync, before it returns a task.
  • collection set to null sends no query parameters.
  • Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends the same DELETE request as Delete and completes the task when the API responds.
  • Otherwise behaves like Delete.

Warning Deleting a release is irreversible. The SDK and the API offer no way to restore a deleted release.

Example

Basic usage: delete a release

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>").Release("<RELEASE_UID>").DeleteAsync();
    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}");
}

All parameters: delete with a query parameter collection

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>").Release("<RELEASE_UID>").DeleteAsync(collection);
    Console.WriteLine(response.OpenResponse());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Deploy

Deploy publishes or unpublishes every item of the release whose UID you passed to stack.Release(), on the environments and locales you list in a DeployModel.

NameTypeDescription
model (required)DeployModel

Environments, locales, action, and optional schedule time.

Default: Not applicable

Returns: ContentstackResponse. The API response for the deployment.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Deploy acts on one release. Call stack.Release("<RELEASE_UID>").
  • Throws ArgumentNullException (parameter dataModel) if model is null, before any request.
  • The SDK does not check the properties of model. An environment or locale that the stack does not have reaches the API, and the SDK throws the rejection as ContentstackErrorException.
  • 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 /releases/<RELEASE_UID>/deploy with the body {"release": {...}}. See Deploy a Release in the Content Management API reference.
  • The body holds every DeployModel property that is not null. Leave ScheduledAt unset to deploy when the API receives the request, or set it to schedule the deployment.
  • Takes no query parameter collection, unlike most methods of this class.
  • Returns the raw API response.

Example

Basic usage: publish a release to one environment

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

DeployModel model = new DeployModel
{
    Environments = new List<string> { "<ENVIRONMENT_NAME>" },
    Locales = new List<string> { "en-us" },
    Action = "publish"
};

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Release("<RELEASE_UID>").Deploy(model);
    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}");
}

Scheduled deployment: unpublish a release at a set time

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient();

DeployModel model = new DeployModel
{
    Environments = new List<string> { "<ENVIRONMENT_NAME>" },
    Locales = new List<string> { "en-us", "fr-fr" },
    Action = "unpublish",
    ScheduledAt = "2027-03-01T09:00:00.000Z"
};

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Release("<RELEASE_UID>").Deploy(model);
    Console.WriteLine(response.OpenResponse());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

DeployAsync

DeployAsync publishes or unpublishes every item of the release whose UID you passed to stack.Release(), without blocking the calling thread.

NameTypeDescription
model (required)DeployModel

Environments, locales, action, and optional schedule time.

Default: Not applicable

Returns: Task<ContentstackResponse>. The API response for the deployment.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because DeployAsync acts on one release. The SDK throws it when you call DeployAsync, before it returns a task.
  • Throws ArgumentNullException (parameter dataModel) if model is null, before it returns a task.
  • Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends the same POST request as Deploy and completes the task when the API responds.
  • Otherwise behaves like Deploy.

Example

Basic usage: publish a release to one environment

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

DeployModel model = new DeployModel
{
    Environments = new List<string> { "<ENVIRONMENT_NAME>" },
    Locales = new List<string> { "en-us" },
    Action = "publish"
};

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Release("<RELEASE_UID>").DeployAsync(model);
    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}");
}

Scheduled deployment: publish a release at a set time

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient();

DeployModel model = new DeployModel
{
    Environments = new List<string> { "<ENVIRONMENT_NAME>" },
    Locales = new List<string> { "en-us" },
    Action = "publish",
    ScheduledAt = "2027-03-01T09:00:00.000Z"
};

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Release("<RELEASE_UID>").DeployAsync(model);
    Console.WriteLine(response.OpenResponse());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Fetch

Fetch retrieves the details of the release whose UID you passed to stack.Release().

NameTypeDescription
collectionParameterCollection?

Adds query parameters, for example include_branch.

Default: null

Returns: ContentstackResponse. The API response with the requested release.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Fetch reads one release. Call stack.Release("<RELEASE_UID>").
  • The SDK does not check the UID format. A UID that names no release 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 /releases/<RELEASE_UID>, with the entries of collection as query parameters. See Get a single Release in the Content Management API reference.
  • The API reference lists one query parameter for the request: include_branch set to true adds the _branch key to the response.
  • Returns the raw API response. The release sits under the release key and includes the fields that ReleaseModel describes.
  • Does not return the items of the release. Call Item and then GetAll to list them.

Example

Basic usage: fetch a release 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>").Release("<RELEASE_UID>").Fetch();
    JsonObject json = response.OpenJsonObjectResponse();
    Console.WriteLine($"Release name: {json["release"]?["name"]}");
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: include the branch key

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_branch", true);

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Release("<RELEASE_UID>").Fetch(collection);
    Console.WriteLine($"Branch: {response.OpenJsonObjectResponse()["release"]?["_branch"]}");
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Typed read: deserialize the release into ReleaseModel

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>").Release("<RELEASE_UID>").Fetch();

    // The release sits under the "release" key, so deserialize that node, not the whole body.
    ReleaseModel? release = response.OpenJsonObjectResponse()["release"]?.Deserialize<ReleaseModel>();
    Console.WriteLine($"{release?.Name}: locked {release?.Locked}, archived {release?.Archived}");
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

FetchAsync

FetchAsync retrieves the details of the release whose UID you passed to stack.Release(), without blocking the calling thread.

NameTypeDescription
collectionParameterCollection?

Adds query parameters, for example include_branch.

Default: null

Returns: Task<ContentstackResponse>. The API response with the requested release.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because FetchAsync reads one release. The SDK throws it when you call FetchAsync, before it returns a task.
  • collection set to null sends no query parameters.
  • Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends the same GET request as Fetch and completes the task when the API responds.
  • Otherwise behaves like Fetch.

Example

Basic usage: fetch a release 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>").Release("<RELEASE_UID>").FetchAsync();
    JsonObject json = response.OpenJsonObjectResponse();
    Console.WriteLine($"Release name: {json["release"]?["name"]}");
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: include the branch key

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_branch", true);

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Release("<RELEASE_UID>").FetchAsync(collection);
    Console.WriteLine($"Branch: {response.OpenJsonObjectResponse()["release"]?["_branch"]}");
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Item

Item returns a ReleaseItem object that lists, adds, and removes the items of the release whose UID you passed to stack.Release().

This method takes no parameters.

Returns: ReleaseItem. A new release item object.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because the items belong to one release. Call stack.Release("<RELEASE_UID>").
  • Item sends no request, so it raises no API error. Errors come from the ReleaseItem method you call next, for example GetAll.

Behavior

  • Builds the object locally and sends nothing. The object targets /releases/<RELEASE_UID>/items.
  • Returns a new object on each call. The object keeps no state between calls, so you can call Item() once and reuse the result.

Example

Basic usage: list the items of a release

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
{
    ReleaseItem items = client.Stack("<API_KEY>").Release("<RELEASE_UID>").Item();
    ContentstackResponse response = items.GetAll();
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the GetAll request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Edge case: calling Item on the release collection throws

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ReleaseItem items = client.Stack("<API_KEY>").Release().Item();
}
catch (ArgumentException ex)
{
    // Fires before any request, because stack.Release() has no UID
    Console.WriteLine(ex.Message);
}

Query

Query returns a query object that lists the releases of the stack when you call Find or FindAsync on it.

This method takes no parameters. Chain Limit, Skip, and IncludeCount on the query object to page through the results, then call Find or FindAsync to send the request.

Returns: Query. A new query for releases.

Validation

  • Throws InvalidOperationException if the instance has a release UID, because Query lists the release collection. Call stack.Release() with no UID.
  • Query sends no request, so it raises no API error. Errors come from the Find or FindAsync call that follows, not from Query. The SDK throws an API rejection as ContentstackErrorException.
  • 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. Build a new query with stack.Release().Query() for each request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Find and FindAsync send one GET request to /releases, with every parameter you set as a query parameter. See Get all Releases in the Content Management API reference.
  • The API reference lists these query parameters for the request:
    • include_count set to true adds the total number of releases as count. IncludeCount sets it.
    • count set to true returns only the total count, without the releases.
    • include_items_count set to true adds the number of items in each release.
    • limit and skip page through the list. Limit and Skip set them.
    • include_branch set to true adds the _branch key to the response.
  • Returns the raw API response. The releases sit under the releases key.
  • Does not page through the results for you. Without Limit and Skip, the API applies its own page size.

Example

Basic usage: list the releases of a stack

using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Release().Query().Find();
    JsonArray? releases = response.OpenJsonObjectResponse()["releases"]?.AsArray();

    foreach (JsonNode? release in releases ?? new JsonArray())
    {
        Console.WriteLine($"{release?["uid"]}: {release?["name"]}");
    }
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Paging: read one page of releases with counts

using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient();

ParameterCollection collection = new ParameterCollection();
collection.Add("include_items_count", true);

try
{
    ContentstackResponse response = await client
        .Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
        .Release()
        .Query()
        .Limit(10)
        .Skip(0)
        .IncludeCount()
        .FindAsync(collection);

    JsonObject json = response.OpenJsonObjectResponse();
    Console.WriteLine($"Showing {json["releases"]?.AsArray().Count} of {json["count"]} releases");
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Edge case: setting a query parameter twice throws

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

Query query = client.Stack("<API_KEY>").Release().Query().Limit(5);

ParameterCollection collection = new ParameterCollection();
collection.Add("limit", 10);

try
{
    query.Find(collection);
}
catch (ArgumentException ex)
{
    // Fires before any request, because Limit(5) already set "limit"
    Console.WriteLine(ex.Message);
}

Update

Update replaces the name, description, and lock state of the release whose UID you passed to stack.Release().

NameTypeDescription
model (required)ReleaseModel

New name, description, and flags of the release.

Default: Not applicable
collectionParameterCollection?

Adds query parameters, for example include_branch.

Default: null

Returns: ContentstackResponse. The API response with the updated release.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Update changes one release. Call stack.Release("<RELEASE_UID>").
  • Throws ArgumentNullException (parameter dataModel) if model is null, before any request.
  • collection set to null sends no query parameters.
  • Throws ContentstackErrorException when the API rejects the request, for example an unknown release UID.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one PUT request to /releases/<RELEASE_UID> with the body {"release": {...}}, and the entries of collection as query parameters. See Update a Release in the Content Management API reference.
  • The body holds every ReleaseModel property that is not null. A Name or Description you leave null stays out of the body.
  • locked and archived are always in the body, false unless you set them. The API reference documents the same request with locked as Lock a Release. Set Locked = true to lock the release, and keep it true on every later Update that should leave the lock in place.
  • Returns the raw API response. The updated release sits under the release key.

Example

Basic usage: rename a release

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

ReleaseModel model = new ReleaseModel { Name = "Spring Launch 2027", Description = "Spring product pages" };

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Release("<RELEASE_UID>").Update(model);
    JsonObject json = response.OpenJsonObjectResponse();
    Console.WriteLine($"Release name: {json["release"]?["name"]}");
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: lock a release and include the branch key

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

ReleaseModel model = new ReleaseModel
{
    Name = "Spring Launch",
    Description = "Approved for deployment",
    Locked = true
};

ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Release("<RELEASE_UID>").Update(model, collection);
    Console.WriteLine($"Locked: {response.OpenJsonObjectResponse()["release"]?["locked"]}");
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

UpdateAsync

UpdateAsync replaces the name, description, and lock state of the release whose UID you passed to stack.Release(), without blocking the calling thread.

NameTypeDescription
model (required)ReleaseModel

New name, description, and flags of the release.

Default: Not applicable
collectionParameterCollection?

Adds query parameters, for example include_branch.

Default: null

Returns: Task<ContentstackResponse>. The API response with the updated release.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because UpdateAsync changes one release. The SDK throws it when you call UpdateAsync, before it returns a task.
  • Throws ArgumentNullException (parameter dataModel) if model is null, before it returns a task.
  • collection set to null sends no query parameters.
  • Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends the same PUT request as Update and completes the task when the API responds.
  • Otherwise behaves like Update.

Example

Basic usage: rename a release

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

ReleaseModel model = new ReleaseModel { Name = "Spring Launch 2027", Description = "Spring product pages" };

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Release("<RELEASE_UID>").UpdateAsync(model);
    JsonObject json = response.OpenJsonObjectResponse();
    Console.WriteLine($"Release name: {json["release"]?["name"]}");
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: remove the lock from a release

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

// Locked defaults to false, so this body removes the lock.
ReleaseModel model = new ReleaseModel { Name = "Spring Launch", Description = "Reopened for edits" };

ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Release("<RELEASE_UID>").UpdateAsync(model, collection);
    Console.WriteLine($"Locked: {response.OpenJsonObjectResponse()["release"]?["locked"]}");
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}