Unleash Change Requests API

openapi: 3.0.3
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:
    updateFeatureStrategySchema:
      type: object
      description: Update a strategy configuration in a feature
      properties:
        name:
          type: string
          description: The name of the strategy type
        sortOrder:
          type: number
          description: The order of the strategy in the list in feature environment configuration
        constraints:
          type: array
          items:
            $ref: '#/components/schemas/constraintSchema'
          description: A list of the constraints attached to the strategy. See https://docs.getunleash.io/concepts/activation-strategies#constraints
        title:
          type: string
          nullable: true
          description: A descriptive title for the strategy
          example: Gradual Rollout 25-Prod
        disabled:
          type: boolean
          description: A toggle to disable the strategy. defaults to true. Disabled strategies are not evaluated or returned to the SDKs
          example: false
          nullable: true
        parameters:
          $ref: '#/components/schemas/parametersSchema'
    constraintSchema:
      additionalProperties: false
      type: object
      required:
      - contextName
      - operator
      description: A strategy constraint. For more information, refer to [the strategy constraint reference documentation](https://docs.getunleash.io/concepts/activation-strategies#constraints)
      properties:
        contextName:
          description: The name of the context field that this constraint should apply to.
          example: appName
          type: string
        operator:
          description: The operator to use when evaluating this constraint. For more information about the various operators, refer to [the strategy constraint operator documentation](https://docs.getunleash.io/concepts/activation-strategies#constraint-operators).
          type: string
          enum:
          - NOT_IN
          - IN
          - STR_ENDS_WITH
          - STR_STARTS_WITH
          - STR_CONTAINS
          - NUM_EQ
          - NUM_GT
          - NUM_GTE
          - NUM_LT
          - NUM_LTE
          - DATE_AFTER
          - DATE_BEFORE
          - SEMVER_EQ
          - SEMVER_GT
          - SEMVER_LT
          example: IN
        caseInsensitive:
          description: Whether the operator should be case sensitive or not. Defaults to `false` (being case sensitive).
          type: boolean
          default: false
        inverted:
          description: Whether the result should be negated or not. If `true`, will turn a `true` result into a `false` result and vice versa.
          type: boolean
          default: false
        values:
          type: array
          description: The context values that should be used for constraint evaluation. Use this property instead of `value` for properties that accept multiple values.
          items:
            type: string
          example:
          - my-app
          - my-other-app
        value:
          description: The context value that should be used for constraint evaluation. Use this property instead of `values` for properties that only accept single values.
          type: string
          example: my-app
    changeRequestConfigSchema:
      type: array
      description: A list of environment-specific [change request](https://docs.getunleash.io/concepts/change-requests) configurations.
      items:
        $ref: '#/components/schemas/changeRequestEnvironmentConfigSchema'
    changeRequestsSchema:
      type: array
      description: A list of change requests
      items:
        type: object
        description: A simplified change request overview
        oneOf:
        - required:
          - id
          - environment
          - state
          - project
          - features
          - segments
          - createdAt
          - createdBy
          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.
              deprecated: true
            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'
              deprecated: true
            rejections:
              type: array
              description: 'A list of rejections that this change request has received. '
              items:
                $ref: '#/components/schemas/changeRequestApprovalSchema'
              deprecated: true
            comments:
              type: array
              description: All comments that have been made on this change request.
              items:
                $ref: '#/components/schemas/changeRequestCommentSchema'
              deprecated: true
            createdBy:
              description: The user who created this change request.
              type: object
              properties:
                username:
                  type: string
                  nullable: true
                  example: Hunter
                imageUrl:
                  type: string
                  format: uri
                  nullable: true
                  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'
            state:
              type: string
              enum:
              - Draft
              - In review
              - Approved
              - Applied
              - Cancelled
              - Rejected
              description: The current state of the change request.
        - required:
          - id
          - environment
          - state
          - project
          - features
          - segments
          - createdAt
          - createdBy
          - 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

# --- 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