domains

Creates, updates, deletes, gets or lists a domains resource.

Overview

Name	domains
Type	Resource
Id	vercel.projects.domains

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
name	string
custom_environment_id	string	(wire: customEnvironmentId)
project_id	string	(wire: projectId)
apex_name	string	(wire: apexName)
created_at	number	(wire: createdAt)
git_branch	string	(wire: gitBranch)
redirect	string
redirect_status_code	number	(301, 302, 307, 308, ) (wire: redirectStatusCode)
updated_at	number	(wire: updatedAt)
verification	array	A list of verification challenges, one of which must be completed to verify the domain for use on the project. After the challenge is complete POST /projects/:idOrName/domains/:domain/verify to verify the domain. Possible challenges: - If verification.type = TXT the verification.domain will be checked for a TXT record matching verification.value.
verified	boolean	true if the domain is verified for use with the project. If false it will not be used as an alias on this project until the challenge in verification is completed. (false, true)

list

Successful response retrieving a list of domains

Name	Datatype	Description
name	string
custom_environment_id	string	(wire: customEnvironmentId)
project_id	string	(wire: projectId)
apex_name	string	(wire: apexName)
created_at	number	(wire: createdAt)
git_branch	string	(wire: gitBranch)
redirect	string
redirect_status_code	number	(301, 302, 307, 308, ) (wire: redirectStatusCode)
updated_at	number	(wire: updatedAt)
verification	array	A list of verification challenges, one of which must be completed to verify the domain for use on the project. After the challenge is complete POST /projects/:idOrName/domains/:domain/verify to verify the domain. Possible challenges: - If verification.type = TXT the verification.domain will be checked for a TXT record matching verification.value.
verified	boolean	true if the domain is verified for use with the project. If false it will not be used as an alias on this project until the challenge in verification is completed. (false, true)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	id_or_name, domain	team_id, slug	Get project domain by project id/name and domain name.
list	select	id_or_name	production, target, custom_environment_id, git_branch, redirects, redirect, verified, limit, since, until, order, team_id, slug	Retrieve the domains associated with a given project by passing either the project id or name in the URL.
add	insert	id_or_name, name	team_id, slug	Add a domain to the project by passing its domain name and by specifying the project by either passing the project id or name in the URL. If the domain is not yet verified to be used on this project, the request will return verified = false, and the domain will need to be verified according to the verification challenge via POST /projects/:idOrName/domains/:domain/verify. If the domain already exists on the project, the request will fail with a 400 status code.
update	update	id_or_name, domain	team_id, slug	Update a project domain's configuration, including the name, git branch and redirect of the domain.
delete	delete	id_or_name, domain	team_id, slug	Remove a domain from a project by passing the domain name and by specifying the project by either passing the project id or name in the URL.
move	exec	id_or_name, domain, projectId	teamId, slug	Move one project's domain to another project. Also allows the move of all redirects pointed to that domain in the same project.
verify	exec	id_or_name, domain	teamId, slug	Attempts to verify a project domain with verified = false by checking the correctness of the project domain's verification challenge.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
domain	string	The domain name you want to verify
id_or_name	string	The unique project identifier or the project name
custom_environment_id	string	The unique custom environment identifier within the project (wire: customEnvironmentId)
git_branch	string	Filters domains based on specific branch. (wire: gitBranch)
limit	number	Maximum number of domains to list from a request (max 100).
order		Domains sort order by createdAt
production		Filters only production domains when set to true.
redirect	string	Filters domains based on their redirect target.
redirects		Excludes redirect project domains when "false". Includes redirect project domains when "true" (default).
since	number	Get domains created after this JavaScript timestamp.
slug	string	The Team slug to perform the request on behalf of.
target	string	Filters on the target of the domain. Can be either "production", "preview"
teamId	string	The Team identifier to perform the request on behalf of.
team_id	string	The Team identifier to perform the request on behalf of. (wire: teamId)
until	number	Get domains created before this JavaScript timestamp.
verified		Filters domains based on their verification status.

SELECT examples

get

Get project domain by project id/name and domain name.

SELECT
name,
custom_environment_id,
project_id,
apex_name,
created_at,
git_branch,
redirect,
redirect_status_code,
updated_at,
verification,
verified
FROM vercel.projects.domains
WHERE id_or_name = '{{ id_or_name }}' -- required
AND domain = '{{ domain }}' -- required
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

list

Retrieve the domains associated with a given project by passing either the project id or name in the URL.

