---
title: "Create deployment"
method: POST
path: "/v2/deployments.createDeployment"
tags: ["deployments"]
---

# Create deployment

`POST /v2/deployments.createDeployment`

Create a deployment for an app in a project.

Provide exactly one source:
- `image`: deploy a prebuilt Docker image as-is (no build).
- `git`: build and deploy from the app's connected GitHub repository, a branch, a specific commit, or a fork commit. Requires the app to have a repository connected.
- `deployment`: re-run an existing deployment by its id. Git-connected apps rebuild from the recorded commit; other apps reuse the recorded image.

Returns immediately with a `deploymentId`. The build and rollout run asynchronously — poll `deployments.getDeployment` to watch status until it is ready.

**Authentication**: requires a root key with permission to create deployments.

## Request body

- union — Create a deployment. Provide exactly one of git, image, or deployment.
  - object
    - `project` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
    - `app` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
    - `environment` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
    - `git` DeploymentSourceGit — Build from the app's connected GitHub repository.
      - `branch` string — Branch to build (its HEAD). Omit branch and commitSha to use the app's default branch.
      - `commitSha` string — Commit to build (full or abbreviated SHA). Takes precedence over branch.
      - `repository` string — Build from a fork instead of the app's connected repository, as "owner/repo". Requires commitSha.
    - `image` DeploymentSourceImage, required — Deploy a prebuilt Docker image as-is.
      - `dockerImage` string, required — Docker image to deploy as-is.
    - `deployment` DeploymentSourceDeployment — Re-run an existing deployment.
      - `deploymentId` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - object
    - `project` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
    - `app` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
    - `environment` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
    - `git` DeploymentSourceGit, required — Build from the app's connected GitHub repository.
      - `branch` string — Branch to build (its HEAD). Omit branch and commitSha to use the app's default branch.
      - `commitSha` string — Commit to build (full or abbreviated SHA). Takes precedence over branch.
      - `repository` string — Build from a fork instead of the app's connected repository, as "owner/repo". Requires commitSha.
    - `image` DeploymentSourceImage — Deploy a prebuilt Docker image as-is.
      - `dockerImage` string, required — Docker image to deploy as-is.
    - `deployment` DeploymentSourceDeployment — Re-run an existing deployment.
      - `deploymentId` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - object
    - `project` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
    - `app` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
    - `environment` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
    - `git` DeploymentSourceGit — Build from the app's connected GitHub repository.
      - `branch` string — Branch to build (its HEAD). Omit branch and commitSha to use the app's default branch.
      - `commitSha` string — Commit to build (full or abbreviated SHA). Takes precedence over branch.
      - `repository` string — Build from a fork instead of the app's connected repository, as "owner/repo". Requires commitSha.
    - `image` DeploymentSourceImage — Deploy a prebuilt Docker image as-is.
      - `dockerImage` string, required — Docker image to deploy as-is.
    - `deployment` DeploymentSourceDeployment, required — Re-run an existing deployment.
      - `deploymentId` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

## Response `201`

Deployment created successfully

- V2DeploymentsCreateDeploymentResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` V2DeploymentsCreateDeploymentResponseData, required
    - `deploymentId` string, required — Unique deployment identifier. Poll deployments.getDeployment with this id to watch status.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `412` — Precondition failed
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/versions/fa78aafac89c/schema)