Skip to content
Docs

Create a custom environment for the current project.

POSThttps://api.vercel.com/v9/projects/{idOrName}/custom-environments
Creates a custom environment for the current project. Cannot be named 'Production' or 'Preview'.
https://api.vercel.com/v9/projects/{idOrName}/custom-environments
const response = await fetch('https://api.vercel.com/v9/projects/idOrName/custom-environments?teamId=string&slug=string', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "slug": "string",
    "description": "string",
    "branchMatcher": {
      "type": "equals",
      "pattern": "string"
    },
    "copyEnvVarsFrom": "string"
  }),
});


const data = await response.json();
console.log(data);
Response
{
  "branchMatcher": {
    "pattern": "string",
    "type": "endsWith"
  },
  "createdAt": "123",
  "currentDeploymentAliases": [],
  "description": "string",
  "domains": [
    {
      "apexName": "Example Name",
      "createdAt": "123",
      "customEnvironmentId": "example_id",
      "gitBranch": "string",
      "name": "Example Name",
      "projectId": "example_id",
      "redirect": "string",
      "redirectStatusCode": "301",
      "updatedAt": "123",
      "verification": [
        {
          "domain": "string",
          "reason": "Customer requested refund",
          "type": "string",
          "value": "string"
        }
      ],
      "verified": "false"
    }
  ],
  "id": "icfg_1234567890",
  "slug": "string",
  "type": "development",
  "updatedAt": "123"
}

Authentication

AuthorizationbearerToken

Default authentication mechanism

Path parameters

idOrNamestringRequired
The unique project identifier or the project name

Query parameters

teamIdstringOptional
The Team identifier to perform the request on behalf of.
slugstringOptional
The Team slug to perform the request on behalf of.

Body

application/json
slugstringOptional
The slug of the custom environment to create.
descriptionstringOptional
Description of the custom environment. This is optional.
branchMatcherobjectOptional
How we want to determine a matching branch. This is optional.
copyEnvVarsFromstringOptional
Where to copy environment variables from. This is optional.

Response

201Success
branchMatcherobjectOptional
Configuration for matching git branches to this environment
createdAtnumberRequired
Timestamp when the environment was created
currentDeploymentAliasesarrayOptional
List of aliases for the current deployment
descriptionstringOptional
Optional description of the environment's purpose
domainsarrayOptional
List of domains associated with this environment
idstringRequired
Unique identifier for the custom environment (format: env_*)
slugstringRequired
URL-friendly name of the environment
typestringRequired
The type of environment (production, preview, or development)
updatedAtnumberRequired
Timestamp when the environment was last updated

Errors

400One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
401The request is not authorized.
402The account is missing a payment so payment method must be updated
403You do not have permission to access this resource.
404Error
409Error
410Error
500Error