---
title: create-one-or-more-environment-variables
product: vercel
url: /docs/rest-api/projects/create-one-or-more-environment-variables
type: reference
prerequisites:
  []
related:
  - /docs/rest-api
summary: Learn about create-one-or-more-environment-variables on Vercel.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# Create one or more environment variables

```http
POST /v10/projects/{idOrName}/env
```

Create one or more environment variables for a project by passing its `key`, `value`, `type` and `target` and by specifying the project by either passing the project `id` or `name` in the URL. If you include `upsert=true` as a query parameter, a new environment variable will not be created if it already exists but, the existing variable's value will be updated.

## Authentication

**bearerToken**: HTTP bearer

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `idOrName` | string | Yes | The unique project identifier or the project name |


## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `upsert` | string | No | Allow override of environment variable if it already exists |
| `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`

```json
{
  "oneOf": [
    {
      "type": "object",
      "required": [
        "key",
        "value",
        "type"
      ],
      "properties": {
        "key": {
          "type": "string",
          "description": "The name of the environment variable"
        },
        "value": {
          "type": "string",
          "description": "The value of the environment variable"
        },
        "type": {
          "type": "string",
          "description": "The type of environment variable",
          "enum": [
            "system",
            "encrypted",
            "plain",
            "sensitive"
          ]
        },
        "target": {
          "type": "array",
          "description": "The target environment of the environment variable",
          "items": {
            "enum": [
              "production",
              "preview",
              "development"
            ]
          }
        },
        "gitBranch": {
          "type": "string",
          "description": "If defined, the git branch of the environment variable (must have target=preview)",
          "maxLength": 250,
          "nullable": true
        },
        "comment": {
          "type": "string",
          "description": "A comment to add context on what this environment variable is for",
          "maxLength": 500
        },
        "customEnvironmentIds": {
          "type": "array",
          "description": "The custom environment IDs associated with the environment variable",
          "items": {
            "type": "string"
          }
        }
      },
      "anyOf": [
        {
          "required": [
            "target"
          ]
        },
        {
          "required": [
            "customEnvironmentIds"
          ]
        }
      ]
    },
    {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "key",
          "value",
          "type"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "The name of the environment variable"
          },
          "value": {
            "type": "string",
            "description": "The value of the environment variable"
          },
          "type": {
            "type": "string",
            "description": "The type of environment variable",
            "enum": [
              "system",
              "encrypted",
              "plain",
              "sensitive"
            ]
          },
          "target": {
            "type": "array",
            "description": "The target environment of the environment variable",
            "items": {
              "enum": [
                "production",
                "preview",
                "development"
              ]
            }
          },
          "gitBranch": {
            "type": "string",
            "description": "If defined, the git branch of the environment variable (must have target=preview)",
            "maxLength": 250,
            "nullable": true
          },
          "comment": {
            "type": "string",
            "description": "A comment to add context on what this environment variable is for",
            "maxLength": 500
          },
          "customEnvironmentIds": {
            "type": "array",
            "description": "The custom environment IDs associated with the environment variable",
            "items": {
              "type": "string"
            }
          }
        },
        "anyOf": [
          {
            "required": [
              "target"
            ]
          },
          {
            "required": [
              "customEnvironmentIds"
            ]
          }
        ]
      }
    }
  ]
}
```

## Responses

### 201: The environment variable was created successfully

Content-Type: `application/json`

