Approvals

You can create an approval request that prevents a flag change from being applied without approval from a team member. Select up to ten members as reviewers. Reviewers receive an email notification, but anyone with sufficient permissions can review a pending approval request. A change needs at least one approval before you can apply it. To learn more, read Approvals.

Changes that conflict will fail if approved and applied, and the flag will not be updated.

Several of the endpoints in the approvals API require a flag approval request ID. The flag approval request ID is returned as part of the Create approval request and List approval requests for a flag responses. It is the _id field, or the _id field of each element in the items array. If you created the approval request as part of a workflow, you can also use a workflow ID as the approval request ID. The workflow ID is returned as part of the Create workflow and Get workflows responses. It is the _id field, or the _id field of each element in the items array.

List approval requests

Get all approval requests.

Filtering approvals

LaunchDarkly supports the filter query param for filtering, with the following fields:

  • notifyMemberIds filters for only approvals that are assigned to a member in the specified list. For example: filter=notifyMemberIds anyOf ["memberId1", "memberId2"].
  • requestorId filters for only approvals that correspond to the ID of the member who requested the approval. For example: filter=requestorId equals 457034721476302714390214.
  • resourceId filters for only approvals that correspond to the the specified resource identifier. For example: filter=resourceId equals proj/my-project:env/my-environment:flag/my-flag.
  • reviewStatus filters for only approvals which correspond to the review status in the specified list. The possible values are approved, declined, and pending. For example: filter=reviewStatus anyOf ["pending", "approved"].
  • status filters for only approvals which correspond to the status in the specified list. The possible values are pending, scheduled, failed, and completed. For example: filter=status anyOf ["pending", "scheduled"].

You can also apply multiple filters at once. For example, setting filter=projectKey equals my-project, reviewStatus anyOf ["pending","approved"] matches approval requests which correspond to the my-project project key, and a review status of either pending or approved.

Expanding approval response

LaunchDarkly supports the expand query param to include additional fields in the response, with the following fields:

  • flag includes the flag the approval request belongs to
  • project includes the project the approval request belongs to
  • environments includes the environments the approval request relates to

For example, expand=project,flag includes the project and flag fields in the response.

Request
query Parameters
filter
string <string>

A comma-separated list of filters. Each filter is of the form field operator value. Supported fields are explained above.

expand
string <string>

A comma-separated list of fields to expand in the response. Supported fields are explained above.

limit
integer <int64>

The number of approvals to return. Defaults to 20. Maximum limit is 200.

offset
integer <int64>

Where to start in the list. Use this with pagination. For example, an offset of 10 skips the first ten items and then returns the next items in the list, up to the query limit.

Responses
200

Approval request collection response

400

Unsupported filter field. Filter field must be one of: requestorId, projectKey, notifyMemberIds, reviewStatus, or status

401

Invalid access token

403

Forbidden

429

Rate limited

get/api/v2/approval-requests
Request samples
Response samples
application/json
{
  • "items": [
    ],
  • "totalCount": 1,
  • "_links": {
    }
}

Create approval request

Create an approval request.

This endpoint currently supports creating an approval request for a flag across all environments with the following instructions:

  • addVariation
  • removeVariation
  • updateVariation
  • updateDefaultVariation

For details on using these instructions, read Update feature flag.

To create an approval for a flag specific to an environment, use Create approval request for a flag.

Request
Request Body schema: application/json
required
resourceId
required
string

String representation of the resource specifier

comment
string

Optional comment describing the approval request

description
required
string

A brief description of the changes you're requesting

required
Array of objects (Instructions)
notifyMemberIds
Array of strings

An array of member IDs. These members are notified to review the approval request.

notifyTeamKeys
Array of strings

An array of team keys. The members of these teams are notified to review the approval request.

object (FormVariableConfig)
Responses
201

Approval request response

400

Invalid request

401

Invalid access token

403

Forbidden

429

Rate limited

