---
title: "Create a custom environment for the current project."
method: POST
path: "/v9/projects/{idOrName}/custom-environments"
tags: ["environment"]
---

# Create a custom environment for the current project.

`POST /v9/projects/{idOrName}/custom-environments`

Creates a custom environment for the current project. Cannot be named 'Production' or 'Preview'.

## Path parameters

- `idOrName` string, required — The unique project identifier or the project name

## Query parameters

- `teamId` string
- `slug` string

## Request body

- object
  - `slug` string — The slug of the custom environment to create.
  - `description` string — Description of the custom environment. This is optional.
  - `branchMatcher` object — How we want to determine a matching branch. This is optional.
    - `type` 'equals' | 'startsWith' | 'endsWith', required — Type of matcher. One of "equals", "startsWith", or "endsWith".
    - `pattern` string, required — Git branch name or portion thereof.
  - `copyEnvVarsFrom` string — Where to copy environment variables from. This is optional.

## Response `201`

- object — Internal representation of a custom environment with all required properties
  - `id` string, required — Unique identifier for the custom environment (format: env_*)
  - `slug` string, required — URL-friendly name of the environment
  - `type` 'development' | 'preview' | 'production', required — The type of environment (production, preview, or development)
  - `description` string — Optional description of the environment's purpose
  - `branchMatcher` object — Configuration for matching git branches to this environment
    - `type` 'endsWith' | 'equals' | 'startsWith', required — The type of matching to perform
    - `pattern` string, required — The pattern to match against branch names
  - `domains` object[] — List of domains associated with this environment
    - `name` string, required
    - `apexName` string, required
    - `projectId` string, required
    - `redirect` string, nullable
    - `redirectStatusCode` 301 | 302 | 307 | 308 | null, nullable
    - `gitBranch` string, nullable
    - `customEnvironmentId` string, nullable
    - `updatedAt` number
    - `createdAt` number
    - `verified` false | true, required — `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.
    - `verification` object[] — 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`.
      - `type` string, required
      - `domain` string, required
      - `value` string, required
      - `reason` string, required
  - `currentDeploymentAliases` string[] — List of aliases for the current deployment
  - `createdAt` number, required — Timestamp when the environment was created
  - `updatedAt` number, required — Timestamp when the environment was last updated

## 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.
- `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.
- `410`
- `500`

---

[API](https://skmtc.net/vercel/apis/api.md) · [All operations](https://skmtc.net/vercel/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vercel/api/versions/61d1ba3f6dac/schema)