assign an alias.md

title: assign-an-alias product: vercel url: /docs/rest-api/aliases/assign-an-alias canonical_url: "https://vercel.com/docs/rest-api/aliases/assign-an-alias" last_updated: 2026-09-26 type: reference prerequisites: [] summary: Learn about assign-an-alias on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin

Assign an Alias

POST /v2/deployments/{id}/aliases

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.

Authentication

bearerToken: HTTP bearer

Path parameters

Name	Type	Required	Description
`id`	object	Yes	The deployment or alias ID or URL to assign from

Query parameters

Name	Type	Required	Description
`teamId`	string	No	The Team identifier to perform the request on behalf of.
`slug`	string	No	The Team slug to perform the request on behalf of.

Request body

Required: Yes

Content-Type: application/json

{
  "type": "object",
  "properties": {
    "alias": {
      "type": "string",
      "description": "The alias we want to assign to the deployment defined in the URL"
    },
    "redirect": {
      "type": "string",
      "description": "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",
      "nullable": true
    }
  }
}

Example request

TypeScript

const response = await fetch('https://api.vercel.com/v2/deployments/id/aliases?teamId=string&slug=string', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "alias": "my-alias.vercel.app",
    "redirect": "null"
  }),
});

const data = await response.json();
console.log(data);

Next.js

'use server';

export async function callEndpoint() {
  const response = await fetch('https://api.vercel.com/v2/deployments/id/aliases?teamId=string&slug=string', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.VERCEL_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      "alias": "my-alias.vercel.app",
      "redirect": "null"
    }),
    next: { revalidate: 3600 }
  });

if (!response.ok) {
    throw new Error('Request failed');
  }

return response.json();
}

cURL

curl -X POST 'https://api.vercel.com/v2/deployments/id/aliases?teamId=string&slug=string' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d "{\n    \"alias\": \"my-alias.vercel.app\",\n    \"redirect\": \"null\"\n  }"

Example response

{
  "alias": "my-alias.vercel.app",
  "created": "2017-04-26T23:00:34.232Z",
  "oldDeploymentId": "dpl_FjvFJncQHQcZMznrUm9EoB8sFuPa",
  "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE"
}

Responses

200: The alias was successfully assigned to the deployment

Content-Type: application/json

{
  "type": "object",
  "required": [
    "alias",
    "created",
    "uid"
  ],
  "properties": {
    "alias": {
      "type": "string",
      "description": "The assigned alias name"
    },
    "created": {
      "type": "string",
      "description": "The date when the alias was created",
      "format": "date-time"
    },
    "oldDeploymentId": {
      "type": "string",
      "description": "The unique identifier of the previously aliased deployment, only received when the alias was used before",
      "nullable": true
    },
    "uid": {
      "type": "string",
      "description": "The unique identifier of the alias"
    }
  }
}

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