post/api/v2/approval-requests
Request samples
application/json
{
  • "resourceId": "proj/projKey:env/envKey:flag/flagKey",
  • "comment": "optional comment",
  • "description": "Requesting to update targeting",
  • "instructions": [
    ],
  • "notifyMemberIds": [
    ],
  • "notifyTeamKeys": [
    ],
  • "integrationConfig": {
    }
}
Response samples
application/json
{
  • "_id": "12ab3c45de678910abc12345",
  • "_version": 1,
  • "creationDate": 0,
  • "serviceKind": "string",
  • "requestorId": "12ab3c45de678910abc12345",
  • "description": "example: request approval from someone",
  • "reviewStatus": "pending",
  • "allReviews": [
    ],
  • "notifyMemberIds": [
    ],
  • "appliedDate": 0,
  • "appliedByMemberId": "1234a56b7c89d012345e678f",
  • "appliedByServiceTokenId": "1234a56b7c89d012345e678f",
  • "status": "pending",
  • "instructions": [
    ],
  • "conflicts": [
    ],
  • "_links": {
    },
  • "executionDate": 0,
  • "operatingOnId": "12ab3c45de678910abc12345",
  • "integrationMetadata": {
    },
  • "source": {
    },
  • "customWorkflowMetadata": {
    },
  • "resourceId": "string",
  • "approvalSettings": {
    }
}

Get approval request

Get an approval request by approval request ID.

Expanding approval response

LaunchDarkly supports the expand query param to include additional fields in the response, with the following fields:

  • flag includes the flag the approval request belongs to
  • project includes the project the approval request belongs to
  • environments includes the environments the approval request relates to

For example, expand=project,flag includes the project and flag fields in the response.

Request
path Parameters
id
required
string <string>

The approval request ID

query Parameters
expand
string <string>

A comma-separated list of fields to expand in the response. Supported fields are explained above.

Responses
200

Approval request response

400

Invalid Request

401

Invalid access token

403

Forbidden

404

Unable to find approval request

429

Rate limited

get/api/v2/approval-requests/{id}
Request samples
Response samples
application/json
{
  • "_id": "12ab3c45de678910abc12345",
  • "_version": 1,
  • "creationDate": 0,
  • "serviceKind": "string",
  • "requestorId": "12ab3c45de678910abc12345",
  • "description": "example: request approval from someone",
  • "reviewStatus": "pending",
  • "allReviews": [
    ],
  • "notifyMemberIds": [
    ],
  • "appliedDate": 0,
  • "appliedByMemberId": "1234a56b7c89d012345e678f",
  • "appliedByServiceTokenId": "1234a56b7c89d012345e678f",
  • "status": "pending",
  • "instructions": [
    ],
  • "conflicts": [
    ],
  • "_links": {
    },
  • "executionDate": 0,
  • "operatingOnId": "12ab3c45de678910abc12345",
  • "integrationMetadata": {
    },
  • "source": {
    },
  • "customWorkflowMetadata": {
    },
  • "resourceId": "string",
  • "approvalSettings": {
    },
  • "project": {
    },
  • "environments": [
    ],
  • "flag": {
    }
}

Delete approval request

Delete an approval request.

Request
path Parameters
id
required
string <string>

The approval request ID

Responses
204

Action succeeded

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

delete/api/v2/approval-requests/{id}
Request samples
Response samples
application/json
{
  • "code": "unauthorized",
  • "message": "Invalid access token"
}

Apply approval request

Apply an approval request that has been approved.

Request
path Parameters
id
required
string <string>

The feature flag approval request ID

Request Body schema: application/json
required
comment
string

Optional comment about the approval request

Responses
200

Approval request apply response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

post/api/v2/approval-requests/{id}/apply
Request samples
application/json
{
  • "comment": "Looks good, thanks for updating"
}
Response samples
application/json
{
  • "_id": "12ab3c45de678910abc12345",
  • "_version": 1,
  • "creationDate": 0,
  • "serviceKind": "string",
  • "requestorId": "12ab3c45de678910abc12345",
  • "description": "example: request approval from someone",
  • "reviewStatus": "pending",
  • "allReviews": [
    ],
  • "notifyMemberIds": [
    ],
  • "appliedDate": 0,
  • "appliedByMemberId": "1234a56b7c89d012345e678f",
  • "appliedByServiceTokenId": "1234a56b7c89d012345e678f",
  • "status": "pending",
  • "instructions": [
    ],
  • "conflicts": [
    ],
  • "_links": {
    },
  • "executionDate": 0,
  • "operatingOnId": "12ab3c45de678910abc12345",
  • "integrationMetadata": {
    },
  • "source": {
    },
  • "customWorkflowMetadata": {
    },
  • "resourceId": "string",
  • "approvalSettings": {
    }
}