```json
{
  "type": "object",
  "required": [
    "created",
    "failed"
  ],
  "properties": {
    "created": {
      "oneOf": [
        {
          "type": "object",
          "required": [
            "key",
            "type",
            "value"
          ],
          "properties": {
            "target": {
              "oneOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "production",
                      "preview",
                      "development"
                    ]
                  }
                },
                {
                  "type": "string",
                  "enum": [
                    "production",
                    "preview",
                    "development"
                  ]
                }
              ]
            },
            "type": {
              "type": "string",
              "enum": [
                "secret",
                "system",
                "encrypted",
                "plain",
                "sensitive"
              ]
            },
            "sunsetSecretId": {
              "type": "string",
              "description": "This is used to identify variables that have been migrated from type secret to sensitive."
            },
            "legacyValue": {
              "type": "string",
              "description": "Legacy now-encryption ciphertext, present after migration swaps value/vsmValue"
            },
            "decrypted": {
              "type": "boolean",
              "enum": [
                false,
                true
              ]
            },
            "value": {
              "type": "string"
            },
            "vsmValue": {
              "type": "string"
            },
            "id": {
              "type": "string"
            },
            "key": {
              "type": "string"
            },
            "configurationId": {
              "type": "string",
              "nullable": true
            },
            "createdAt": {
              "type": "number"
            },
            "updatedAt": {
              "type": "number"
            },
            "createdBy": {
              "type": "string",
              "nullable": true
            },
            "updatedBy": {
              "type": "string",
              "nullable": true
            },
            "gitBranch": {
              "type": "string"
            },
            "edgeConfigId": {
              "type": "string",
              "nullable": true
            },
            "edgeConfigTokenId": {
              "type": "string",
              "nullable": true
            },
            "contentHint": {
              "nullable": true,
              "oneOf": [
                {
                  "type": "object",
                  "required": [
                    "storeId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "redis-url"
                      ]
                    },
                    "storeId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "storeId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "redis-rest-api-url"
                      ]
                    },
                    "storeId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "storeId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "redis-rest-api-token"
                      ]
                    },
                    "storeId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "storeId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "redis-rest-api-read-only-token"
                      ]
                    },
                    "storeId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "storeId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "blob-read-write-token"
                      ]
                    },
                    "storeId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "storeId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "postgres-url"
                      ]
                    },
                    "storeId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "storeId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "postgres-url-non-pooling"
                      ]
                    },
                    "storeId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "storeId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "postgres-prisma-url"
                      ]
                    },
                    "storeId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "storeId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "postgres-user"
                      ]
                    },
                    "storeId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "storeId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "postgres-host"
                      ]
                    },
                    "storeId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "storeId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "postgres-password"
                      ]
                    },
                    "storeId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "storeId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "postgres-database"
                      ]
                    },
                    "storeId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "storeId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "postgres-url-no-ssl"
                      ]
                    },
                    "storeId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "integrationConfigurationId",
                    "integrationId",
                    "integrationProductId",
                    "storeId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "integration-store-secret"
                      ]
                    },
                    "storeId": {
                      "type": "string"
                    },
                    "integrationId": {
                      "type": "string"
                    },
                    "integrationProductId": {
                      "type": "string"
                    },
                    "integrationConfigurationId": {
                      "type": "string"
                    }
                  }
                },
                {
                  "type": "object",
                  "required": [
                    "projectId",
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "flags-connection-string"
                      ]
                    },
                    "projectId": {
                      "type": "string"
                    }
                  }
                }
              ]
            },
            "internalContentHint": {
              "type": "object",
              "description": "Similar to `contentHints`, but should not be exposed to the user.",
              "nullable": true,
              "required": [
                "encryptedValue",
                "type"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "flags-secret"
                  ]
                },
                "encryptedValue": {
                  "type": "string",
                  "description": "Contains the `value` of the env variable, encrypted with a special key to make decryption possible in the subscriber Lambda."
                }
              }
            },
            "comment": {
              "type": "string"
            },
            "customEnvironmentIds": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "system": {
              "type": "boolean",
              "enum": [
                false,
                true
              ]
            }
          }
        },
        {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "key",
              "type",
              "value"
            ],
            "properties": {
              "target": {
                "oneOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  {
                    "type": "string",
                    "enum": [
                      "production",
                      "preview",
                      "development"
                    ]
                  }
                ]
              },
              "type": {
                "type": "string",
                "enum": [
                  "secret",
                  "system",
                  "encrypted",
                  "plain",
                  "sensitive"
                ]
              },
              "sunsetSecretId": {
                "type": "string",
                "description": "This is used to identify variables that have been migrated from type secret to sensitive."
              },
              "legacyValue": {
                "type": "string",
                "description": "Legacy now-encryption ciphertext, present after migration swaps value/vsmValue"
              },
              "decrypted": {
                "type": "boolean",
                "enum": [
                  false,
                  true
                ]
              },
              "value": {
                "type": "string"
              },
              "vsmValue": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "key": {
                "type": "string"
              },
              "configurationId": {
                "type": "string",
                "nullable": true
              },
              "createdAt": {
                "type": "number"
              },
              "updatedAt": {
                "type": "number"
              },
              "createdBy": {
                "type": "string",
                "nullable": true
              },
              "updatedBy": {
                "type": "string",
                "nullable": true
              },
              "gitBranch": {
                "type": "string"
              },
              "edgeConfigId": {
                "type": "string",
                "nullable": true
              },
              "edgeConfigTokenId": {
                "type": "string",
                "nullable": true
              },
              "contentHint": {
                "nullable": true,
                "oneOf": [
                  {
                    "type": "object",
                    "required": [
                      "storeId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "redis-url"
                        ]
                      },
                      "storeId": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "storeId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "redis-rest-api-url"
                        ]
                      },
                      "storeId": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "storeId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "redis-rest-api-token"
                        ]
                      },
                      "storeId": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "storeId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "redis-rest-api-read-only-token"
                        ]
                      },
                      "storeId": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "storeId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "blob-read-write-token"
                        ]
                      },
                      "storeId": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "storeId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "postgres-url"
                        ]
                      },
                      "storeId": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "storeId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "postgres-url-non-pooling"
                        ]
                      },
                      "storeId": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "storeId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "postgres-prisma-url"
                        ]
                      },
                      "storeId": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "storeId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "postgres-user"
                        ]
                      },
                      "storeId": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "storeId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "postgres-host"
                        ]
                      },
                      "storeId": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "storeId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "postgres-password"
                        ]
                      },
                      "storeId": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "storeId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "postgres-database"
                        ]
                      },
                      "storeId": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "storeId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "postgres-url-no-ssl"
                        ]
                      },
                      "storeId": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "integrationConfigurationId",
                      "integrationId",
                      "integrationProductId",
                      "storeId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "integration-store-secret"
                        ]
                      },
                      "storeId": {
                        "type": "string"
                      },
                      "integrationId": {
                        "type": "string"
                      },
                      "integrationProductId": {
                        "type": "string"
                      },
                      "integrationConfigurationId": {
                        "type": "string"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "required": [
                      "projectId",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "flags-connection-string"
                        ]
                      },
                      "projectId": {
                        "type": "string"
                      }
                    }
                  }
                ]
              },
              "internalContentHint": {
                "type": "object",
                "description": "Similar to `contentHints`, but should not be exposed to the user.",
                "nullable": true,
                "required": [
                  "encryptedValue",
                  "type"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "flags-secret"
                    ]
                  },
                  "encryptedValue": {
                    "type": "string",
                    "description": "Contains the `value` of the env variable, encrypted with a special key to make decryption possible in the subscriber Lambda."
                  }
                }
              },
              "comment": {
                "type": "string"
              },
              "customEnvironmentIds": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "system": {
                "type": "boolean",
                "enum": [
                  false,
                  true
                ]
              }
            }
          }
        }
      ]
    },
    "failed": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "key": {
                "type": "string"
              },
              "envVarId": {
                "type": "string"
              },
              "envVarKey": {
                "type": "string"
              },
              "action": {
                "type": "string"
              },
              "link": {
                "type": "string"
              },
              "value": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "production",
                        "preview",
                        "development"
                      ]
                    }
                  }
                ]
              },
              "gitBranch": {
                "type": "string"
              },
              "target": {
                "oneOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "production",
                        "preview",
                        "development",
                        "preview",
                        "development"
                      ]
                    }
                  },
                  {
                    "type": "string",
                    "enum": [
                      "production",
                      "preview",
                      "development"
                    ]
                  }
                ]
              },
              "project": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
```

### 400: One of the provided values in the request body is invalid.
One of the provided values in the request query is invalid.
The environment variable coudn't be created because an ongoing update env update is already happening
The environment variable coudn't be created because project document is too large

### 401: The request is not authorized.

### 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.
The environment variable cannot be created because it already exists
Additional permissions are required to create production environment variables

### 404: No description

### 409: The project is being transfered and creating an environment variable is not possible

### 429: No description

### 500: No description

---

## Related

- [projects endpoints](/docs/rest-api#projects)

- [REST API overview](/docs/rest-api)

- [OpenAPI spec](https://openapi.vercel.sh/) (machine-readable, all endpoints)

---

[View full sitemap](/docs/sitemap)