SELECT
name,
custom_environment_id,
project_id,
apex_name,
created_at,
git_branch,
redirect,
redirect_status_code,
updated_at,
verification,
verified
FROM vercel.projects.domains
WHERE id_or_name = '{{ id_or_name }}' -- required
AND production = '{{ production }}'
AND target = '{{ target }}'
AND custom_environment_id = '{{ custom_environment_id }}'
AND git_branch = '{{ git_branch }}'
AND redirects = '{{ redirects }}'
AND redirect = '{{ redirect }}'
AND verified = '{{ verified }}'
AND limit = '{{ limit }}'
AND since = '{{ since }}'
AND until = '{{ until }}'
AND order = '{{ order }}'
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

INSERT examples

add

Add a domain to the project by passing its domain name and by specifying the project by either passing the project id or name in the URL. If the domain is not yet verified to be used on this project, the request will return verified = false, and the domain will need to be verified according to the verification challenge via POST /projects/:idOrName/domains/:domain/verify. If the domain already exists on the project, the request will fail with a 400 status code.

INSERT INTO vercel.projects.domains (
name,
git_branch,
custom_environment_id,
redirect,
redirect_status_code,
id_or_name,
team_id,
slug
)
SELECT 
'{{ name }}' /* required */,
'{{ git_branch }}',
'{{ custom_environment_id }}',
'{{ redirect }}',
{{ redirect_status_code }},
'{{ id_or_name }}',
'{{ team_id }}',
'{{ slug }}'
RETURNING
name,
custom_environment_id,
project_id,
apex_name,
created_at,
git_branch,
redirect,
redirect_status_code,
updated_at,
verification,
verified
;

Manifest

# Description fields are for documentation purposes
- name: domains
props:
  - name: id_or_name
    value: "{{ id_or_name }}"
    description: Required parameter for the domains resource.
  - name: name
    value: "{{ name }}"
    description: |
      The project domain name
  - name: git_branch
    value: "{{ git_branch }}"
    description: |
      Git branch to link the project domain
  - name: custom_environment_id
    value: "{{ custom_environment_id }}"
    description: |
      The unique custom environment identifier within the project
  - name: redirect
    value: "{{ redirect }}"
    description: |
      Target destination domain for redirect
  - name: redirect_status_code
    value: {{ redirect_status_code }}
    description: |
      Status code for domain redirect
    valid_values: ['', '301', '302', '307', '308']
  - name: team_id
    value: "{{ team_id }}"
    description: The Team identifier to perform the request on behalf of.
    description: The Team identifier to perform the request on behalf of.
  - name: slug
    value: "{{ slug }}"
    description: The Team slug to perform the request on behalf of.
    description: The Team slug to perform the request on behalf of.

UPDATE examples

update

Update a project domain's configuration, including the name, git branch and redirect of the domain.

UPDATE vercel.projects.domains
SET 
git_branch = '{{ git_branch }}',
redirect = '{{ redirect }}',
redirect_status_code = {{ redirect_status_code }}
WHERE 
id_or_name = '{{ id_or_name }}' --required
AND domain = '{{ domain }}' --required
AND team_id = '{{ team_id}}'
AND slug = '{{ slug}}'
RETURNING
name,
custom_environment_id,
project_id,
apex_name,
created_at,
git_branch,
redirect,
redirect_status_code,
updated_at,
verification,
verified;

DELETE examples

delete

Remove a domain from a project by passing the domain name and by specifying the project by either passing the project id or name in the URL.

DELETE FROM vercel.projects.domains
WHERE id_or_name = '{{ id_or_name }}' --required
AND domain = '{{ domain }}' --required
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

Lifecycle Methods

EXEC variables use wire (API) names.

move

Move one project's domain to another project. Also allows the move of all redirects pointed to that domain in the same project.

EXEC vercel.projects.domains.move 
@id_or_name='{{ id_or_name }}' --required, 
@domain='{{ domain }}' --required, 
@teamId='{{ teamId }}', 
@slug='{{ slug }}' 
@@json=
'{
"projectId": "{{ projectId }}", 
"gitBranch": "{{ gitBranch }}", 
"redirect": "{{ redirect }}", 
"redirectStatusCode": {{ redirectStatusCode }}
}'
;

verify

Attempts to verify a project domain with verified = false by checking the correctness of the project domain's verification challenge.

EXEC vercel.projects.domains.verify 
@id_or_name='{{ id_or_name }}' --required, 
@domain='{{ domain }}' --required, 
@teamId='{{ teamId }}', 
@slug='{{ slug }}'
;