Review approval request

Review an approval request by approving or denying changes.

Request
path Parameters
id
required
string <string>

The approval request ID

Request Body schema: application/json
required
kind
string

The type of review for this approval request

Enum: "approve" "comment" "decline"
comment
string

Optional comment about the approval request

Responses
200

Approval request review response

400

Invalid request

401

Invalid access token

404

Invalid resource identifier

405

Method not allowed

409

Status conflict

429

Rate limited

post/api/v2/approval-requests/{id}/reviews
Request samples
application/json
{
  • "kind": "approve",
  • "comment": "Looks good, thanks for updating"
}
Response samples
application/json
{
  • "_id": "12ab3c45de678910abc12345",
  • "_version": 1,
  • "creationDate": 0,
  • "serviceKind": "string",
  • "requestorId": "12ab3c45de678910abc12345",
  • "description": "example: request approval from someone",
  • "reviewStatus": "pending",
  • "allReviews": [
    ],
  • "notifyMemberIds": [
    ],
  • "appliedDate": 0,
  • "appliedByMemberId": "1234a56b7c89d012345e678f",
  • "appliedByServiceTokenId": "1234a56b7c89d012345e678f",
  • "status": "pending",
  • "instructions": [
    ],
  • "conflicts": [
    ],
  • "_links": {
    },
  • "executionDate": 0,
  • "operatingOnId": "12ab3c45de678910abc12345",
  • "integrationMetadata": {
    },
  • "source": {
    },
  • "customWorkflowMetadata": {
    },
  • "resourceId": "string",
  • "approvalSettings": {
    }
}

List approval requests for a flag

Get all approval requests for a feature flag.

Request
path Parameters
projectKey
required
string <string>

The project key

featureFlagKey
required
string <string>

The feature flag key

environmentKey
required
string <string>

The environment key

Responses
200

Approval request collection response

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

get/api/v2/projects/{projectKey}/flags/{featureFlagKey}/environments/{environmentKey}/approval-requests
Request samples
Response samples
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

Create approval request for a flag

Create an approval request for a feature flag.

Request
path Parameters
projectKey
required
string <string>

The project key

featureFlagKey
required
string <string>

The feature flag key

environmentKey
required
string <string>

The environment key

Request Body schema: application/json
required
comment
string

Optional comment describing the approval request

description
required
string

A brief description of the changes you're requesting

required
Array of objects (Instructions)
notifyMemberIds
Array of strings

An array of member IDs. These members are notified to review the approval request.

notifyTeamKeys
Array of strings

An array of team keys. The members of these teams are notified to review the approval request.

executionDate
integer <int64> (UnixMillis)
operatingOnId
string

The ID of a scheduled change. Include this if your instructions include editing or deleting a scheduled change.

object (FormVariableConfig)
Responses
201

Approval request response

400

Invalid request

401

Invalid access token

403

Forbidden

429

Rate limited

post/api/v2/projects/{projectKey}/flags/{featureFlagKey}/environments/{environmentKey}/approval-requests
Request samples
application/json
{
  • "comment": "optional comment",
  • "description": "Requesting to update targeting",
  • "instructions": [
    ],
  • "notifyMemberIds": [
    ],
  • "notifyTeamKeys": [
    ],
  • "executionDate": 0,
  • "operatingOnId": "6297ed79dee7dc14e1f9a80c",
  • "integrationConfig": {
    }
}
Response samples
application/json
{
  • "_id": "12ab3c45de678910abc12345",
  • "_version": 1,
  • "creationDate": 0,
  • "serviceKind": "string",
  • "requestorId": "12ab3c45de678910abc12345",
  • "description": "example: request approval from someone",
  • "reviewStatus": "pending",
  • "allReviews": [
    ],
  • "notifyMemberIds": [
    ],
  • "appliedDate": 0,
  • "appliedByMemberId": "1234a56b7c89d012345e678f",
  • "appliedByServiceTokenId": "1234a56b7c89d012345e678f",
  • "status": "pending",
  • "instructions": [
    ],
  • "conflicts": [
    ],
  • "_links": {
    },
  • "executionDate": 0,
  • "operatingOnId": "12ab3c45de678910abc12345",
  • "integrationMetadata": {
    },
  • "source": {
    },
  • "customWorkflowMetadata": {
    }
}

