aliases

Reference

3 min read

Aliases

Assign an Alias

post/v2/deployments/{id}/aliases

Creates a new alias for the deployment with the given deployment ID. 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.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v2/deployments/dpl_FjvFJncQHQcZMznrUm9EoB8sFuPa/aliases?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "body": {
3    "alias": "my-alias.vercel.app",
4    "redirect": "SOME_STRING_VALUE"
5  },
6  "headers": {
7    "Authorization": "Bearer <TOKEN>"
8  },
9  "method": "post"
10})

Parameters

Path Params

Query Params

Body Params

Path Parameter	Description
id	string of the following required The ID of the deployment the aliases should be listed for Example:`dpl_FjvFJncQHQcZMznrUm9EoB8sFuPa` type: `string`

Response

aliasstringRequired
The assigned alias name
Example: my-alias.vercel.app

createdstring (date-time)Required
The date when the alias was created
Example: 2017-04-26T23:00:34.232Z

oldDeploymentIdstring or null
The unique identifier of the previously aliased deployment, only received when the alias was used before
Example: dpl_FjvFJncQHQcZMznrUm9EoB8sFuPa

uidstringRequired
The unique identifier of the alias
Example: 2WjyKQmM8ZnGcJsPWMrHRHrE

Response Codes

Code	Description
`200`	The alias was successfully assigned to the deployment
`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`
`402`	The account was soft-blocked for an unhandled reason. 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

Optional params

fetch-request

1await fetch("https://api.vercel.com/v2/deployments/dpl_FjvFJncQHQcZMznrUm9EoB8sFuPa/aliases?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "body": {
3    "alias": "my-alias.vercel.app",
4    "redirect": "SOME_STRING_VALUE"
5  },
6  "headers": {
7    "Authorization": "Bearer <TOKEN>"
8  },
9  "method": "post"
10})

Delete an Alias

delete/v2/aliases/{aliasId}

Delete an Alias with the specified ID.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v2/aliases/2WjyKQmM8ZnGcJsPWMrHRHrE?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "delete"
6})

Parameters

Path Params

Query Params

Path Parameter	Description
aliasId	string of the following required The ID or alias that will be removed Example:`2WjyKQmM8ZnGcJsPWMrHRHrE` type: `string`

Response

statusstringRequired
One of: SUCCESS

Response Codes

Code	Description
`200`	The alias was successfully removed
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`	The alias was not found

Optional params

fetch-request

1await fetch("https://api.vercel.com/v2/aliases/2WjyKQmM8ZnGcJsPWMrHRHrE?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "delete"
6})

Get an Alias

get/v4/aliases/{idOrAlias}

Retrieves an Alias for the given host name or alias ID.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v4/aliases/example.vercel.app?from=1540095775951&projectId=prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB&since=1540095775941&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE&until=1540095775951", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Path Params

Query Params

Path Parameter	Description
idOrAlias	string required The alias or alias ID to be retrieved Example:`example.vercel.app`

Response

aliasstringRequired
The alias name, it could be a .vercel.app subdomain or a custom domain
Example: my-alias.vercel.app

createdstring (date-time)Required
The date when the alias was created
Example: 2017-04-26T23:00:34.232Z

createdAtnumber
The date when the alias was created in milliseconds since the UNIX epoch
Example: 1540095775941

creatorobject
Information of the user who created the alias

Properties
deletedAtnumber
The date when the alias was deleted in milliseconds since the UNIX epoch
Example: 1540095775941

deploymentobject
A map with the deployment ID, URL and metadata

Properties
deploymentIdstring or nullRequired
The deployment ID
Example: dpl_5m8CQaRBm3FnWRW1od3wKTpaECPx

projectIdstring or nullRequired
The unique identifier of the project
Example: prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB

protectionBypassobject
The protection bypass for the alias

One of
redirectstring or null
Target destination domain for redirect when the alias is a redirect

redirectStatusCodenumber or null
One of: 301 | 302 | 307 | 308
Status code to be used on redirect

uidstringRequired
The unique identifier of the alias

updatedAtnumber
The date when the alias was updated in milliseconds since the UNIX epoch
Example: 1540095775941

Response Codes

Code	Description
`200`	The alias information
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`	The alias was not found

Optional params

fetch-request

1await fetch("https://api.vercel.com/v4/aliases/example.vercel.app?from=1540095775951&projectId=prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB&since=1540095775941&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE&until=1540095775951", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

List aliases

get/v4/aliases

Retrieves a list of aliases for the authenticated User or Team. When domain is provided, only aliases for that domain will be returned. When projectId is provided, it will only return the given project aliases.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v4/aliases?domain=my-test-domain.com&from=1540095775951&limit=10&projectId=prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB&rollbackDeploymentId=dpl_XXX&since=1540095775941&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE&until=1540095775951", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Query Params

Query Parameter	Description
domain	array <= 20 items \| string of the following Get only aliases of the given domain name `<= 20 items` Example:`my-test-domain.com` type: `array` type: `string`
from	number deprecated Get only aliases created after the provided timestamp Example:`1540095775951`
limit	number Maximum number of aliases to list from a request Example:`10`
projectId	string Filter aliases from the given `projectId` Example:`prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB`
rollbackDeploymentId	string Get aliases that would be rolled back for the given deployment Example:`dpl_XXX`
since	number Get aliases created after this JavaScript timestamp Example:`1540095775941`
slug	string The Team slug to perform the request on behalf of.
teamId	string The Team identifier to perform the request on behalf of.
until	number Get aliases created before this JavaScript timestamp Example:`1540095775951`

Response

aliasesarrayRequired
Properties
paginationRequired

Response Codes

Code	Description
`200`	The paginated list of aliases
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`

Optional params

fetch-request

1await fetch("https://api.vercel.com/v4/aliases?domain=my-test-domain.com&from=1540095775951&limit=10&projectId=prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB&rollbackDeploymentId=dpl_XXX&since=1540095775941&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE&until=1540095775951", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

List Deployment Aliases

get/v2/deployments/{id}/aliases

Retrieves all Aliases for the Deployment with the given ID. The authenticated user or team must own the deployment.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v2/deployments/dpl_FjvFJncQHQcZMznrUm9EoB8sFuPa/aliases?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Path Params

Query Params

Path Parameter	Description
id	string required The ID of the deployment the aliases should be listed for Example:`dpl_FjvFJncQHQcZMznrUm9EoB8sFuPa`

Response

aliasesarrayRequired
A list of the aliases assigned to the deployment
Properties

Response Codes

Code	Description
`200`	The list of aliases assigned to the deployment
`400`	One of the provided values in the request query is invalid.
`401`
`403`	You do not have permission to access this resource.
`404`	The deployment was not found

Optional params

fetch-request

1await fetch("https://api.vercel.com/v2/deployments/dpl_FjvFJncQHQcZMznrUm9EoB8sFuPa/aliases?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Last updated on April 27, 2024

Endpoints

Assign an Alias

Was this helpful?