Unleash Change Requests API

openapi: 3.2.0
info:
  title: Unleash Admin Addons Change Requests API
  version: 7.4.1
  description: Create, update, and delete [Unleash addons](https://docs.getunleash.io/addons).
servers:
- url: https://app.unleash-instance.example.com
  description: Your Unleash instance (replace with your actual URL)
security:
- apiKey: []
- bearerToken: []
tags:
- name: Change Requests
  description: API for managing [change requests](https://docs.getunleash.io/concepts/change-requests).
paths:
  /api/admin/projects/{projectId}/change-requests/config:
    get:
      summary: Retrieves Change Request Configuration for a Project
      description: '**Enterprise feature**


        Given a projectId, this endpoint will retrieve change request configuration for the project'
      tags:
      - Change Requests
      operationId: getProjectChangeRequestConfig
      responses:
        '200':
          description: changeRequestConfigSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeRequestConfigSchema'
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/environments/{environment}/change-requests/config:
    put:
      summary: Updates Change Request Configuration for an Environment in the Project
      description: '**Enterprise feature**


        This endpoint will change the change request configuration for a given environment, set it to either on/off and optionally configure the number of approvals needed. The minimum number of approvals is 1 and the maximum number is 10. If you provide a number higher than 10 or lower than 1, Unleash will clamp it to the allowed range.'
      tags:
      - Change Requests
      operationId: updateProjectChangeRequestConfig
      requestBody:
        description: updateChangeRequestEnvironmentConfigSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateChangeRequestEnvironmentConfigSchema'
      responses:
        '200':
          description: This response has no body.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: environment
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/change-requests/scheduled:
    get:
      summary: Get Scheduled Change Requests Matching a Query.
      description: '**Enterprise feature**


        This endpoint retrieves basic information about all scheduled change requests that match the search criteria provided in the query parameters. The endpoint will return any change request that matches one or more of the provided parameters. If you use no query parameters, you''ll get an empty list.


        For instance, to find all the scheduled change requests that either touch feature `MyFeature` or strategy `0D198067-7D55-460C-9EC7-DB86E3AE261A`, you would use the query string `feature=MyFeature&strategyId=0D198067-7D55-460C-9EC7-DB86E3AE261A`.'
      tags:
      - Change Requests
      operationId: getScheduledChangeRequests
      responses:
        '200':
          description: changeRequestScheduledResultSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeRequestScheduledResultSchema'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NotFoundError
                    description: The name of the error kind
                  message:
                    type: string
                    example: Could not find the addon with ID "12345".
                    description: A description of what went wrong.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/environments/{environment}/change-requests:
    post:
      summary: Create/add Change to a Change Request
      description: '**Enterprise feature**


        Given a change request exists, this endpoint will attempt to add a change to


        an existing change request for the user. If a change request does not exist,


        it will attempt to create one.'
      tags:
      - Change Requests
      operationId: changeRequest
      requestBody:
        description: changeRequestOneOrManyCreateSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/changeRequestOneOrManyCreateSchema'
      responses:
        '200':
          description: changeRequestSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeRequestSchema'
        '400':
          description: The request data does not match what we expect.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: ValidationError
                    description: The name of the error kind
                  message:
                    type: string
                    example: The request payload you provided doesn't conform to the schema. The .parameters property should be object. You sent [].
                    description: A description of what went wrong.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: environment
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/change-requests/count:
    get:
      summary: Retrieves Number of Project Change Requests in Each State
      description: '**Enterprise feature**


        This endpoint will retrieve the number of project change requests that are: approved, applied, rejected, scheduled or awaiting review'
      tags:
      - Change Requests
      operationId: getChangeRequestsCount
      responses:
        '200':
          description: changeRequestsCountSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeRequestsCountSchema'
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/change-requests/open:
    get:
      summary: Retrieves Pending Change Requests in Configured Environments
      description: '**Enterprise feature**


        This endpoint will retrieve the pending change requests in the configured environments for the project, for the current user performing the request.'
      tags:
      - Change Requests
      operationId: getOpenChangeRequestsForUser
      deprecated: true
      responses:
        '200':
          description: changeRequestsSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeRequestsSchema'
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/change-requests/pending:
    get:
      summary: Retrieves Pending Change Requests in Configured Environments
      description: '**Enterprise feature**


        This endpoint will retrieve the pending change requests in the configured environments for the project, for the current user performing the request.'
      tags:
      - Change Requests
      operationId: getPendingChangeRequestsForUser
      responses:
        '200':
          description: changeRequestsSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeRequestsSchema'
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/change-requests:
    get:
      summary: Retrieves All Change Requests for a Project
      description: '**Enterprise feature**


        This endpoint will retrieve all change requests regardless of status for a given project. There''s an upper limit of last 300 change requests ordered by creation date.'
      tags:
      - Change Requests
      operationId: getChangeRequestsForProject
      responses:
        '200':
          description: changeRequestsSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeRequestsSchema'
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/change-requests/pending/{featureName}:
    get:
      summary: Retrieves All Pending Change Requests Referencing a Feature in the Project
      description: '**Enterprise feature**


        This endpoint will retrieve all pending change requests (change requests with a status of Draft | In review | Approved) referencing the given feature flag name.'
      tags:
      - Change Requests
      operationId: getPendingChangeRequestsForFeature
      responses:
        '200':
          description: changeRequestsSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeRequestsSchema'
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: featureName
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/change-requests/{id}:
    get:
      summary: Retrieves One Change Request by ID
      description: '**Enterprise feature**


        This endpoint will retrieve one change request if it matches the provided id.'
      tags:
      - Change Requests
      operationId: getChangeRequest
      responses:
        '200':
          description: changeRequestSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeRequestSchema'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NotFoundError
                    description: The name of the error kind
                  message:
                    type: string
                    example: Could not find the addon with ID "12345".
                    description: A description of what went wrong.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
    delete:
      summary: Deletes a Change Request by ID
      description: '**Enterprise feature**


        This endpoint will delete one change request if it matches the provided id.'
      tags:
      - Change Requests
      operationId: deleteChangeRequest
      responses:
        '200':
          description: This response has no body.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/change-requests/{changeRequestId}/changes/{changeId}:
    delete:
      summary: Discards a Change From a Change Request by Change ID
      description: '**Enterprise feature**


        This endpoint will discard one change from a change request if it matches the provided id.'
      tags:
      - Change Requests
      operationId: deleteChange
      responses:
        '200':
          description: This response has no body.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: changeRequestId
        in: path
        required: true
        schema:
          type: string
      - name: changeId
        in: path
        required: true
        schema:
          type: string
    put:
      summary: Edits a Single Change in a Change Request
      description: '**Enterprise feature**


        This endpoint will edit one change from a change request if it matches the provided id. The edit removes previous change and inserts a new one. You


        should not rely on the changeId for subsequent edits and always check the most recent changeId.'
      tags:
      - Change Requests
      operationId: editChange
      requestBody:
        description: changeRequestCreateSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/changeRequestCreateSchema'
      responses:
        '200':
          description: changeRequestSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeRequestSchema'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NotFoundError
                    description: The name of the error kind
                  message:
                    type: string
                    example: Could not find the addon with ID "12345".
                    description: A description of what went wrong.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: changeRequestId
        in: path
        required: true
        schema:
          type: string
      - name: changeId
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/change-requests/{id}/state:
    put:
      summary: This Endpoint Will Update the State of a Change Request
      description: '**Enterprise feature**


        This endpoint will update the state of a change request if the business rules allow it. The state can be one of the following: Draft, In review, Approved, Cancelled, Applied. In order to be approved, the change request must have at least one change and the number of approvals must be greater than or equal to the number of approvals required for the environment.


        Once a change request has been approved, it can be applied. Once a change request has been applied, it cannot be changed. Once a change request has been cancelled, it cannot be changed. Any change to a change request in the state of Approved will result in the state being set to In Review and the number of approvals will be reset.'
      tags:
      - Change Requests
      operationId: updateChangeRequestState
      responses:
        '200':
          description: changeRequestSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeRequestSchema'
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/change-requests/{id}/title:
    put:
      summary: This Endpoint Will Update the Custom Title of a Change Request
      description: '**Enterprise feature**


        Change requests get a default title e.g. Change Request #1. This endpoint allows to make the title


        more meaningful and describe the intent behind the Change Request'
      tags:
      - Change Requests
      operationId: updateChangeRequestTitle
      responses:
        '204':
          description: This response has no body.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/change-requests/{id}/approvers:
    put:
      summary: This Endpoint Will Update the Reviewers of a Change Request
      description: '**Enterprise feature**


        Change requests can have requests for review from users. This endpoint allows to add or remove reviewers from a change request. The maximum number of reviewers is 10.'
      tags:
      - Change Requests
      operationId: addChangeRequestReviewers
      responses:
        '204':
          description: This response has no body.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      summary: This Endpoint Fetches the Requested Approvers of a Change Request
      description: '**Enterprise feature**


        Change requests can have requests for review from users. This endpoint fetches the list of requested reviewers for a change request.'
      tags:
      - Change Requests
      operationId: getChangeRequestApprovers
      responses:
        '200':
          description: changeRequestAvailableReviewersSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeRequestAvailableReviewersSchema'
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/change-requests/{id}/comments:
    post:
      summary: This Endpoint Will Add a Comment to a Change Request
      description: '**Enterprise feature**


        This endpoint will add a comment to a change request for the user making the request.'
      tags:
      - Change Requests
      operationId: addChangeRequestComment
      requestBody:
        description: changeRequestAddCommentSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/changeRequestAddCommentSchema'
      responses:
        '204':
          description: This response has no body.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
  /api/admin/projects/{projectId}/change-requests/available-reviewers/{environment}:
    get:
      summary: This Endpoint Will Return Users Available to Review/approve This Change Request
      description: '**Enterprise feature**


        This endpoint will list users available to approve a change request in this project.'
      tags:
      - Change Requests
      operationId: getAvailableChangeRequestReviewers
      responses:
        '200':
          description: changeRequestAvailableReviewersSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeRequestAvailableReviewersSchema'
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: environment
        in: path
        required: true
        schema:
          type: string
  /api/admin/search/change-requests:
    get:
      tags:
      - Change Requests
      summary: Search Change Requests
      description: '**Enterprise feature**


        Search and filter change requests by creator and approver.'
      operationId: searchChangeRequests
      parameters:
      - name: createdBy
        schema:
          type: string
          example: IS:123
        description: Filter by change request creator user ID
        in: query
      - name: requestedApproverId
        schema:
          type: string
          example: IS:456
        description: Filter by requested approver user ID
        in: query
      - name: state
        schema:
          type: string
          enum:
          - IS:open
          - IS:closed
          example: IS:open
        description: Filter by open / closed change requests. Change requests that are in 'draft', 'in review', 'approved', or 'scheduled' states are considered open. Change requests that are in 'cancelled', 'applied', or 'rejected' states are considered closed.
        in: query
      - name: offset
        schema:
          type: integer
          minimum: 0
          example: 50
          default: 0
        description: The number of change requests to skip when returning a page. By default it is set to 0.
        in: query
      - name: limit
        schema:
          type: integer
          minimum: 1
          example: 75
          default: 50
          maximum: 1000
        description: The number of change requests to return in a page. By default it is set to 50. The maximum is 1000.
        in: query
      responses:
        '200':
          description: changeRequestSearchResponseSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/changeRequestSearchResponseSchema'
        '401':
          description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: AuthenticationRequired
                    description: The name of the error kind
                  message:
                    type: string
                    example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
                    description: A description of what went wrong.
        '403':
          description: The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NoAccessError
                    description: The name of the error kind
                  message:
                    type: string
                    example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.
                    description: A description of what went wrong.
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 9c40958a-daac-400e-98fb-3bb438567008
                    description: The ID of the error instance
                  name:
                    type: string
                    example: NotFoundError
                    description: The name of the error kind
                  message:
                    type: string
                    example: Could not find the addon with ID "12345".
                    description: A description of what went wrong.
components:
  schemas:
    createFeatureStrategySchema:
      type: object
      required:
      - name
      description: Create a strategy configuration in a feature
      properties:
        name:
          type: string
          description: The name of the strategy type
          example: flexibleRollout
        title:
          type:
          - string
          - 'null'
          description: A descriptive title for the strategy
          example: Gradual Rollout 25-Prod
        disabled:
          type:
          - boolean
          - 'null'
          description: A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs
          example: false
        sortOrder:
          type: number
          description: The order of the strategy in the list
          example: 9999
        constraints:
          type: array
          description: A list of the constraints attached to the strategy. See https://docs.getunleash.io/concepts/activation-strategies#constraints
          example:
          - values:
            - '1'
            - '2'
            inverted: false
            operator: IN
            contextName: appName
            caseInsensitive: false
          items:
            $ref: '#/components/schemas/constraintSchema'
        variants:
          type: array
          description: Strategy level variants
          items:
            $ref: '#/components/schemas/createStrategyVariantSchema'
        parameters:
          description: An object containing the parameters for the strategy
          example:
            groupId: some_new
            rollout: '25'
            stickiness: sessionId
          $ref: '#/components/schemas/parametersSchema'
        segments:
          type: array
          description: Ids of segments to use for this strategy
          example:
          - 1
          - 2
          items:
            type: number
    safeguardTriggerConditionSchema:
      type: object
      required:
      - operator
      - threshold
      additionalProperties: false
      description: The condition that triggers the safeguard.
      properties:
        operator:
          type: string
          enum:
          - '>'
          - <
          description: The comparison operator for the threshold check.
          example: '>'
        threshold:
          type: number
          description: The threshold value to compare against.
          example: 100
    changeRequestSchema:
      type: object
      description: A [change request](https://docs.getunleash.io/concepts/change-requests)
      oneOf:
      - required:
        - id
        - environment
        - state
        - minApprovals
        - project
        - features
        - segments
        - createdAt
        - createdBy
        - stateTimestamps
        additionalProperties: false
        properties:
          id:
            type: number
            example: 3
            description: This change requests's ID.
          title:
            type: string
            example: Increasing gradual rollout
            description: A title describing the change request's content.
          environment:
            type: string
            example: development
            description: The environment in which the changes should be applied.
          minApprovals:
            type: number
            example: 2
            description: The minimum number of approvals required before this change request can be applied.
          project:
            type: string
            example: unleash-project
            description: The project this change request belongs to.
          features:
            type: array
            description: The list of features and their changes that relate to this change request.
            items:
              $ref: '#/components/schemas/changeRequestFeatureSchema'
          segments:
            type: array
            description: The list of segments and their changes that relate to this change request.
            items:
              $ref: '#/components/schemas/changeRequestSegmentChangeSchema'
          approvals:
            type: array
            description: A list of approvals that this change request has received.
            items:
              $ref: '#/components/schemas/changeRequestApprovalSchema'
          rejections:
            type: array
            description: 'A list of rejections that this change request has received. '
            items:
              $ref: '#/components/schemas/changeRequestApprovalSchema'
          comments:
            type: array
            description: All comments that have been made on this change request.
            items:
              $ref: '#/components/schemas/changeRequestCommentSchema'
          createdBy:
            description: The user who created this change request.
            type: object
            properties:
              username:
                type:
                - string
                - 'null'
                example: Hunter
              imageUrl:
                type:
                - string
                - 'null'
                format: uri
                description: The URL of the user's profile image.
          createdAt:
            description: When this change request was created.
            type: string
            format: date-time
            example: '2023-07-31T13:33:02Z'
          stateTimestamps:
            type: object
            description: A mapping of each state this change request has entered to the most recent time when it entered that state. If a change request has entered the same state multiple times, only the most recent timestamp will be included.
            additionalProperties:
              type: string
              format: date-time
              example: '2023-08-01T10:15:30Z'
            example:
              Draft: '2023-07-31T13:33:02Z'
              In review: '2023-08-01T10:15:30Z'
              Approved: '2023-08-02T09:01:00Z'
          state:
            type: string
            enum:
            - Draft
            - In review
            - Approved
            - Applied
            - Cancelled
            - Rejected
            description: The current state of the change request.
      - required:
        - id
        - environment
        - state
        - minApprovals
        - project
        - features
        - segments
        - createdAt
        - createdBy
        - stateTimestamps
        - schedule
        additionalProperties: false
        properties:
          id:
            type: number
            example: 3
            description: This change requests's ID.
          title:
            type: string
            example: Increasing gradual rollout
            description: A title describing the change request's content.
          environment:
            type: string
            example: development
            description: The environment in which the changes should be applied.
          minApprovals:
            type: number
            example: 2
            description: The minimum number of approvals required before this change request can be applied.
          project:
            type: string
            example: unleash-project
            description: The project this change request belongs to.
          features:
            type: array
            description: The list of features and their changes that relate to this change request.
            items:
              $ref: '#/components/schemas/changeRequestFeatureSchema'
          segments:
            type: array
            description: The list of segments and their changes that relate to this chan

# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unleash/refs/heads/main/openapi/unleash-change-requests-api-openapi.yml