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

# Create Proposal

> Proposes a flag config change for a protected environment.

Only valid for [protected environments](/docs/concepts/environments#protected-environments). Requires **Enterprise** plan.

Only one `pending` proposal can exist per flag + environment at a time.

## Proposal lifecycle

```
pending ──approve──▶ approved  (flag version created, edge cache updated)
        ──reject───▶ rejected
```

`approved` and `rejected` are terminal — neither can be re-opened. To make another change to a protected environment after a proposal is resolved, create a new proposal.

## Path parameters

<ParamField path="projectId" type="string" required />

<ParamField path="envId" type="string" required />

<ParamField path="flagKey" type="string" required />

## Body

Same shape as [Update Flag Config](/docs/api-reference/flags/update-flag-config) body.

<ParamField body="version" type="number" required>
  The current latest version of the flag config in this environment. Recorded as the proposal's
  intended base so reviewers can see what the change is based on. The actual stored version is
  assigned at approval time (always `latest + 1`) — this field is **not** used as a concurrency
  gate.
</ParamField>

<ParamField body="enabled" type="boolean" required />

<ParamField body="defaultValue" type="boolean | string | number" required />

<ParamField body="rules" type="Rule[]" required />

<ParamField body="variants" type="Variant[]" />

<RequestExample>
  ```bash theme={null}
  curl -X POST https://nest.feather.mupeni.dev/v1/projects/proj_01hx.../environments/env_01hx.../flags/new-checkout/proposals \
    -H "Authorization: Bearer <server_key>" \
    -H "Content-Type: application/json" \
    -d '{
      "version": 3,
      "enabled": true,
      "defaultValue": false,
      "rules": [
        {
          "id": "rule-1",
          "name": "All users",
          "enabled": true,
          "conditionOperator": "AND",
          "conditions": [],
          "value": true
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "id": "prop_01hx...",
    "flagId": "flag_01hx...",
    "environmentId": "env_01hx...",
    "status": "pending",
    "proposedConfig": { ... },
    "createdBy": "key_01hx...",
    "createdAt": "2024-04-10T14:00:00.000Z"
  }
  ```

  ```json 409 theme={null}
  {
    "error": {
      "code": "PROPOSAL_ALREADY_PENDING",
      "message": "A pending proposal already exists for this flag and environment."
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": { "code": "UPGRADE_REQUIRED", "message": "Change requests require an Enterprise plan." }
  }
  ```
</ResponseExample>