> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Environment Variable

> Creates a new environment variable. Environment variables can be global (same value for all environments) or environment-specific (different values per environment). The variable is automatically deployed to all environments.

## Endpoint

```plaintext theme={null}
POST /apiops/projects/{projectName}/environmentVariables/{name}/
```

## Authentication

Requires a Personal API Access Token.

### Header

```plaintext theme={null}
Authorization: Bearer YOUR_TOKEN
```

## Request

### Headers

| Header        | Value            | Required |
| ------------- | ---------------- | -------- |
| Authorization | Bearer {token}   | Yes      |
| Content-Type  | application/json | Yes      |

### Path Parameters

| Parameter   | Type   | Required | Description                                     |
| ----------- | ------ | -------- | ----------------------------------------------- |
| projectName | string | Yes      | Project name (can be "admin" for admin project) |
| name        | string | Yes      | Environment variable name (unique identifier)   |

### Request Body

#### Full JSON Body Example - Global Environment Variable

```json theme={null}
{
  "name": "API_KEY",
  "description": "API Key for external service",
  "global": true,
  "globalValue": "secret-api-key-12345",
  "globalVisible": false,
  "environmentValueList": null
}
```

#### Full JSON Body Example - Environment-Specific Variable

```json theme={null}
{
  "name": "API_BASE_URL",
  "description": "Base URL for API calls",
  "global": false,
  "globalValue": null,
  "globalVisible": true,
  "environmentValueList": [
    {
      "environmentName": "production",
      "value": "https://api.production.example.com",
      "visible": true
    },
    {
      "environmentName": "staging",
      "value": "https://api.staging.example.com",
      "visible": true
    },
    {
      "environmentName": "development",
      "value": "https://api.dev.example.com",
      "visible": true
    }
  ]
}
```

#### Full JSON Body Example - Environment-Specific with Secret Values

```json theme={null}
{
  "name": "DATABASE_PASSWORD",
  "description": "Database password",
  "global": false,
  "globalValue": null,
  "globalVisible": true,
  "environmentValueList": [
    {
      "environmentName": "production",
      "value": "prod-secret-password",
      "visible": false
    },
    {
      "environmentName": "staging",
      "value": "staging-secret-password",
      "visible": false
    }
  ]
}
```

#### Request Body Fields

| Field                | Type                 | Required | Default | Description                                                                                                                                    |
| -------------------- | -------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| name                 | string               | Yes      | -       | Environment variable name (must match path parameter)                                                                                          |
| description          | string               | No       | -       | Environment variable description                                                                                                               |
| global               | boolean              | No       | false   | Whether the variable is global (true) or environment-specific (false)                                                                          |
| globalValue          | string\|null         | No       | null    | Global value (required if global=true)                                                                                                         |
| globalVisible        | boolean              | No       | true    | Whether global value is visible (not secret)                                                                                                   |
| environmentValueList | array\[object]\|null | No       | null    | List of environment-specific values (required if global=false). See [Environment Value Object](#environment-value-object-environmentvaluelist) |

### Environment Value Object (environmentValueList)

| Field           | Type    | Required | Description                |                                           |
| --------------- | ------- | -------- | -------------------------- | ----------------------------------------- |
| environmentName | string  | Yes      | Environment name           |                                           |
| value           | string  | Yes      | Value for this environment |                                           |
| visible         | boolean | No       | false                      | Whether the value is visible (not secret) |

### Notes

* `name` in path must match `name` in body
* `name` must be unique within the project
* If `global=true`, provide `globalValue` and set `environmentValueList=null`
* If `global=false`, provide `environmentValueList` with at least one environment value
* `visible=false` marks the value as secret (will be masked in responses)
* `globalVisible=false` marks the global value as secret
* Variable is automatically deployed to all environments after creation

## Response

### Success Response (200 OK) - Deployment Successful

When the environment variable is created and successfully deployed to all environments:

```json theme={null}
{
  "status": "SUCCESS",
  "deploymentResult": {
    "success": true,
    "responseTime": 1500,
    "detailList": [
      {
        "envName": "production",
        "success": true,
        "detail": "Deployed successfully",
        "responseTime": 450
      },
      {
        "envName": "staging",
        "success": true,
        "detail": "Deployed successfully",
        "responseTime": 420
      }
    ],
    "firstFromApiResultList": {
      "envName": "production",
      "success": true,
      "detail": "Deployed successfully",
      "responseTime": 450
    }
  }
}
```

### Error Response (400 Bad Request)

```json theme={null}
{
  "error": "bad_request",
  "error_description": "Environment variable name can not be empty!"
}
```

or

```json theme={null}
{
  "error": "bad_request",
  "error_description": "Environment variable name in path (API_KEY) does not match name in body (API_BASE_URL)!"
}
```

or

```json theme={null}
{
  "error": "bad_request",
  "error_description": "Environment variable (name: API_KEY) already exists!"
}
```

### Common Causes

* Missing or empty `name` field
* Name in path does not match name in body
* Environment variable name already exists
* Invalid global/environment-specific configuration

### Deployment Failure Note

When `status` is "SUCCESS" but `deploymentResult.success` is false, the environment variable was created in the Manager but failed to deploy to one or more Gateway environments. Common causes:

* Gateway not running or not reachable (e.g., "Connection refused" on port 8091)
* Network connectivity issues between Manager and Gateway
* Environment name mismatch or environment not configured

## cURL Example

### Example 1: Create Global Environment Variable

```bash theme={null}
curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/environmentVariables/API_KEY/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API_KEY",
    "description": "API Key for external service",
    "global": true,
    "globalValue": "secret-api-key-12345",
    "globalVisible": false
  }'
```

### Example 2: Create Environment-Specific Variable

```bash theme={null}
curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/environmentVariables/API_BASE_URL/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API_BASE_URL",
    "description": "Base URL for API calls",
    "global": false,
    "environmentValueList": [
      {
        "environmentName": "production",
        "value": "https://api.production.example.com",
        "visible": true
      },
      {
        "environmentName": "staging",
        "value": "https://api.staging.example.com",
        "visible": true
      }
    ]
  }'
```

## Permissions

User must have **`SECRETS` + `MANAGE`** permission in the project. For deployment operations (when deploying environment variables to environments), user must also have **`SECRETS` + `DEPLOY_UNDEPLOY`** permission.

## Notes and Warnings

* **Name Uniqueness**:
  * Environment variable name must be unique within the project
  * If name already exists, creation will fail

* **Name Matching**:
  * Name in path must match name in body
  * Case-insensitive matching

* **Global vs Environment-Specific**:
  * `global=true` - Single value for all environments
  * `global=false` - Different values per environment

* **Secret Values**:
  * Set `visible=false` or `globalVisible=false` to mark values as secret
  * Secret values are masked (returned as `null`) in responses

* **Environment Names**:
  * Environment names must exist
  * Use `environmentName` (not `environmentId`)

* **Automatic Deployment**:
  * Variable is automatically deployed to all environments
  * Deployment results are returned in the response

* For deployment operations (when deploying environment variables to environments), user must also have **`SECRETS` + `DEPLOY_UNDEPLOY`** permission
  * User must have access to the project

## Related Documentation

* [List Environment Variables](/api-reference/environment-variables/crud/list-environment-variables) - List all environment variables
* [Update Environment Variable](/api-reference/environment-variables/crud/update-environment-variable) - Update an environment variable