Environments

Environments allow you to maintain separate rollout rules in different contexts, from local development to QA, staging, and production. With the LaunchDarkly Environments API, you can programmatically create, delete, and update environments. To learn more, read Environments.

List environments

Return a list of environments for the specified project.

By default, this returns the first 20 environments. Page through this list with the limit parameter and by following the first, prev, next, and last links in the _links field that returns. If those links do not appear, the pages they refer to don't exist. For example, the first and prev links will be missing from the response on the first page, because there is no previous page and you cannot return to the first page when you are already on the first page.

Filtering environments

LaunchDarkly supports two fields for filters:

  • query is a string that matches against the environments' names and keys. It is not case sensitive.
  • tags is a + separate list of environment tags. It filters the list of environments that have all of the tags in the list.

For example, the filter query:abc,tags:tag-1+tag-2 matches environments with the string abc in their name or key and also are tagged with tag-1 and tag-2. The filter is not case-sensitive.

Sorting environments

LaunchDarkly supports two fields for sorting:

  • name sorts by environment name.
  • createdOn sorts by the creation date of the environment.

For example, sort=name sorts the response by environment name in ascending order.

Request
path Parameters
projectKey
required
string <string>

The project key

query Parameters
limit
integer <int64>

The number of environments to return in the response. Defaults to 20.

offset
integer <int64>

Where to start in the list. This is for use 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.

filter
string <string>

A comma-separated list of filters. Each filter is of the form field:value.

sort
string <string>

A comma-separated list of fields to sort by. Fields prefixed by a dash ( - ) sort in descending order.

Responses
200

Environments collection response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

405

Method not allowed

429

Rate limited

get/api/v2/projects/{projectKey}/environments
Request samples
Response samples
application/json
{
  • "_links": {
    },
  • "totalCount": 2,
  • "items": [
    ]
}

Create environment

Approval settings

The approvalSettings key is only returned when the Flag Approvals feature is enabled.

You cannot update approval settings when creating new environments. Update approval settings with the PATCH Environment API.

Create a new environment in a specified project with a given name, key, swatch color, and default TTL.

Request
path Parameters
projectKey
required
string <string>

The project key

Request Body schema: application/json
name
required
string

A human-friendly name for the new environment.

key
required
string

A project-unique key for the new environment.

color
required
string

A color to indicate this environment in the UI.

defaultTtl
integer

The default time (in minutes) that the PHP SDK can cache feature flag rules locally.

secureMode
boolean

Ensures that a user of the client-side SDK cannot impersonate another user.

defaultTrackEvents
boolean

Enables tracking detailed information for new flags by default.

confirmChanges
boolean

Requires confirmation for all flag and segment changes via the UI in this environment.

requireComments
boolean

Requires comments for all flag and segment changes via the UI in this environment.

tags
Array of strings

Tags to apply to the new environment.

object (SourceEnv)
Responses
201

Environment response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

409

Status conflict

429

Rate limited

post/api/v2/projects/{projectKey}/environments
Request samples
application/json
{
  • "color": "DADBEE",
  • "key": "my-environment",
  • "name": "My Environment"
}
Response samples
application/json
{
  • "_links": {
    },
  • "_id": "57be1db38b75bf0772d11384",
  • "key": "my-environment",
  • "name": "My Environment",
  • "apiKey": "XYZ",
  • "mobileKey": "XYZ",
  • "color": "F5A623",
  • "defaultTtl": 5,
  • "secureMode": true,
  • "defaultTrackEvents": false,
  • "requireComments": true,
  • "confirmChanges": true,
  • "tags": [
    ],
  • "approvalSettings": {
    }
}

Get environment

Approval settings

The approvalSettings key is only returned when the Flag Approvals feature is enabled.

Get an environment given a project and key.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

Responses
200

Environment response

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

get/api/v2/projects/{projectKey}/environments/{environmentKey}
Request samples
Response samples
application/json
{
  • "_links": {
    },
  • "_id": "57be1db38b75bf0772d11384",
  • "key": "my-environment",
  • "name": "My Environment",
  • "apiKey": "XYZ",
  • "mobileKey": "XYZ",
  • "color": "F5A623",
  • "defaultTtl": 5,
  • "secureMode": true,
  • "defaultTrackEvents": false,
  • "requireComments": true,
  • "confirmChanges": true,
  • "tags": [
    ],
  • "approvalSettings": {
    }
}

Update environment

Update an environment. Requires a JSON Patch representation of the desired changes to the environment.

To update fields in the environment object that are arrays, set the path to the name of the field and then append /<array index>. Using /0 appends to the beginning of the array.

Approval settings

This request only returns the approvalSettings key if the Flag Approvals feature is enabled.

Only the canReviewOwnRequest, canApplyDeclinedChanges, minNumApprovals, required and requiredApprovalTagsfields are editable.

If you try to patch the environment by setting both required and requiredApprovalTags, the request fails and an error appears. You can specify either required approvals for all flags in an environment or those with specific tags, but not both.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

Request Body schema: application/json
Array
op
required
string

The type of operation to perform

path
required
string

A JSON Pointer string specifying the part of the document to operate on

value
required
any

A JSON value used in "add", "replace", and "test" operations

Responses
200

Environment response

400

Invalid request

401

Invalid access token

404

Invalid resource identifier

409

Status conflict

429

Rate limited

patch/api/v2/projects/{projectKey}/environments/{environmentKey}
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
{
  • "_links": {
    },
  • "_id": "57be1db38b75bf0772d11384",
  • "key": "my-environment",
  • "name": "My Environment",
  • "apiKey": "XYZ",
  • "mobileKey": "XYZ",
  • "color": "F5A623",
  • "defaultTtl": 5,
  • "secureMode": true,
  • "defaultTrackEvents": false,
  • "requireComments": true,
  • "confirmChanges": true,
  • "tags": [
    ],
  • "approvalSettings": {
    }
}

Delete environment

Delete a environment by key.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

Responses
204

Action succeeded

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

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

Reset environment SDK key

Reset an environment's SDK key with an optional expiry time for the old key.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

query Parameters
expiry
integer <int64>

The time at which you want the old SDK key to expire, in UNIX milliseconds. By default, the key expires immediately.

Responses
200

Environment response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

post/api/v2/projects/{projectKey}/environments/{environmentKey}/apiKey
Request samples
Response samples
application/json
{
  • "_links": {
    },
  • "_id": "57be1db38b75bf0772d11384",
  • "key": "my-environment",
  • "name": "My Environment",
  • "apiKey": "XYZ",
  • "mobileKey": "XYZ",
  • "color": "F5A623",
  • "defaultTtl": 5,
  • "secureMode": true,
  • "defaultTrackEvents": false,
  • "requireComments": true,
  • "confirmChanges": true,
  • "tags": [
    ],
  • "approvalSettings": {
    }
}

Reset environment mobile SDK key

Reset an environment's mobile key. The optional expiry for the old key is deprecated for this endpoint, so the old key will always expire immediately.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

Responses
200

Environment response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

429

Rate limited

post/api/v2/projects/{projectKey}/environments/{environmentKey}/mobileKey
Request samples
Response samples
application/json
{
  • "_links": {
    },
  • "_id": "57be1db38b75bf0772d11384",
  • "key": "my-environment",
  • "name": "My Environment",
  • "apiKey": "XYZ",
  • "mobileKey": "XYZ",
  • "color": "F5A623",
  • "defaultTtl": 5,
  • "secureMode": true,
  • "defaultTrackEvents": false,
  • "requireComments": true,
  • "confirmChanges": true,
  • "tags": [
    ],
  • "approvalSettings": {
    }
}