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

# Create deployment

`POST /v2/deploy.createDeployment`

Creates a new deployment for a project using either a pre-built Docker image or build context.

**Authentication**: Requires a valid root key with appropriate permissions.

## Request body

- union — Deployment source - either build from source or use prebuilt image
  - object — Build from source configuration
    - `projectId` string, required — Unkey project ID
    - `keyspaceId` string — Optional keyspace ID for authentication context
    - `branch` string, required — Git branch name
    - `environmentSlug` string, required — Environment slug (e.g., "production", "staging")
    - `gitCommit` V2DeployGitCommit — Optional git commit information
      - `commitSha` string — Git commit SHA
      - `commitMessage` string — Git commit message
      - `authorHandle` string — Git author handle/username
      - `authorAvatarUrl` string — Git author avatar URL
      - `timestamp` integer — Commit timestamp in milliseconds
    - `build` object, required — Build context for building from source. Provide either `build.context` (build from source) or `image` (prebuilt image), but not both.
      - `context` string, required — S3 path to uploaded build context tarball
      - `dockerfile` string — Optional path to Dockerfile within build context (defaults to "Dockerfile")
  - object — Prebuilt Docker image configuration
    - `projectId` string, required — Unkey project ID
    - `keyspaceId` string — Optional keyspace ID for authentication context
    - `branch` string, required — Git branch name
    - `environmentSlug` string, required — Environment slug (e.g., "production", "staging")
    - `gitCommit` V2DeployGitCommit — Optional git commit information
      - `commitSha` string — Git commit SHA
      - `commitMessage` string — Git commit message
      - `authorHandle` string — Git author handle/username
      - `authorAvatarUrl` string — Git author avatar URL
      - `timestamp` integer — Commit timestamp in milliseconds
    - `image` string, required — Prebuilt Docker image reference

## Response `201`

Deployment created successfully

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

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Not found
- `500` — Internal server error

## Changes

- **2026-01-14** `bdbbfa847a6f` — 1 info
  - api operation id `createDeployment` removed and replaced with `deploy.createDeployment`
- **2026-01-13** `025abb556ac8` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/deploy.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-service-production.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/revisions/9a9c22b6dd09/schema)