---
title: "Create one or more shared environment variables"
method: POST
path: "/v1/env"
tags: ["environment"]
---

# Create one or more shared environment variables

`POST /v1/env`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/v1/env`
- Auth: HTTP bearer

Creates shared environment variable(s) for a team.

## Query parameters

- `teamId` string
- `slug` string

## Request body

- union
  - object
    - `evs` object[], required
      - `key` string, required: The name of the Shared Environment Variable
      - `value` string, required: The value of the Shared Environment Variable
      - `comment` string: A comment to add context on what this Shared Environment Variable is for
    - `type` 'encrypted' | 'sensitive': The type of environment variable
    - `target` string[], required: The target environment of the Shared Environment Variable
    - `projectId` string[]: Associate a Shared Environment Variable to projects.
  - object
    - `evs` object[], required
      - `key` string, required: The name of the Shared Environment Variable
      - `value` string, required: The value of the Shared Environment Variable
      - `comment` string: A comment to add context on what this Shared Environment Variable is for
    - `type` 'encrypted' | 'sensitive': The type of environment variable
    - `target` string[]: The target environment of the Shared Environment Variable
    - `projectId` string[]: Associate a Shared Environment Variable to projects.
  - object
    - `evs` object[], required
      - `key` string, required: The name of the Shared Environment Variable
      - `value` string, required: The value of the Shared Environment Variable
      - `comment` string: A comment to add context on what this Shared Environment Variable is for
    - `type` 'encrypted' | 'sensitive': The type of environment variable
    - `target` string[]: The target environment of the Shared Environment Variable
    - `projectId` string[]: Associate a Shared Environment Variable to projects.

## Response `201`

- object
  - `created` object[], required
    - `applyToAllCustomEnvironments` false | true: whether or not this env varible applies to custom environments
    - `comment` string: A user provided comment that describes what this Shared Env Var is for.
    - `created` string, date-time: The date when the Shared Env Var was created.
    - `createdAt` number: Timestamp for when the Shared Env Var was created.
    - `createdBy` string, nullable: The unique identifier of the user who created the Shared Env Var.
    - `customEnvironmentIds` string[]: The custom environment IDs that this Shared Env Var is scoped to.
    - `decrypted` false | true: whether or not this env variable is decrypted
    - `deletedAt` number: Timestamp for when the Shared Env Var was (soft) deleted.
    - `deletedBy` string, nullable: The unique identifier of the user who deleted the Shared Env Var.
    - `id` string: The unique identifier of the Shared Env Var.
    - `key` string: The name of the Shared Env Var.
    - `lastEditedByDisplayName` string: The last editor full name or username.
    - `lastEditedByPrincipal` union
      - object: The principal that last edited this env var, when the editor id resolves to a known user or app. Lets clients render the right avatar instead of assuming every editor is a user.
        - `avatar` string
        - `id` string, required
        - `name` string, nullable
        - `type` 'user', required
        - `username` string, required
      - object: The principal that last edited this env var, when the editor id resolves to a known user or app. Lets clients render the right avatar instead of assuming every editor is a user.
        - `avatar` string
        - `id` string, required
        - `name` string, required
        - `type` 'app', required
    - `ownerId` string, nullable: The unique identifier of the owner (team) the Shared Env Var was created for.
    - `projectId` string[]: The unique identifiers of the projects which the Shared Env Var is linked to.
    - `target` string[]: environments this env variable targets
    - `type` 'encrypted' | 'plain' | 'sensitive' | 'system': The type of this cosmos doc instance, if blank, assume secret.
    - `updatedAt` number: Timestamp for when the Shared Env Var was last updated.
    - `updatedBy` string, nullable: The unique identifier of the user who last updated the Shared Env Var.
    - `value` string: The value of the Shared Env Var.
  - `failed` object[], required
    - `error` object, required
      - `action` string
      - `code` string, required
      - `envVarId` string
      - `envVarKey` string
      - `gitBranch` string
      - `key` string
      - `link` string
      - `message` string, required
      - `project` string
      - `target` union
        - string[]
        - 'development' | 'development' | 'preview' | 'preview' | 'production'
      - `value` union
        - string
        - string[]

## Other responses

- `400`: One of the provided values in the request body 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.
- `404`
- `410`

## Changes

- **2026-09-30** `099fbe1f521c`: 1 info
  - added the non-success response with the status `404`
- **2026-09-24** `dd6a90982ed0`: 1 info
  - added the optional property `created/items/lastEditedByPrincipal` to the response with the `201` status
- **2026-07-21** `2ae10ee9d21c`: 1 info
  - added the non-success response with the status `410`
- **2026-06-11** `14b4658f819e`: 2 info
  - added `subschema #3` to the request body `anyOf` list
  - added the optional property `created/items/customEnvironmentIds` to the response with the `201` status
- **2026-01-22** `c12186034433`: 4 warning
  - added the new `false` enum value to the `created/items/applyToAllCustomEnvironments` response property for the response status `201`
  - added the new `false` enum value to the `created/items/decrypted` response property for the response status `201`
  - added the new `true` enum value to the `created/items/applyToAllCustomEnvironments` response property for the response status `201`
  - added the new `true` enum value to the `created/items/decrypted` response property for the response status `201`

[Operation history](https://skmtc.dev/vercel/apis/vercel-api/changes/v1/env/post.md)

---

[API](https://skmtc.dev/vercel/apis/vercel-api.md) - [All operations](https://skmtc.dev/vercel/apis/vercel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/vercel-api/revisions/60686c0e1f6a?raw)