Create approval request to copy flag configurations across environments

Create an approval request to copy a feature flag's configuration across environments.

Request
path Parameters
projectKey
required
string <string>

The project key

featureFlagKey
required
string <string>

The feature flag key

environmentKey
required
string <string>

The environment key for the target environment

Request Body schema: application/json
required
comment
string

Optional comment describing the approval request

description
required
string

A brief description of your changes

notifyMemberIds
Array of strings

An array of member IDs. These members are notified to review the approval request.

notifyTeamKeys
Array of strings

An array of team keys. The members of these teams are notified to review the approval request.

required
object (sourceFlag)
includedActions
Array of strings

Optional list of the flag changes to copy from the source environment to the target environment. You may include either includedActions or excludedActions, but not both. If neither are included, then all flag changes will be copied.

Items Enum: "updateOn" "updateFallthrough" "updateOffVariation" "updateRules" "updateTargets" "updatePrerequisites"
excludedActions
Array of strings

Optional list of the flag changes NOT to copy from the source environment to the target environment. You may include either includedActions or excludedActions, but not both. If neither are included, then all flag changes will be copied.

Items Enum: "updateOn" "updateFallthrough" "updateOffVariation" "updateRules" "updateTargets" "updatePrerequisites"
Responses
201

Approval request response

400

Invalid request

401

Invalid access token

403

Forbidden

409

Status conflict

429

Rate limited

post/api/v2/projects/{projectKey}/flags/{featureFlagKey}/environments/{environmentKey}/approval-requests-flag-copy
Request samples
application/json
{
  • "comment": "optional comment",
  • "description": "copy flag settings to another environment",
  • "notifyMemberIds": [
    ],
  • "notifyTeamKeys": [
    ],
  • "source": {
    },
  • "includedActions": [
    ],
  • "excludedActions": [
    ]
}
Response samples
application/json
{
  • "_id": "12ab3c45de678910abc12345",
  • "_version": 1,
  • "creationDate": 0,
  • "serviceKind": "string",
  • "requestorId": "12ab3c45de678910abc12345",
  • "description": "example: request approval from someone",
  • "reviewStatus": "pending",
  • "allReviews": [
    ],
  • "notifyMemberIds": [
    ],
  • "appliedDate": 0,
  • "appliedByMemberId": "1234a56b7c89d012345e678f",
  • "appliedByServiceTokenId": "1234a56b7c89d012345e678f",
  • "status": "pending",
  • "instructions": [
    ],
  • "conflicts": [
    ],
  • "_links": {
    },
  • "executionDate": 0,
  • "operatingOnId": "12ab3c45de678910abc12345",
  • "integrationMetadata": {
    },
  • "source": {
    },
  • "customWorkflowMetadata": {
    }
}

Get approval request for a flag

Get a single approval request for a feature flag.

Request
path Parameters
projectKey
required
string <string>

The project key

featureFlagKey
required
string <string>

The feature flag key

environmentKey
required
string <string>

The environment key

id
required
string <string>

The feature flag approval request ID

Responses
200

Approval request response

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

get/api/v2/projects/{projectKey}/flags/{featureFlagKey}/environments/{environmentKey}/approval-requests/{id}
Request samples
Response samples
application/json
{
  • "_id": "12ab3c45de678910abc12345",
  • "_version": 1,
  • "creationDate": 0,
  • "serviceKind": "string",
  • "requestorId": "12ab3c45de678910abc12345",
  • "description": "example: request approval from someone",
  • "reviewStatus": "pending",
  • "allReviews": [
    ],
  • "notifyMemberIds": [
    ],
  • "appliedDate": 0,
  • "appliedByMemberId": "1234a56b7c89d012345e678f",
  • "appliedByServiceTokenId": "1234a56b7c89d012345e678f",
  • "status": "pending",
  • "instructions": [
    ],
  • "conflicts": [
    ],
  • "_links": {
    },
  • "executionDate": 0,
  • "operatingOnId": "12ab3c45de678910abc12345",
  • "integrationMetadata": {
    },
  • "source": {
    },
  • "customWorkflowMetadata": {
    }
}

