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

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

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

## 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}/deploys`
- Auth: HTTP bearer

Deploy a pre-built image. environment accepts a slug or public ID, all (the default), or existing. existing selects this service's placements in active environments with positive replica counts and enabled regions; it preserves their replica counts unless desired_instances overrides them and never creates a placement or restarts a drained placement. No eligible placements returns 422. Existing Git writer placements roll out sequentially in the background. rollout_predecessor queues a deployment until the named operation has completed successfully; failure or cancellation stops its followers.

## Path parameters

- `app_id` string, required

## Request body

- object
  - `image` string, required
  - `service` string: Service slug or public ID; required unless app_service_id is supplied.
  - `app_service_id` string
  - `environment` string: Environment slug or public ID, all, or existing.
  - `app_environment_id` string
  - `region` string
  - `desired_instances` integer
  - `command` string
  - `channel` string
  - `source_ref` string
  - `commit_sha` string
  - `rollout_predecessor` string: Public deployment operation ID from the same app that must succeed before this rollout starts.

## Response `200`

Success

- object

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `422`: Invalid image, no eligible placements, or placement changed before deployment.
- `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)