---
title: "Assign an Alias"
method: POST
path: "/v2/deployments/{id}/aliases"
tags: ["aliases"]
---

# Assign an Alias

`POST /v2/deployments/{id}/aliases`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/v2/deployments/{id}/aliases`
- Auth: HTTP bearer

Creates a new alias for the deployment resolved from the given deployment or alias ID or URL. The authenticated user or team must own this deployment. If the desired alias is already assigned to another deployment, then it will be removed from the old deployment and assigned to the new one.

## Path parameters

- `id` string, required: The deployment or alias ID or URL to assign from

## Query parameters

- `teamId` string
- `slug` string

## Request body

- object
  - `alias` string: The alias we want to assign to the deployment defined in the URL
  - `redirect` string, nullable: The redirect property will take precedence over the deployment id from the URL and consists of a hostname (like test.com) to which the alias should redirect using status code 307

## Response `200`

The alias was successfully assigned to the deployment

- object
  - `alias` string, required: The assigned alias name
  - `created` string, date-time, required: The date when the alias was created
  - `oldDeploymentId` string, nullable: The unique identifier of the previously aliased deployment, only received when the alias was used before
  - `uid` string, required: The unique identifier of the alias

## Other responses

- `400`: One of the provided values in the request body is invalid. One of the provided values in the request query is invalid. The cert for the provided alias is not ready The deployment is not READY and can not be aliased The supplied alias is invalid
- `401`: The request is not authorized.
- `402`: The account is missing a payment so payment method must be updated
- `403`: You do not have permission to access this resource. If no .vercel.app alias exists then we fail (nothing to mirror)
- `404`: The domain used for the alias was not found The deployment was not found
- `409`: The provided alias is already assigned to the given deployment The domain is not allowed to be used
- `410`

## Changes

- **2026-07-21** `2ae10ee9d21c`: 1 info
  - added the non-success response with the status `410`
- **2026-01-22** `c12186034433`: 1 breaking
  - request body became required
- **2025-03-19** `37b482c58c92`: 2 info
  - added the new optional `query` request parameter `slug`
  - added the non-success response with the status `401`

[Operation history](https://skmtc.dev/vercel/apis/vercel-api/changes/v2/deployments/:id/aliases/post.md)

---

[API](https://skmtc.dev/vercel/apis/vercel-api.md) - [All operations](https://skmtc.dev/vercel/apis/vercel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/vercel-api/revisions/60686c0e1f6a?raw)