# REST: Update Workloads

> REST: Update Workloads - Promote and replacement-history endpoints.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-06-22T16:50:38.255826+00:00` (UTC).

## Primary page

- [REST: Update Workloads](https://docs.datarobot.com/en/docs/workload-api/update-workloads/update-rest-endpoints.html.md): Full documentation for this topic (Markdown sidecar).

## Sections on this page

- [Promote](https://docs.datarobot.com/en/docs/workload-api/update-workloads/update-rest-endpoints.html.md#promote): In-page section heading.
- [Replacements](https://docs.datarobot.com/en/docs/workload-api/update-workloads/update-rest-endpoints.html.md#replacements): In-page section heading.
- [Replacement history](https://docs.datarobot.com/en/docs/workload-api/update-workloads/update-rest-endpoints.html.md#replacement-history): In-page section heading.

## Related documentation

- [Workload API](https://docs.datarobot.com/en/docs/workload-api/index.html.md): Linked from this page.
- [Update existing Workloads](https://docs.datarobot.com/en/docs/workload-api/update-workloads/index.html.md): Linked from this page.
- [REST: operate Workloads](https://docs.datarobot.com/en/docs/workload-api/operate-workloads/operate-rest-endpoints.html.md#runtime-settings): Linked from this page.
- [Promote to production](https://docs.datarobot.com/en/docs/workload-api/update-workloads/promote-production.html.md): Linked from this page.
- [Replace and roll out](https://docs.datarobot.com/en/docs/workload-api/update-workloads/replace-artifact-rollouts.html.md): Linked from this page.

## Documentation content

These endpoints drive change events on a running Workload—promotion from draft to production and inspection of past replacements. Runtime updates that trigger a replacement ( `PATCH /workloads/{workload_id}/settings`) are documented under [REST: operate Workloads](https://docs.datarobot.com/en/docs/workload-api/operate-workloads/operate-rest-endpoints.html.md#runtime-settings) because they live on the same settings surface used for routine tuning.

## Promote

Promote a draft Workload to production in place. See [Promote to production](https://docs.datarobot.com/en/docs/workload-api/update-workloads/promote-production.html.md) for semantics and the preserved-identity guarantees.

| Verb | Path | Description |
| --- | --- | --- |
| POST | /workloads/{workload_id}/promote | Lock the draft artifact, assign a version, reset stats, and remove the draft TTL (time-to-live). |

## Replacements

Trigger, inspect, and cancel artifact replacements on a Workload. See [Replace and roll out](https://docs.datarobot.com/en/docs/workload-api/update-workloads/replace-artifact-rollouts.html.md) for the lifecycle and rollout strategy.

| Verb | Path | Description |
| --- | --- | --- |
| POST | /workloads/{workload_id}/replacement | Start a replacement onto a new artifact. Body is a StartReplacementRequest (artifactId and strategy required; config and runtime optional). Returns 202 with a Replacement. |
| GET | /workloads/{workload_id}/replacement | Get the current active Replacement for the Workload. |
| DELETE | /workloads/{workload_id}/replacement | Cancel an active replacement. Returns 202. |

## Replacement history

Inspect previous replacements on a Workload, including strategy, candidate artifact, and final outcome.

| Verb | Path | Description |
| --- | --- | --- |
| GET | /workloads/{workload_id}/history | List the replacement history for a Workload (ReplacementHistoryListResponse). |