---
title: Create a change request for a flag in an environment
slug: feature-experimentation/api/create-a-change-request-for-a-flag-in-an-environment
docTags: 
createdAt: 2026-10-13T18:16:15.508Z
---

{
  "id": "ZMgn95nj9BveIqB2HOL86",
  "type": "api-oas-v2",
  "data": {
    "method": "POST",
    "url": "http://localhost:3002//projects/{project_id}/flags/{flag_key}/environments/{environment_key}/ruleset/change_requests",
    "servers": [
      {
        "url": "http://localhost:3002//projects/{project_id}/flags/{flag_key}/environments/{environment_key}/ruleset/change_requests",
        "description": "Local server"
      },
      {
        "url": "https://api.app.optimizely.com/flags-scheduling/projects/{project_id}/flags/{flag_key}/environments/{environment_key}/ruleset/change_requests",
        "description": "Production server"
      }
    ],
    "name": "Create a change request for a flag in an environment",
    "description": "Create a change request for a flag in an environment\n",
    "contentType": "application/json",
    "request": {
      "pathParameters": [
        {
          "kind": "required",
          "name": "project_id",
          "type": "integer",
          "description": ""
        },
        {
          "kind": "required",
          "name": "flag_key",
          "type": "string",
          "description": ""
        },
        {
          "kind": "required",
          "name": "environment_key",
          "type": "string",
          "description": ""
        }
      ],
      "headerParameters": [
        {
          "name": "accept",
          "type": "string",
          "kind": "optional",
          "description": "Generated from available response content types",
          "enum": [
            "application/json"
          ],
          "default": "application/json"
        }
      ],
      "queryParameters": [],
      "bodyDataParameters": [
        {
          "kind": "required",
          "name": "body",
          "type": "object",
          "description": "",
          "customType": "ChangeRequestCreateRequest",
          "schema": [
            {
              "name": "operations",
              "kind": "required",
              "type": "array",
              "description": "List of JSON Patch operations to apply.",
              "modelRef": "#/components/schemas/JsonPatchOperation",
              "customType": "JsonPatchOperation[]",
              "schema": [
                {
                  "name": "op",
                  "kind": "required",
                  "type": "string<replace | add | remove>",
                  "description": "The JSON Patch operation type.",
                  "enum": [
                    "replace",
                    "add",
                    "remove"
                  ]
                },
                {
                  "name": "path",
                  "kind": "required",
                  "type": "string",
                  "description": "<p>JSON Pointer (RFC 6901) targeting a location within the document.</p>"
                },
                {
                  "name": "value",
                  "kind": "optional",
                  "type": "object",
                  "nullable": true,
                  "description": "<p>New value; required for 'replace' and 'add' ops.</p>",
                  "complexType": "oneOf",
                  "complexItems": [],
                  "schema": []
                }
              ]
            },
            {
              "name": "reason",
              "kind": "optional",
              "type": "string",
              "description": "Reason for the change request."
            },
            {
              "name": "schedule",
              "kind": "optional",
              "type": "object",
              "description": "<p>Optional scheduled execution time. Presence makes the change request scheduled; absence creates an immediate change request.</p>",
              "complexType": "allOf",
              "complexItems": [
                {
                  "name": "ScheduledTime",
                  "description": "",
                  "modelRef": "#/components/schemas/ScheduledTime",
                  "schema": [
                    {
                      "name": "time",
                      "kind": "required",
                      "type": "string",
                      "description": "<p>The schedule will run at this time. Expected format: hh</p><div></div> (24 hour)<p></p>",
                      "example": 1214
                    },
                    {
                      "name": "time_zone",
                      "kind": "required",
                      "type": "string",
                      "description": "The timezone information for the scheduled time. Must be an IANA timezone.",
                      "example": "Etc/UTC"
                    },
                    {
                      "name": "date",
                      "kind": "required",
                      "type": "string",
                      "description": "<p>The schedule will run at this date. Expected format: yyyy-mm-dd.</p>",
                      "example": "2023-07-30"
                    }
                  ]
                }
              ],
              "schema": []
            }
          ],
          "modelRef": "#/components/schemas/ChangeRequestCreateRequest",
          "isExpanded": true
        }
      ],
      "formDataParameters": [],
      "oAuthParameters": [
        {
          "id": "BearerAuth",
          "name": "BearerAuth",
          "kind": "optional",
          "type": "http",
          "description": "<p>To get a personal token, see <a href=\"https://docs.developers.optimizely.com/web/docs/personal-token\" target=\"_blank\">https://docs.developers.optimizely.com/web/docs/personal-token</a></p>",
          "scheme": "bearer"
        }
      ],
      "cookieParameters": []
    },
    "responses": [
      {
        "statusCode": "201",
        "description": "Successful Response",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "customType": "ChangeRequest",
            "schema": [
              {
                "name": "id",
                "kind": "required",
                "type": "integer",
                "description": "The change request ID."
              },
              {
                "name": "project_id",
                "kind": "required",
                "type": "integer",
                "description": "The project ID."
              },
              {
                "name": "entity_key",
                "kind": "required",
                "type": "string",
                "description": "<p>The key of the entity (e.g. flag key).</p>"
              },
              {
                "name": "entity_id",
                "kind": "optional",
                "type": "integer",
                "description": "<p>The ID of the entity (e.g. flag ID).</p>"
              },
              {
                "name": "entity_type",
                "kind": "required",
                "type": "string",
                "description": "The entity type."
              },
              {
                "name": "environment",
                "kind": "required",
                "type": "string",
                "description": "The environment key."
              },
              {
                "name": "environment_id",
                "kind": "optional",
                "type": "integer",
                "description": "The environment ID."
              },
              {
                "name": "job_status",
                "kind": "required",
                "type": "string",
                "description": "The status of the scheduled job."
              },
              {
                "name": "created_by",
                "kind": "required",
                "type": "string",
                "description": "The user who created the change request."
              },
              {
                "name": "updated_by",
                "kind": "required",
                "type": "string",
                "description": "The user who last updated the change request."
              },
              {
                "name": "created_at",
                "kind": "required",
                "type": "string<date-time>",
                "description": "Timestamp when the change request was created.",
                "format": "date-time"
              },
              {
                "name": "updated_at",
                "kind": "optional",
                "type": "string<date-time>",
                "description": "Timestamp when the change request was last updated.",
                "format": "date-time"
              },
              {
                "name": "archived",
                "kind": "required",
                "type": "boolean",
                "description": "Whether the change request is archived."
              },
              {
                "name": "revision",
                "kind": "required",
                "type": "integer",
                "description": "The revision number."
              },
              {
                "name": "approval_required",
                "kind": "required",
                "type": "boolean",
                "description": "Whether approval is required for this change request."
              },
              {
                "name": "current_approval_state_id",
                "kind": "optional",
                "type": "integer",
                "description": "The current approval state ID."
              },
              {
                "name": "approval_status",
                "kind": "optional",
                "type": "string<pending | accepted | rejected | withdrawn>",
                "description": "The current approval status.",
                "enum": [
                  "pending",
                  "accepted",
                  "rejected",
                  "withdrawn"
                ]
              },
              {
                "name": "policy_id",
                "kind": "optional",
                "type": "integer",
                "description": "The ID of the approval policy that governs this change request."
              },
              {
                "name": "policy_name",
                "kind": "optional",
                "type": "string",
                "description": "The name of the approval policy that governs this change request."
              },
              {
                "name": "is_current_user_approver",
                "kind": "optional",
                "type": "boolean",
                "nullable": true,
                "description": "<p>Whether the current user is an approver for this change request. true if the user can approve, false if not, null when the status is not pending or the approver cannot be resolved.</p>"
              },
              {
                "name": "reason",
                "kind": "optional",
                "type": "string",
                "description": "The reason from the initial submission."
              },
              {
                "name": "operations",
                "kind": "required",
                "type": "array",
                "description": "List of JSON Patch operations.",
                "modelRef": "#/components/schemas/JsonPatchOperation",
                "customType": "JsonPatchOperation[]",
                "schema": [
                  {
                    "name": "op",
                    "kind": "required",
                    "type": "string<replace | add | remove>",
                    "description": "The JSON Patch operation type.",
                    "enum": [
                      "replace",
                      "add",
                      "remove"
                    ]
                  },
                  {
                    "name": "path",
                    "kind": "required",
                    "type": "string",
                    "description": "<p>JSON Pointer (RFC 6901) targeting a location within the document.</p>"
                  },
                  {
                    "name": "value",
                    "kind": "optional",
                    "type": "object",
                    "nullable": true,
                    "description": "<p>New value; required for 'replace' and 'add' ops.</p>",
                    "complexType": "oneOf",
                    "complexItems": [],
                    "schema": []
                  }
                ]
              },
              {
                "name": "status_history",
                "kind": "optional",
                "type": "array",
                "description": "History of status changes.",
                "modelRef": "#/components/schemas/ChangeRequestStatusHistory",
                "customType": "ChangeRequestStatusHistory[]",
                "schema": [
                  {
                    "name": "id",
                    "kind": "required",
                    "type": "integer",
                    "description": "The unique identifier for the status history entry."
                  },
                  {
                    "name": "status",
                    "kind": "required",
                    "type": "string<pending | accepted | rejected | withdrawn>",
                    "description": "The status of the change request at this point.",
                    "enum": [
                      "pending",
                      "accepted",
                      "rejected",
                      "withdrawn"
                    ]
                  },
                  {
                    "name": "email",
                    "kind": "required",
                    "type": "string",
                    "description": "The email of the user who set this status."
                  },
                  {
                    "name": "reason",
                    "kind": "optional",
                    "type": "string",
                    "description": "The reason for the status change."
                  },
                  {
                    "name": "approved_via_team_id",
                    "kind": "optional",
                    "type": "integer",
                    "description": "<p>The team ID through which the user approved (if team-based).</p>"
                  },
                  {
                    "name": "approved_via_team_name",
                    "kind": "optional",
                    "type": "string",
                    "description": "<p>The team name through which the user approved (if team-based).</p>"
                  },
                  {
                    "name": "created_at",
                    "kind": "required",
                    "type": "string<date-time>",
                    "description": "Timestamp when this status was set.",
                    "format": "date-time"
                  }
                ]
              },
              {
                "name": "schedule",
                "kind": "optional",
                "type": "object",
                "nullable": true,
                "description": "<p>The scheduled execution time. Null for immediate change requests; present when the change request is scheduled.</p>",
                "complexType": "allOf",
                "complexItems": [
                  {
                    "name": "ScheduleTimeResponse",
                    "description": "",
                    "modelRef": "#/components/schemas/ScheduleTimeResponse",
                    "schema": [
                      {
                        "name": "date",
                        "kind": "optional",
                        "type": "string<date>",
                        "description": "<p>The schedule will run at this date. Expected format: yyyy-mm-dd.</p>",
                        "example": "2025-02-18",
                        "format": "date"
                      },
                      {
                        "name": "time",
                        "kind": "optional",
                        "type": "string",
                        "description": "<p>The schedule will run at this time. Expected format: hh</p><div></div> (24 hour).<p></p>",
                        "example": "23:59",
                        "pattern": "^([01]?[0-9]|2[0-3]):([0-5][0-9])$"
                      },
                      {
                        "name": "time_zone",
                        "kind": "optional",
                        "type": "string",
                        "description": "The timezone information for the scheduled time.",
                        "example": "UTC"
                      },
                      {
                        "name": "utc_time",
                        "kind": "optional",
                        "type": "string<date-time>",
                        "description": "The utc timestamp when the scheduled job will be executed.",
                        "example": "2025-02-18T23:59:59+00:00",
                        "format": "date-time"
                      }
                    ]
                  }
                ],
                "schema": []
              }
            ],
            "modelRef": "#/components/schemas/ChangeRequest",
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "401",
        "description": "Not Authenticated",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "example": "{\"details\":\"Not authenticated\",\"status\":401}",
            "description": "",
            "customType": "ErrorResponse",
            "schema": [
              {
                "name": "details",
                "kind": "required",
                "type": "string",
                "description": "Details of Error."
              },
              {
                "name": "status",
                "kind": "required",
                "type": "integer",
                "description": "Status code of the response.",
                "example": 400
              }
            ],
            "modelRef": "#/components/schemas/ErrorResponse",
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "403",
        "description": "Forbidden",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "example": "{\"details\":\"Forbidden\",\"status\":403}",
            "description": "",
            "customType": "ErrorResponse",
            "schema": [
              {
                "name": "details",
                "kind": "required",
                "type": "string",
                "description": "Details of Error."
              },
              {
                "name": "status",
                "kind": "required",
                "type": "integer",
                "description": "Status code of the response.",
                "example": 400
              }
            ],
            "modelRef": "#/components/schemas/ErrorResponse",
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "422",
        "description": "Validation Error",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "customType": "HTTPValidationError",
            "schema": [
              {
                "name": "detail",
                "kind": "optional",
                "type": "array",
                "description": "",
                "modelRef": "#/components/schemas/ValidationError",
                "customType": "ValidationError[]",
                "schema": [
                  {
                    "name": "loc",
                    "kind": "required",
                    "type": "array",
                    "description": "Path to the invalid value",
                    "example": "",
                    "itemType": "object",
                    "customType": "object[]",
                    "itemExample": "",
                    "itemDefault": ""
                  },
                  {
                    "name": "msg",
                    "kind": "required",
                    "type": "string",
                    "description": "Error message"
                  },
                  {
                    "name": "type",
                    "kind": "required",
                    "type": "string",
                    "description": "Error type"
                  }
                ]
              },
              {
                "name": "status",
                "kind": "optional",
                "type": "integer",
                "description": "Status code of the response.",
                "example": 422
              }
            ],
            "modelRef": "#/components/schemas/HTTPValidationError",
            "isExpanded": true
          }
        ]
      }
    ],
    "hasXCodeSamples": false,
    "examples": {
      "languages": [
        {
          "id": "AsB5zwQWmRf2KFHhHbHf-",
          "language": "curl",
          "label": "cURL",
          "code": "curl --request POST \\\n     --url http://localhost:3002//projects/{project_id}/flags/{flag_key}/environments/{environment_key}/ruleset/change_requests \\\n     --header 'accept: application/json' \\\n     --header 'content-type: application/json' \\\n     --data '{\n     \"operations\": [\n     {\n     \"op\": \"\",\n     \"path\": \"\"\n     }\n     ],\n     \"schedule\": {\n     \"time\": 1214,\n     \"time_zone\": \"Etc/UTC\",\n     \"date\": \"2023-07-30\"\n     }\n     }'"
        },
        {
          "id": "1CKXlx3NnGlI_7wqw_ZdD",
          "language": "javascript",
          "label": "javascript",
          "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n   \"operations\": [\n      {\n         \"op\": \"\",\n         \"path\": \"\"\n      }\n   ],\n   \"schedule\": {\n      \"time\": 1214,\n      \"time_zone\": \"Etc/UTC\",\n      \"date\": \"2023-07-30\"\n   }\n});\n\nvar requestOptions = {\n   method: 'POST',\n   headers: myHeaders,\n   body: raw,\n   redirect: 'follow'\n};\n\nfetch(\"http://localhost:3002//projects/{project_id}/flags/{flag_key}/environments/{environment_key}/ruleset/change_requests\", requestOptions)\n   .then(response => response.text())\n   .then(result => console.log(result))\n   .catch(error => console.log('error', error));"
        },
        {
          "id": "txRV0iHAy8xjfX5wFbPss",
          "language": "ruby",
          "label": "Ruby",
          "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"http://localhost:3002//projects/{project_id}/flags/{flag_key}/environments/{environment_key}/ruleset/change_requests\")\n\nhttp = Net::HTTP.new(url.host, url.port);\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n   \"operations\": [\n      {\n         \"op\": \"\",\n         \"path\": \"\"\n      }\n   ],\n   \"schedule\": {\n      \"time\": 1214,\n      \"time_zone\": \"Etc/UTC\",\n      \"date\": \"2023-07-30\"\n   }\n})\n\nresponse = http.request(request)\nputs response.read_body\n"
        },
        {
          "id": "koTDB4jXGHJTPXaJU_Zd0",
          "language": "python",
          "label": "Python",
          "code": "import requests\nimport json\n\nurl = \"http://localhost:3002//projects/{project_id}/flags/{flag_key}/environments/{environment_key}/ruleset/change_requests\"\n\npayload = json.dumps({\n   \"operations\": [\n      {\n         \"op\": \"\",\n         \"path\": \"\"\n      }\n   ],\n   \"schedule\": {\n      \"time\": 1214,\n      \"time_zone\": \"Etc/UTC\",\n      \"date\": \"2023-07-30\"\n   }\n})\nheaders = {\n   'accept': 'application/json',\n   'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n"
        }
      ],
      "selectedLanguageId": "AsB5zwQWmRf2KFHhHbHf-"
    },
    "results": {
      "languages": [
        {
          "id": "0QMV_l5F3bJG8o3Q2PlB8",
          "language": "201",
          "code": "// Successful Response\n{\n  \"id\": 0,\n  \"project_id\": 0,\n  \"entity_key\": \"\",\n  \"entity_id\": 0,\n  \"entity_type\": \"\",\n  \"environment\": \"\",\n  \"environment_id\": 0,\n  \"job_status\": \"\",\n  \"created_by\": \"\",\n  \"updated_by\": \"\",\n  \"created_at\": \"\",\n  \"updated_at\": \"\",\n  \"archived\": false,\n  \"revision\": 0,\n  \"approval_required\": false,\n  \"current_approval_state_id\": 0,\n  \"approval_status\": \"\",\n  \"policy_id\": 0,\n  \"policy_name\": \"\",\n  \"is_current_user_approver\": false,\n  \"reason\": \"\",\n  \"operations\": [\n    {\n      \"op\": \"\",\n      \"path\": \"\",\n      \"value\": {}\n    }\n  ],\n  \"status_history\": [\n    {\n      \"id\": 0,\n      \"status\": \"\",\n      \"email\": \"\",\n      \"reason\": \"\",\n      \"approved_via_team_id\": 0,\n      \"approved_via_team_name\": \"\",\n      \"created_at\": \"\"\n    }\n  ],\n  \"schedule\": {}\n}"
        },
        {
          "id": "dfd8UxI-3_frFL2bL1mWl",
          "language": "401",
          "code": "// Not Authenticated\n{\n  \"details\": \"\",\n  \"status\": 400\n}"
        },
        {
          "id": "mUurbeWbSBUvgluPXhrHI",
          "language": "403",
          "code": "// Forbidden\n{\n  \"details\": \"\",\n  \"status\": 400\n}"
        },
        {
          "id": "jAPBYgJKc21FYg89AcP9h",
          "language": "422",
          "code": "// Validation Error\n{\n  \"detail\": [\n    {\n      \"loc\": [\n        {}\n      ],\n      \"msg\": \"\",\n      \"type\": \"\"\n    }\n  ],\n  \"status\": 422\n}"
        }
      ],
      "selectedLanguageId": "0QMV_l5F3bJG8o3Q2PlB8"
    }
  },
  "children": [
    {
      "text": ""
    }
  ]
}