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

# Create deployment

`POST /v3/deployments.createDeployment`

Create a deployment for an app in a project.

Omit the source to use the app's configured default. A Git app builds its default branch. An OCI app deploys its default image.

Optionally provide one source override:
- `oci`: deploy a prebuilt OCI image without a build. Mutable tags are resolved to immutable digests before rollout.
- `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 deployments rebuild from the recorded commit; OCI deployments reuse the recorded resolved 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

- V3DeploymentsCreateDeploymentRequestBody — Create a deployment. Omit the source to use the app default, or provide one source override.
  - `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.
  - `oci` DeploymentSourceOCI — Deploy a prebuilt OCI image without a build.
    - `image` string, required — OCI image to deploy. Mutable tags are resolved to immutable digests before rollout.
  - `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.

## Response `201`

Deployment created successfully

- V3DeploymentsCreateDeploymentResponseBody
  - `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` V3DeploymentsCreateDeploymentResponseData, required
    - `deploymentId` string, required — Unique deployment identifier

## Other responses

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

## Changes

- **2026-09-04** `31ef4eedd220` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v3/deployments.createDeployment/post.md)

---

[API](https://skmtc.dev/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.dev/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc.dev/unkeyed/apis/unkey-api/revisions/f357a2090000?raw)