---
title: "POST /api/v1/hosting/apps/{app_id}/deployment_rollbacks"
method: POST
path: "/api/v1/hosting/apps/{app_id}/deployment_rollbacks"
tags: ["hosting"]
---

# POST /api/v1/hosting/apps/{app_id}/deployment_rollbacks

`POST /api/v1/hosting/apps/{app_id}/deployment_rollbacks`

## Request

- Base URL: `https://composal.com` (the document declares no server; this is the origin it was published from)
- URL: `https://composal.com/api/v1/hosting/apps/{app_id}/deployment_rollbacks`
- Auth: HTTP bearer

## Path parameters

- `app_id` string, required

## Request body

- DeploymentRollbackPayload
  - `app_service_id` string
  - `service` string
  - `app_environment_id` string
  - `environment` string
  - `to` string
  - `deployment` string
  - `reason` string
  - `force` boolean
  - `idempotency_key` string

## Response `200`

Existing idempotent deployment rollback

- DeploymentRollbackResult
  - `app_id` string, required
  - `service` AppService, required
    - `id` string, required
    - `hosted_app_id` string, required
    - `slug` string, required
    - `name` string, required
    - `kind` 'web' | 'worker' | 'cron' | 'static' | 'private', required
    - `runtime` 'docker' | 'node' | 'ruby' | 'python' | 'go' | 'rust' | 'static' | 'generic', required
    - `runtime_adapter_kind` 'nomad' | 'database', required
    - `runtime_adapter_settings_json` string, nullable, required
    - `nomad_namespace` string, nullable, required
    - `nomad_region` string, nullable, required
    - `cpu_mhz` integer, nullable, required
    - `memory_mb` integer, nullable, required
    - `memory_max_mb` integer, nullable, required: Hard memory limit in MB the task may burst to (Nomad MemoryMaxMB). memory_mb stays the reservation the scheduler places against, so raising this does not make a rollout harder to place. Must be >= memory_mb. Memory above the reservation is oversubscribed and best effort: under node pressure the kernel reclaims it and can OOM-kill the task. Null/absent renders no limit beyond the reservation.
    - `disk_mb` integer, nullable, required
    - `nomad_constraints_json` string, nullable, required
    - `nomad_update_strategy_json` string, nullable, required
    - `nomad_ulimits_json` string, nullable, required: Docker task ulimits as a JSON object of rlimit name to "soft:hard" (e.g. {"nofile":"65536:65536"}). Null/absent leaves the container on the daemon default.
    - `nomad_kill_timeout_seconds` integer, nullable, required: Seconds the task gets after SIGTERM before SIGKILL. Null/absent leaves Nomad's 5s default. Capped at 30 because a Nomad client silently clamps kill_timeout to its own max_kill_timeout (default 30s).
    - `nomad_shutdown_delay_seconds` integer, nullable, required: Seconds Nomad waits between deregistering the group's services and sending SIGTERM, so the edge stops routing new requests to the allocation before it is signalled. Null/absent leaves Nomad's 0s default.
    - `source_path` string, required
    - `repo_source_path` string, required
    - `build_command` string, nullable, required
    - `release_command` string, nullable, required
    - `prestart_command` string, nullable, required
    - `start_command` string, nullable, required
    - `healthcheck_path` string, nullable, required
    - `schedule` string, nullable, required
    - `internal_port` integer, nullable, required
    - `desired_instances` integer, required
    - `publicly_accessible` boolean, required
    - `auto_deploy` boolean, required
    - `deploy_paths` string[], required: Explicit repo-root-relative path prefixes/globs a push must touch to auto-deploy. Empty means default to the app root_path.
    - `effective_deploy_paths` string[], required: Tracked paths actually applied by the auto-deploy trigger (explicit deploy_paths, else [root_path]).
    - `bindings` AppServiceBinding[], required
      - `id` string, required
      - `hosted_app_id` string, required
      - `app_service_id` string, required
      - `bindable_type` string, required
      - `bindable_id` string, required
      - `binding_type` string, required
      - `name` string, required
      - `mount_path` string, nullable, required
      - `read_only` boolean, required
      - `required` boolean, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `created_at_label` string, nullable, required
    - `updated_at_label` string, nullable, required
    - `cpu_label` string, nullable, required
    - `memory_label` string, nullable, required
    - `memory_max_label` string, nullable, required
    - `disk_label` string, nullable, required
  - `environment` AppEnvironment, required
    - `id` string, required
    - `hosted_app_id` string, required
    - `location_id` string, required
    - `slug` string, required
    - `name` string, required
    - `kind` 'production' | 'staging' | 'development' | 'preview' | 'ephemeral' | 'custom', required
    - `status` 'active' | 'paused' | 'archived', required
    - `location` HostingLocation, required
      - `id` string, required
      - `code` string, required
      - `name` string, required
      - `nomad_datacenter` string, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
    - `branch_pattern` string, nullable, required
    - `base_domain` string, nullable, required
    - `auto_deploy` boolean, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `created_at_label` string, nullable, required
    - `updated_at_label` string, nullable, required
  - `location` HostingLocation, required
    - `id` string, required
    - `code` string, required
    - `name` string, required
    - `nomad_datacenter` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `current_release` DeploymentRollbackRelease, required
    - `id` string, required
    - `slug` string, required
    - `version` string, required
    - `release_kind` 'deployment' | 'rollback' | 'hotfix', required
    - `status` 'draft' | 'ready' | 'deploying' | 'active' | 'failed' | 'rolled_back', required
    - `source_ref` string, nullable, required
    - `commit_sha` string, nullable, required
    - `app_deployment_id` string, nullable, required
    - `rollback_target_release_id` string, nullable, required
    - `created_at` string, date-time, required
  - `current_deployment` AppDeployment, required
    - `id` string, required
    - `hosted_app_id` string, required
    - `organization_id` string, required
    - `app_service_id` string, required
    - `app_environment_id` string, required
    - `location_id` string, required
    - `creator_user_id` string, nullable, required
    - `number` integer, required
    - `display_id` integer, required
    - `status` 'queued' | 'building' | 'deploying' | 'active' | 'failed' | 'rolled_back' | 'canceled', required
    - `location` HostingLocation, required
      - `id` string, required
      - `code` string, required
      - `name` string, required
      - `nomad_datacenter` string, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
    - `source_ref` string, nullable, required
    - `commit_sha` string, nullable, required
    - `artifact_locator` string, nullable, required
    - `deployed_url` string, nullable, required
    - `trigger_kind` 'manual' | 'push' | 'schedule' | 'api' | 'rollback', required
    - `operation_key` string, nullable, required
    - `build_role` 'leader' | 'follower' | 'standalone', nullable, required
    - `is_rollback` boolean, required
    - `rollback_source_release_id` string, nullable, required
    - `rollback_target_release_id` string, nullable, required
    - `rollback_source_deployment_id` string, nullable, required
    - `rollback_reason` string, nullable, required
    - `idempotency_key` string, nullable, required
    - `failure_message` string, nullable, required
    - `started_at` string, date-time, nullable, required
    - `finished_at` string, date-time, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `started_at_label` string, nullable, required
    - `finished_at_label` string, nullable, required
    - `created_at_label` string, nullable, required
    - `updated_at_label` string, nullable, required
  - `target_release` DeploymentRollbackRelease, required
    - `id` string, required
    - `slug` string, required
    - `version` string, required
    - `release_kind` 'deployment' | 'rollback' | 'hotfix', required
    - `status` 'draft' | 'ready' | 'deploying' | 'active' | 'failed' | 'rolled_back', required
    - `source_ref` string, nullable, required
    - `commit_sha` string, nullable, required
    - `app_deployment_id` string, nullable, required
    - `rollback_target_release_id` string, nullable, required
    - `created_at` string, date-time, required
  - `target_artifact_locator` string, nullable, required
  - `candidate_releases` DeploymentRollbackRelease[], required
    - `id` string, required
    - `slug` string, required
    - `version` string, required
    - `release_kind` 'deployment' | 'rollback' | 'hotfix', required
    - `status` 'draft' | 'ready' | 'deploying' | 'active' | 'failed' | 'rolled_back', required
    - `source_ref` string, nullable, required
    - `commit_sha` string, nullable, required
    - `app_deployment_id` string, nullable, required
    - `rollback_target_release_id` string, nullable, required
    - `created_at` string, date-time, required
  - `reason` string, nullable, required
  - `force` boolean, required
  - `blockers` string[], required
  - `warnings` string[], required
  - `execution_allowed` boolean, required
  - `confirmation_text` string, required
  - `idempotent_reuse` boolean, required
  - `operation` DeploymentOperation, required
    - `rollout_predecessor_id` string, nullable, required
    - `id` string, required
    - `number` integer, required
    - `status` 'queued' | 'building' | 'deploying' | 'active' | 'failed' | 'rolled_back' | 'canceled', required
    - `app` object, required
      - `id` string, required
      - `slug` string, required
      - `name` string, required
    - `service` object, required
      - `id` string, required
      - `slug` string, required
      - `name` string, required
    - `environment` object, required
      - `id` string, required
      - `slug` string, required
      - `name` string, required
      - `kind` string, required
    - `placement` object, nullable, required
      - `id` string, required
      - `mode` 'single_region' | 'multi_region', required
      - `rollout_strategy` 'health_gated' | 'burst', required
      - `replicas_per_region` integer, required
      - `total_replicas` integer, required
    - `rollout_strategy` 'health_gated' | 'burst', required
    - `replicas_per_region` integer, required
    - `total_replicas` integer, required
    - `trigger_kind` 'manual' | 'push' | 'schedule' | 'api' | 'rollback', required
    - `is_rollback` boolean, required
    - `rollback_source_release_id` string, nullable, required
    - `rollback_target_release_id` string, nullable, required
    - `rollback_reason` string, nullable, required
    - `source_ref` string, nullable, required
    - `commit_sha` string, nullable, required
    - `artifact_locator` string, nullable, required
    - `deployed_url` string, uri, nullable, required
    - `build_duration_seconds` integer, nullable, required
    - `duration_seconds` integer, nullable, required
    - `creator` object, nullable, required
      - `id` string, required
      - `name` string, nullable, required
      - `picture_url` string, nullable, required
    - `build_status` 'queued' | 'building' | 'succeeded' | 'failed' | 'canceled' | 'skipped', required
    - `rollout_status` 'not_started' | 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled' | 'mixed', required
    - `history_kind` 'current' | 'superseded' | 'stale' | 'historical', required
    - `history_reason` string, nullable, required
    - `ci_pipeline_id` string, nullable, required
    - `ci_pipeline_run_id` string, nullable, required
    - `build_source` object, nullable, required
      - `phase` 'waiting' | 'reused', required
      - `deployment_id` string, required
      - `canonical_deployment_id` string, required
      - `number` integer, required
    - `region_count` integer, required
    - `live_region_count` integer, required
    - `is_live` boolean, required
    - `children` DeploymentOperationChild[], required
      - `deployment_id` string, required
      - `target_id` string, nullable, required
      - `number` integer, required
      - `environment` object, required
        - `id` string, required
        - `slug` string, required
        - `name` string, required
        - `kind` string, required
      - `location` object, nullable, required
        - `id` string, required
        - `code` string, required
        - `name` string, required
      - `build_role` 'leader' | 'follower' | 'standalone', required
      - `build_status` 'queued' | 'building' | 'succeeded' | 'failed' | 'canceled' | 'skipped', required
      - `rollout_status` 'not_started' | 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required
      - `history_kind` 'current' | 'superseded' | 'stale' | 'historical', required
      - `history_reason` string, nullable, required
      - `recorded_status` 'queued' | 'building' | 'deploying' | 'active' | 'failed' | 'rolled_back' | 'canceled', required
      - `desired_replicas` integer, required
      - `live_replicas` integer, required
      - `is_live` boolean, required
      - `release_id` string, nullable, required
      - `rollout_id` string, nullable, required
      - `failure_message` string, nullable, required
      - `superseded_by_deployment_id` string, nullable, required
      - `ci_pipeline_id` string, nullable, required
      - `ci_pipeline_run_id` string, nullable, required
      - `started_at` string, date-time, nullable, required
      - `finished_at` string, date-time, nullable, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `deployment` AppDeployment, required
    - `id` string, required
    - `hosted_app_id` string, required
    - `organization_id` string, required
    - `app_service_id` string, required
    - `app_environment_id` string, required
    - `location_id` string, required
    - `creator_user_id` string, nullable, required
    - `number` integer, required
    - `display_id` integer, required
    - `status` 'queued' | 'building' | 'deploying' | 'active' | 'failed' | 'rolled_back' | 'canceled', required
    - `location` HostingLocation, required
      - `id` string, required
      - `code` string, required
      - `name` string, required
      - `nomad_datacenter` string, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
    - `source_ref` string, nullable, required
    - `commit_sha` string, nullable, required
    - `artifact_locator` string, nullable, required
    - `deployed_url` string, nullable, required
    - `trigger_kind` 'manual' | 'push' | 'schedule' | 'api' | 'rollback', required
    - `operation_key` string, nullable, required
    - `build_role` 'leader' | 'follower' | 'standalone', nullable, required
    - `is_rollback` boolean, required
    - `rollback_source_release_id` string, nullable, required
    - `rollback_target_release_id` string, nullable, required
    - `rollback_source_deployment_id` string, nullable, required
    - `rollback_reason` string, nullable, required
    - `idempotency_key` string, nullable, required
    - `failure_message` string, nullable, required
    - `started_at` string, date-time, nullable, required
    - `finished_at` string, date-time, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `started_at_label` string, nullable, required
    - `finished_at_label` string, nullable, required
    - `created_at_label` string, nullable, required
    - `updated_at_label` string, nullable, required
  - `rollback_release` DeploymentRollbackRelease, required
    - `id` string, required
    - `slug` string, required
    - `version` string, required
    - `release_kind` 'deployment' | 'rollback' | 'hotfix', required
    - `status` 'draft' | 'ready' | 'deploying' | 'active' | 'failed' | 'rolled_back', required
    - `source_ref` string, nullable, required
    - `commit_sha` string, nullable, required
    - `app_deployment_id` string, nullable, required
    - `rollback_target_release_id` string, nullable, required
    - `created_at` string, date-time, required
  - `desired_state` AppDesiredState, required
    - `id` string, required
    - `organization_id` string, required
    - `hosted_app_id` string, required
    - `app_environment_id` string, required
    - `app_service_id` string, required
    - `network_segment_id` string, nullable, required
    - `slug` string, required
    - `status` 'active' | 'paused' | 'archived', required
    - `desired_instances` integer, required
    - `desired_version` string, nullable, required
    - `image_locator` string, nullable, required
    - `command` string, nullable, required
    - `env_fingerprint` string, nullable, required
    - `config_fingerprint` string, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `created_at_label` string, nullable, required
    - `updated_at_label` string, nullable, required
  - `rollout` AppRollout, required
    - `id` string, required
    - `organization_id` string, required
    - `app_release_id` string, required
    - `strategy` string, required
    - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required
    - `deployment_phase` 'queued' | 'deploying' | 'active' | 'failed' | 'unknown', required
    - `auto_safe_rollout` boolean, required
    - `nomad_deployment_id` string, nullable, required
    - `nomad_eval_id` string, nullable, required
    - `target_percentage` integer, required
    - `summary` string, nullable, required
    - `started_at` string, date-time, nullable, required
    - `finished_at` string, date-time, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `started_at_label` string, nullable, required
    - `finished_at_label` string, nullable, required
    - `created_at_label` string, nullable, required
    - `updated_at_label` string, nullable, required

## Other responses

- `201`: Deployment rollback created
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Idempotency key already names a different deployment
- `422`: Deployment request failed validation
- `502`: Bad gateway

---

[API](https://skmtc.dev/composal/apis/vex-api.md) - [All operations](https://skmtc.dev/composal/apis/vex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/composal/apis/vex-api/revisions/74298a24e040?raw)