Delete approval request for a flag

Delete an approval request for a feature flag.

Request
path Parameters
projectKey
required
string <string>

The project key

featureFlagKey
required
string <string>

The feature flag key

environmentKey
required
string <string>

The environment key

id
required
string <string>

The feature flag approval request ID

Responses
204

Action succeeded

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

delete/api/v2/projects/{projectKey}/flags/{featureFlagKey}/environments/{environmentKey}/approval-requests/{id}
Request samples
Response samples
application/json
{
  • "code": "unauthorized",
  • "message": "Invalid access token"
}

Apply approval request for a flag

Apply an approval request that has been approved.

Request
path Parameters
projectKey
required
string <string>

The project key

featureFlagKey
required
string <string>

The feature flag key

environmentKey
required
string <string>

The environment key

id
required
string <string>

The feature flag approval request ID

Request Body schema: application/json
required
comment
string

Optional comment about the approval request

Responses
200

Approval request apply response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

post/api/v2/projects/{projectKey}/flags/{featureFlagKey}/environments/{environmentKey}/approval-requests/{id}/apply
Request samples
application/json
{
  • "comment": "Looks good, thanks for updating"
}
Response samples
application/json
{
  • "_id": "12ab3c45de678910abc12345",
  • "_version": 1,
  • "creationDate": 0,
  • "serviceKind": "string",
  • "requestorId": "12ab3c45de678910abc12345",
  • "description": "example: request approval from someone",
  • "reviewStatus": "pending",
  • "allReviews": [
    ],
  • "notifyMemberIds": [
    ],
  • "appliedDate": 0,
  • "appliedByMemberId": "1234a56b7c89d012345e678f",
  • "appliedByServiceTokenId": "1234a56b7c89d012345e678f",
  • "status": "pending",
  • "instructions": [
    ],
  • "conflicts": [
    ],
  • "_links": {
    },
  • "executionDate": 0,
  • "operatingOnId": "12ab3c45de678910abc12345",
  • "integrationMetadata": {
    },
  • "source": {
    },
  • "customWorkflowMetadata": {
    }
}

Review approval request for a flag

Review an approval request by approving or denying changes.

Request
path Parameters
projectKey
required
string <string>

The project key

featureFlagKey
required
string <string>

The feature flag key

environmentKey
required
string <string>

The environment key

id
required
string <string>

The feature flag approval request ID

Request Body schema: application/json
required
kind
string

The type of review for this approval request

Enum: "approve" "comment" "decline"
comment
string

Optional comment about the approval request

Responses
200

Approval request review response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

post/api/v2/projects/{projectKey}/flags/{featureFlagKey}/environments/{environmentKey}/approval-requests/{id}/reviews
Request samples
application/json
{
  • "kind": "approve",
  • "comment": "Looks good, thanks for updating"
}
Response samples
application/json
{
  • "_id": "12ab3c45de678910abc12345",
  • "_version": 1,
  • "creationDate": 0,
  • "serviceKind": "string",
  • "requestorId": "12ab3c45de678910abc12345",
  • "description": "example: request approval from someone",
  • "reviewStatus": "pending",
  • "allReviews": [
    ],
  • "notifyMemberIds": [
    ],
  • "appliedDate": 0,
  • "appliedByMemberId": "1234a56b7c89d012345e678f",
  • "appliedByServiceTokenId": "1234a56b7c89d012345e678f",
  • "status": "pending",
  • "instructions": [
    ],
  • "conflicts": [
    ],
  • "_links": {
    },
  • "executionDate": 0,
  • "operatingOnId": "12ab3c45de678910abc12345",
  • "integrationMetadata": {
    },
  • "source": {
    },
  • "customWorkflowMetadata": {
    }
}