# Promote asset

`POST /v1/promotions`

Available as MCP tool `promote-asset` (Replace).

Promotion endpoints allow you to push assets from staging to production environments in your Redox organization. This creates a promotion association between the two assets so that you can keep track of when production assets might be out of date. Currently, you can promote config modifiers.

[Learn more about promotions](https://docs.redoxengine.com/permalink/7MWLANlhoIOUZzFb1Y6i93). Or learn how to promote any of these assets in the Redox dashboard:

- [config modifiers](https://docs.redoxengine.com/permalink/6sZ0Y9XdnMRCyoSWlqscjM/#promote-a-config-modifier)
- [filters](https://docs.redoxengine.com/permalink/Zn8kiEw3GdyBFaSwQNSAN/#promote-a-filter)
- [translation sets](https://docs.redoxengine.com/permalink/4GJXunyoAI3s05VrrRkJ09/#promote-a-translation-set)

### Promote asset

Promote one or more assets (e.g., config modifier, filter, translation set) from a staging environment to a production environment.

If a user edits the asset in staging later, a new version of it is created. That means you have to promote it to production again. You can use this same endpoint for promoting or re-promoting an individual asset or bulk promoting one or more asset types. 

> **Only for engineer or support roles**
>
> Any user may view existing data operations (e.g., filters, translation sets, config modifiers) in a given environment. However, you must be assigned to an engineer or a support role to create, manage, and promote these assets. [Learn about roles](/basics/managing-access-for-your-redox-organization/what-are-user-roles-and-groups).
>
> A user must be assigned to an engineer or support role in _both_ environments to promote an asset. 

## Request body

Contains the necessary details to promote asset(s) from staging to production.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `promotingAssets` | Array of object | Yes | Lists the staging assets to promote (max allowed is 50). Duplicate asset entries cause the request to fail. |
| `promotingAssets[].id` | string (uuid) | Yes | Contains the unique identifier of the asset. |
| `promotingAssets[].type` | string | Yes | Possible values: configModifier, filter, translationSet |
| `fromEnvironment` | object | Yes | Specifies the staging environment where the original asset exists. |
| `fromEnvironment.id` | string (uuid) | Yes | Contains the unique identifier of the Redox environment. |
| `toEnvironment` | object | Yes | Specifies the production environment that the asset should be promoted to. |
| `toEnvironment.id` | string (uuid) | Yes | Contains the unique identifier of the Redox environment. |

## Request example

_Generated from the schema: the values are placeholders, not a real payload._

```bash
curl 'https://api.redoxengine.com/platform/v1/promotions' \
--request POST \
--header 'Authorization: Bearer $API_TOKEN' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
  "promotingAssets": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "type": "configModifier"
    }
  ],
  "fromEnvironment": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  },
  "toEnvironment": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}'
```

## Responses

### 200

Contains a payload with the outcome (i.e., succeeded or failed) of each promoted asset. A `200` means Redox successfully processed the request, but doesn't necessarily indicate a successful outcome for each individual promotion. Check the `failures` array for details.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `meta` | object | No |  |
| `meta.version` | string | No | Lists the major and minor version number for the format of the returned payload. The payload format or shape may change between minor versions, like including additional or extended fields in later versions. We include the version data in each response so that you have the option to handle the signaled differences. |
| `payload` | object | No |  |
| `payload.promotedAssets` | Array of object | No | Lists the assets that were promoted, with their IDs and versions in the production environment. |
| `payload.promotedAssets[].id` | string (uuid) | No | Contains the unique identifier of the asset. |
| `payload.promotedAssets[].version` | number | No | Specifies the version of the promoted asset in the production environment. |
| `payload.promotedAssets[].action` | string | No | Indicates whether the asset was promoted for the first time (i.e., created) or re-promoted with a new version (i.e., updated). Possible values: created, updated |
| `payload.promotedAssets[].environment` | object | No | Describes the Redox environment that the asset belongs to. |
| `payload.promotedAssets[].environment.id` | string (uuid) | No | Contains the unique identifier of the Redox environment. |
| `payload.promotedAssets[].type` | string | No | Possible values: configModifier, filter, translationSet |
| `payload.promotedAssets[].promotingAsset` | object | No | Contains details about the original asset in the staging environment that was promoted to create the production asset. |
| `payload.promotedAssets[].promotingAsset.id` | string (uuid) | No | Contains the unique identifier of the asset. |
| `payload.promotedAssets[].promotingAsset.environment` | object | No | Describes the Redox environment that the asset belongs to. |
| `payload.promotedAssets[].promotingAsset.environment.id` | string (uuid) | No | Contains the unique identifier of the Redox environment. |
| `payload.promotedAssets[].promotingAsset.type` | string | No | Possible values: configModifier, filter, translationSet |
| `payload.failures` | Array of object | No | Lists any assets that weren't promoted, along with the error that prevented it. See `error.meta.isTransient` to learn whether you can safely retry promoting an asset. This array is empty when every asset promoted successfully. |
| `payload.failures[].promotingAsset` | object | No | Identifies the staging asset that failed to promote. |
| `payload.failures[].promotingAsset.id` | string (uuid) | No | Contains the unique identifier of the asset. |
| `payload.failures[].promotingAsset.type` | string | No | Possible values: configModifier, filter, translationSet |
| `payload.failures[].error` | object | No | Explains why one item in a bulk request failed. The overall request still returns `200`. A request that's rejected before any work starts (e.g., due to a malformed body) returns `400` instead. |
| `payload.failures[].error.id` | string | Yes | Contains a unique identifier for this error instance. |
| `payload.failures[].error.code` | string | Yes | Identifies the error type, which can be used to find relevant troubleshooting information. |
| `payload.failures[].error.title` | string | Yes | Displays the high-level error message. |
| `payload.failures[].error.detail` | string | Yes | Contains the specific error details for this item. |
| `payload.failures[].error.meta` | object | No | Contains additional details about the failure. Some errors add other properties, such as the ID of an asset that was partially created. |
| `payload.failures[].error.meta.isTransient` | boolean | No | Indicates whether retrying this item as-is might succeed. `true` means the failure was temporary (e.g., a timeout), so you can retry the item. `false` means the item will continue to fail until you correct the issue (e.g., the asset doesn't exist or its name is a duplicate). When absent, the failure wasn't classified; review `detail` before retrying. |

_Generated from the schema: the values are placeholders, not a real payload._

```json
{
  "meta": {
    "version": "1.0.0"
  },
  "payload": {
    "promotedAssets": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "version": 1,
        "action": "created",
        "environment": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        },
        "type": "configModifier",
        "promotingAsset": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "environment": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          },
          "type": "configModifier"
        }
      }
    ],
    "failures": [
      {
        "promotingAsset": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "type": "configModifier"
        },
        "error": {
          "id": "string",
          "code": "asset.not.found",
          "title": "Not Found",
          "detail": "string",
          "meta": {
            "isTransient": true
          }
        }
      }
    ]
  }
}
```

### 400

Bad Request

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.error` | object | No | Contains the error message details. |
| `payload.error.id` | string | No | Contains a unique identifier for the given error instance. |
| `payload.error.title` | string | No | Displays the high-level error message, typically something succinct like `Bad Request`. |
| `payload.error.code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |
| `payload.error.detail` | string | No | Contains the specific error details for this message. |
| `payload.error.status` | number | No | Displays the corresponding HTTP status code for the error. |
| `payload.error.transient` | boolean | No | Describes whether the error will resolve itself. If `true`, no further action needs to be taken. If `false`, you may need to troubleshoot on your end to resolve the issue before the error can be processed. |

```json
{
  "payload": {
    "error": {
      "title": "Bad Request",
      "code": "validation.error.bad.request",
      "detail": "Error details",
      "status": 400,
      "transient": false
    }
  }
}
```

### 403

Forbidden

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.errors` | Array of object | No |  |
| `payload.errors[].title` | string | No | Displays the high-level error message, typically something succinct like `Forbidden`. |
| `payload.errors[].code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |

```json
{
  "payload": {
    "errors": [
      {
        "title": "Forbidden",
        "code": "authorization.forbidden"
      }
    ]
  }
}
```

### 500

Internal Server Error

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.error` | object | No | Contains the error message details. |
| `payload.error.title` | string | No | Displays the high-level error message, typically something succinct like `Failed in step X`. |
| `payload.error.code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |
| `payload.error.detail` | string | No | Contains the specific error details for this message. |
| `payload.error.status` | number | No | Displays the corresponding HTTP status code for the error. |
| `payload.error.transient` | boolean | No | Describes whether the error will resolve itself. If `true`, no further action needs to be taken. If `false`, you may need to troubleshoot on your end to resolve the issue before the error can be processed. |

```json
{
  "payload": {
    "error": {
      "title": "Internal Server Error",
      "code": "failed.db.lookup",
      "detail": "Error details",
      "status": 500,
      "transient": true
    }
  }
}
```
