Releases
You can pin a set of entries and assets (along with the deploy action, i.e., publish/unpublish) to a ‘release’, and then deploy this release to an environment. This will publish/unpublish all the items of the release to the specified environment. Read more about Releases.
You can now pass the branch header in the API request to fetch or manage modules located within specific branches of the stack. Additionally, you can also set the include_branch query parameter to true to include the _branch top-level key in the response. This key specifies the unique ID of the branch where the concerned Contentstack module resides.
NotePass the release_version parameter as 2.0 in the Headers section if you have the latest release enabled for your organization. Reach out to our support team for more information.
Get all Releases
https://api.contentstack.io/v3/releases?include_count={boolean_value}&count={boolean_value}&include_items_count={boolean_value}&limit={limit_value}&skip={skip_value}The Get all Releases request retrieves a list of all Releases of a stack along with details of each Release. To configure the permissions for your application via OAuth, please include the cm.releases.management:read scope.
{
"releases": [{
"name": "Release Name",
"description": "2018-12-12",
"uid": "blt123123bfc123fdd1",
"created_by": "blt42e123123a2b1239f",
"updated_by": "blt42e123123a2b1239f",
"created_at": "2018-11-05T11:22:20.027Z",
"updated_at": "2019-03-08T10:30:19.493Z",
"locked": true,
"status": [{
"environment": "bltfd123123123123cb",
"time": "2019-03-08T10:30:19.451Z",
"status": "success",
"user": "blt42e55757d70d5f81026a2b9f"
}],
"items_count": 10
}]
}Get a single Release
https://api.contentstack.io/v3/releases/{release_uid}The Get a single Release request gets the details of a specific Release in a stack.
When executing the API request, provide the Release UID as parameter.
To configure the permissions for your application via OAuth, please include the cm.releases.management:read scope.
{
"release": {
"uid": "bl***************38",
"name": "Release Name",
"description": "Fall Collection",
"locked": false,
"sys_version": 2,
"created_at": "2025-04-04T08:41:52.729Z",
"updated_at": "2025-07-24T10:34:29.852Z",
"created_by": "bl***************8f",
"updated_by": "bl***************2d",
"status": [
{
"environment": "bl***************91",
"status": "success",
"user": "bl***************2d",
"job_id": "7a78cb20-77b4-4bc5-93c0-092bcdde6c5a",
"time": "2025-07-24T10:33:50.811Z"
}
],
"_deploy_latest": false,
"items": [
{
"uid": "bl***************1a",
"action": "publish",
"locale": "en-us",
"content_type_uid": "sample",
"version": 2,
"title": "Entry name",
"variant_id": null
},
{
"uid": "bl***************24",
"action": "publish",
"locale": "en-us",
"content_type_uid": "sample",
"version": 2,
"title": "AI Innovation",
"variant_id": null
},
{
"uid": "bl***************10",
"action": "publish",
"locale": "en-us",
"content_type_uid": "blog",
"version": 14,
"title": "My First Blog",
"variant_id": null
},
{
"uid": "bl***************79",
"action": "publish",
"locale": "en-us",
"content_type_uid": "sample",
"version": 8,
"title": "My first Article",
"variant_id": null
}
]
}
}Create a Release
https://api.contentstack.io/v3/releasesThe Create a Release request allows you to create a new Release in your stack. To create a release, you need to provide the name of the release in the request body.
To configure the permissions for your application via OAuth, please include the cm.releases.management:write scope.
{
"release": {
"name": "Release Name",
"description": "2018-12-12",
"locked": false,
"archived": false
}
}{
"notice": "Release created successfully.",
"release": {
"name": "Release Name",
"description": "2018-12-12",
"locked": false,
"uid": "blt123123aaa321321",
"created_by": "blt123123123123123",
"updated_by": "blt123123123123123",
"created_at": "2017-12-12T12:12:12:122Z",
"updated_at": "2017-12-12T12:12:12:122Z",
"status": [],
"_deploy_latest": false
}
}Update a Release
https://api.contentstack.io/v3/releases/{release_uid}The Update a Release call allows you to update the details of a Release, i.e., the ‘name’ and ‘description’.
When executing this API request, provide the Release UID as parameter. In the 'Body' section, you need to provide the new name and description of the Release that you want to update.
To configure the permissions for your application via OAuth, please include the cm.releases.management:write scope.
{
"release": {
"name": "Release Name",
"description": "2018-12-22"
}
}{
"notice": "Release updated successfully.",
"release": {
"name": "Release Name",
"description": "2018-12-22",
"locked": false,
"uid": "blt9dc98b5d9d4d1e4a",
"created_by": "blta068b6e50264acf6",
"updated_by": "blta068b6e50264acf6",
"created_at": "2023-02-28T07:11:57.077Z",
"updated_at": "2023-02-28T07:19:30.886Z",
"status": [],
"_deploy_latest": false
}
}Delete a Release
https://api.contentstack.io/v3/releases/{release_uid}The Delete a Release request allows you to delete a specific Release from a stack.
When executing the API request, provide the Release UID.
To configure the permissions for your application via OAuth, please include the cm.releases.management:write scope.
{
"notice": "Release deleted successfully."
}Get all items in a Release
https://api.contentstack.io/v3/releases/{release_uid}/itemsThe Get all items in a Release request retrieves a list of all items (entries and assets) that are part of a specific Release.
When executing the API request, you need to provide the Release UID.
To configure the permissions for your application via OAuth, please include the cm.release:read scope.
{
"items": [
{
"action": "publish",
"title": "Group",
"uid": "blt63177c0f00f20b61",
"locale": "en-us",
"version": 2,
"content_type_uid": "test_fields"
},
{
"action": "publish",
"title": "Modular Blocks",
"uid": "bltcad3ea0479ffb274",
"locale": "en-us",
"version": 1,
"content_type_uid": "test_fields"
},
{
"action": "publish",
"title": "File",
"uid": "blt47a6d5202496b1da",
"locale": "en-us",
"version": 2,
"content_type_uid": "test_fields"
}
]
}Add a single item to a Release
https://api.contentstack.io/v3/releases/{release_uid}/itemThe Add a single item to a Release request allows you to add an item (entry or asset) to a Release.
When executing the API request, you need to provide the Release UID. In the 'Body' section, you need to provide the details of the item such as the UID, version (of the entry and asset), content type UID (of an entry), the action to be performed (publish/unpublish), and the locale of the item. To add the asset in the release, the content type should be passed as "content_type_uid": "built_io_upload" in the request body.
To configure the permissions for your application via OAuth, please include the cm.release:write scope.
{
"item": {
"version": 1,
"uid": "entry_or_asset_uid",
"content_type_uid": "your_content_type_uid",
"action": "publish",
"locale": "en-us"
}
}{
"notice": "Item added to release successfully.",
"release": {
"name": "Release Name 2",
"description": "2018-12-12",
"locked": false,
"items": [
{
"action": "publish",
"title": "Sample1",
"uid": "bltc24b029fc706fc8d",
"locale": "en-us",
"version": 1,
"content_type_uid": "localization"
}
],
"uid": "bltfb07235c1e256728",
"created_by": "bltf7b2fe26db42adc6",
"updated_by": "bltf7b2fe26db42adc6",
"created_at": "2023-02-22T10:30:10.032Z",
"updated_at": "2023-02-27T13:35:20.768Z",
"ACL": [],
"app_user_object_uid": null,
"_version": 4,
"status": [],
"_deploy_latest": false,
"tags": []
}
}Add multiple items to a Release
https://api.contentstack.io/v3/releases/{release_uid}/itemsThe Add multiple items to a Release request allows you to add multiple items (entries and/or assets) to a Release.
When executing the API request, you need to provide the Release UID. In the 'Body' section, you need to provide the details of the items such as their UIDs, versions (in case of entries and assets), content type UIDs (in case of entries), the action to be performed (publish/unpublish), and the locales of the items. To add the asset in the release, the content type should be passed as "content_type_uid": "built_io_upload" in the request body.
To configure the permissions for your application via OAuth, please include the cm.release:write scope.
NoteIn a single request, you can add maximum 25 items (entries/assets) to a Release.
{
"items": [{
"uid": "entry_or_asset_uid1",
"version": 1,
"locale": "en-us",
"content_type_uid": "demo1",
"action": "publish"
}, {
"uid": "entry_or_asset_uid2",
"version": 4,
"locale": "fr-fr",
"content_type_uid": "demo2",
"action": "publish"
}]
}{
"notice": "Item(s) to be added to the release has been sent successfully.",
"release": {
"name": "Release Name 2",
"description": "2018-12-12",
"items": [{
"action": "publish",
"title": "Sample1",
"uid": "entry_or_asset_uid1",
"locale": "en-us",
"version": 1,
"content_type_uid": "demo1"
},
{
"action": "publish",
"title": "Sample2",
"uid": "entry_or_asset_uid2",
"locale": "fr-fr",
"version": 4,
"content_type_uid": "demo2"
}
],
"app_user_object_uid": "system",
"uid": "release_uid",
"created_by": "blt7d123123cc321fee9e",
"updated_by": "blt7d123123cc321fee9e",
"created_at": "2019-07-18T08:41:33.915Z",
"updated_at": "2019-07-18T08:41:33.915Z",
"ACL": [],
"_version": 1,
"locked": false,
"status": [],
"tags": []
}
}Update Release items to their latest versions
https://api.contentstack.io/v3/releases/{release_uid}/update_itemsThe Update Release items to their latest versions request let you update all the release items (entries and assets) to their latest versions before deployment.
To configure the permissions for your application via OAuth, please include the cm.release:write scope.
In the 'Body' section, you need to specify the following:
{
"items":[
"$all"
]
}
NoteThis API request only allows you to collectively update all items in the release to their latest versions and not update any particular item individually.
In case an un-localized entry in the release has been localized later, this request will update the entry to the latest localized version. For example, if you add an un-localized entry to a release and later localize it to the French (France) language, this API request will update the release with the localized French version of the entry.
- If the updated version of an entry has new references, this API request doesn't automatically add the references to the release. You need to add them manually.
- You cannot update the items in a release once you deploy it.
- If the latest version of an entry is in the in-progress state, this API request doesn't update the entry.
{
"items":[
"$all"
]
}{
"notice":"Release items updated to their latest versions successfully.",
"release":{
"name":"Sample release",
"description":"Sample release",
"uid":"blt046d036db7f2f9df",
"created_by":"blt55927d24ccdc8d74e",
"updated_by":"bltf41b5ae869879839",
"created_at":"2021-11-15T06:29:21.061Z",
"updated_at":"2021-12-01T07:09:42.201Z",
"locked":false,
"status":[
],
"_deploy_latest":false,
"items":[
{
"uid":"blta5cd0e5e62e4bc97",
"version":4,
"action":"publish",
"content_type_uid":"sample_ct",
"locale":"en-us",
"title":"Sample entry"
},
{
"uid":"blte254916f7d580dda",
"version":2,
"action":"publish",
"content_type_uid":"demo-ct",
"locale":"en-us",
"title":"11.jpg"
}
]
}
}Remove an item from a Release
https://api.contentstack.io/v3/releases/{release_uid}/itemsThe Remove an item from a Release request removes one or more items (entries and/or assets) from a specific Release.
When executing the API request, provide the Release UID. In the 'Body' section, you need to provide the details of the item such as their UIDs, version (of the entry), content type UID (of an entry), the action to be performed (publish/unpublish), and the locale of the item.
To configure the permissions for your application via OAuth, please include the cm.release:write scope.
{
"items": [{
"uid": "blt123123123123",
"version": 1,
"locale": "ja-jp",
"content_type_uid": "category",
"action": "publish"
}]
}{
"notice": "Item(s) send to remove from release successfully.",
"release": {
"name": "Release Name 2",
"description": "2018-12-12",
"items": [{
"action": "publish",
"title": "Sample1",
"uid": "blt123123ef321321",
"locale": "en-us",
"version": 1,
"content_type_uid": "demo1"
},
{
"action": "unpublish",
"title": "Sample2",
"uid": "blt321321fe123123",
"locale": "en-us",
"version": 1,
"content_type_uid": "demo2"
}
],
"uid": "blt123123ab12312de",
"created_by": "blt123123123123123",
"updated_by": "blt123123123123322",
"created_at": "2017-12-12T12:12:12:122Z",
"updated_at": "2017-12-14T13:13:13:122Z",
"locked": false,
"status": []
}
}Delete multiple items from a Release
https://api.contentstack.io/v3/releases/{release_uid}/items?all={boolean_value}The Delete multiple items from a Release request deletes one or more items (entries and/or assets) from a specific Release.
When executing the API request, provide the Release UID. In the 'Body' section, you need to provide the UIDs of the items along with details such as their locale, versions, the action to be performed on the items (publish/unpublish), and content type UID of entries (if any).
To configure the permissions for your application via OAuth, please include the cm.release:write scope.
{
"items": [{
"uid": "item_uid",
"locale": "en-us",
"version": 1,
"content_type_uid": "your_content_type_uid",
"action": "publish_or_unpublish"
}]
}{
"notice": "Item(s) send to remove from release successfully.",
"release": {
"name": "Release Name",
"description": "2018-12-12",
"items": [{
"action": "publish_or_unpublish",
"title": "Sample",
"uid": "item_uid",
"locale": "en-us",
"version": 1,
"content_type_uid": "your_content_type_uid"
}
],
"uid": "blt123123ab12312de",
"created_by": "blt123123123123123",
"updated_by": "blt123123123123322",
"created_at": "2017-12-12T12:12:12:122Z",
"updated_at": "2017-12-14T13:13:13:122Z",
"locked": false,
"status": []
}
}Deploy a Release
https://api.contentstack.io/v3/releases/{release_uid}/deployThe Deploy a Release request deploys a specific Release to specific environment(s) and locale(s).
When executing the API request, provide the Release UID. In the 'Body' section, you need to provide the details of the Release that you want to deploy. For example, you need to provide the scheduled time (in case of scheduled release), action, and environment(s) on which the Release should be deployed.
To configure the permissions for your application via OAuth, please include the cm.release:deploy scope.
{
"release": {
"scheduled_at": "2018-12-12T13:13:13.122Z",
"action": "publish/unpublish",
"environments": [
"Production",
"UAT"
]
}
}{
"notice": "Release sent successfully for deployment."
}Clone a Release
https://api.contentstack.io/v3/releases/{release_uid}/cloneThe Clone a Release request allows you to clone (make a copy of) a specific Release in a stack. When executing the API request, provide the Release UID.
In the 'Body' section, you need to provide the new name and description of the cloned Release.
To configure the permissions for your application via OAuth, please include the cm.release:clone scope.
{
"release": {
"name": "New Release Name",
"description": "2018-12-12"
}
}{
"notice": "Release cloned successfully.",
"release": {
"name": "New Release Name",
"description": "2018-12-12",
"items": [{
"action": "publish",
"title": "Sample1",
"uid": "blt123123ef321321",
"locale": "en-us",
"version": 1,
"content_type_uid": "demo1"
},
{
"action": "unpublish",
"title": "Sample2",
"uid": "blt321321fe123123",
"locale": "en-us",
"version": 1,
"content_type_uid": "demo2"
}
],
"uid": "blt1123ab123ede123",
"created_by": "blt123123123123123",
"updated_by": "blt123123123123123",
"created_at": "2017-12-12T12:12:12:122Z",
"updated_at": "2017-12-12T12:12:12:122Z",
"locked": false,
"status": []
}
}Lock a Release
https://api.contentstack.io/v3/releases/{release_uid}The Lock a Release request prevents further modifications to the specified release by locking it. In the 'Body' section, set the locked parameter as true to lock the release.
Your request body is as follows:
{
"release": {
"locked": true
}
}{
"release": {
"locked": true
}
}{
"notice": "Release updated successfully.",
"release": {
"uid": "blt4**************a",
"name": "Christmas Releases",
"description": "",
"locked": true,
"sys_locked": false,
"sys_version": 2,
"status": [
{
"environment": "bltf6**************0",
"status": "success",
"user": "bltd**************2",
"job_id": "445f0669-50fc-4918-8f36-09abb3d573f4",
"time": "2025-03-04T12:06:27.951Z"
},
{
"environment": "blta**************1",
"status": "success",
"user": "bltd**************2",
"job_id": "44****69-50fc-4918-8f36-09********f4",
"time": "2025-03-04T12:06:27.974Z"
}
],
"created_at": "2025-02-13T05:55:46.177Z",
"updated_at": "2025-06-25T08:24:04.621Z",
"created_by": "blt3**************4",
"updated_by": "blte9**************1"
}
}Unock a Release
https://api.contentstack.io/v3/releases/{release_uid}The Unlock a Release request removes the lock from a release, allowing further modifications to the specified release. In the 'Body' section, set the locked parameter as false to unlock the release.
Your request body is as follows:
{
"release": {
"locked": false
}
}{
"release": {
"locked": false
}
}{
"notice": "Release updated successfully.",
"release": {
"uid": "blt4**************a",
"name": "Christmas Releases",
"description": "",
"locked": false,
"sys_locked": false,
"sys_version": 2,
"status": [
{
"environment": "bltf6**************0",
"status": "success",
"user": "bltd**************2",
"job_id": "445f0669-50fc-4918-8f36-09abb3d573f4",
"time": "2025-03-04T12:06:27.951Z"
},
{
"environment": "blta**************1",
"status": "success",
"user": "bltd**************2",
"job_id": "44****69-50fc-4918-8f36-09********f4",
"time": "2025-03-04T12:06:27.974Z"
}
],
"created_at": "2025-02-13T05:55:46.177Z",
"updated_at": "2025-06-25T08:24:04.621Z",
"created_by": "blt3**************4",
"updated_by": "blte9**************1"
}
}