Language

English Français 日本語 한국어 Español

Datadog Site

Site help
US1 US3 US5 EU AP1 AP2 US1-FED

Feature Flags

Manage feature flags and environments.

Delete an environment

DELETE https://api.ap1.datadoghq.com/api/v2/feature-flags/environments/{environment_id}https://api.ap2.datadoghq.com/api/v2/feature-flags/environments/{environment_id}https://api.datadoghq.eu/api/v2/feature-flags/environments/{environment_id}https://api.ddog-gov.com/api/v2/feature-flags/environments/{environment_id}https://api.datadoghq.com/api/v2/feature-flags/environments/{environment_id}https://api.us3.datadoghq.com/api/v2/feature-flags/environments/{environment_id}https://api.us5.datadoghq.com/api/v2/feature-flags/environments/{environment_id}

Overview

Deletes an environment. This operation cannot be undone. This endpoint requires the feature_flag_environment_config_write permission.

Arguments

Path Parameters

Name

Type

Description

environment_id [required]

string

The ID of the environment.

Response

No Content

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export environment_id="550e8400-e29b-41d4-a716-446655440001"
# Curl command
curl -X DELETE "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/environments/${environment_id}" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

Update an environment

PUT https://api.ap1.datadoghq.com/api/v2/feature-flags/environments/{environment_id}https://api.ap2.datadoghq.com/api/v2/feature-flags/environments/{environment_id}https://api.datadoghq.eu/api/v2/feature-flags/environments/{environment_id}https://api.ddog-gov.com/api/v2/feature-flags/environments/{environment_id}https://api.datadoghq.com/api/v2/feature-flags/environments/{environment_id}https://api.us3.datadoghq.com/api/v2/feature-flags/environments/{environment_id}https://api.us5.datadoghq.com/api/v2/feature-flags/environments/{environment_id}

Overview

Updates an existing environment’s metadata such as name and description. This endpoint requires the feature_flag_environment_config_write permission.

Arguments

Path Parameters

Name

Type

Description

environment_id [required]

string

The ID of the environment.

Request

Body Data (required)

Expand All

Field

Type

Description

data [required]

object

Data for updating an environment.

attributes [required]

object

Attributes for updating an environment.

is_production

boolean

Indicates whether this is a production environment.

name

string

The name of the environment.

queries

[string]

List of queries to define the environment scope.

require_feature_flag_approval

boolean

Indicates whether feature flag changes require approval in this environment.

type [required]

enum

The resource type. Allowed enum values: environments

{
  "data": {
    "attributes": {
      "is_production": false,
      "name": "Environment XYZ789",
      "queries": [
        "staging",
        "test"
      ],
      "require_feature_flag_approval": true
    },
    "type": "environments"
  }
}

Response

OK

Response containing an environment.

Expand All

Field

Type

Description

data [required]

object

A feature flag environment resource.

attributes [required]

object

Attributes of an environment.

created_at

date-time

The timestamp when the environment was created.

description

string

The description of the environment.

is_production

boolean

Indicates whether this is a production environment.

key

string

The unique key of the environment.

name [required]

string

The name of the environment.

queries

[string]

List of queries to define the environment scope.

require_feature_flag_approval

boolean

Indicates whether feature flag changes require approval in this environment.

updated_at

date-time

The timestamp when the environment was last updated.

id [required]

uuid

The unique identifier of the environment.

type [required]

enum

The resource type. Allowed enum values: environments

{
  "data": {
    "attributes": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "Test environment XYZ789",
      "is_production": false,
      "key": "env-search-term",
      "name": "env-search-term",
      "queries": [
        "staging",
        "test"
      ],
      "require_feature_flag_approval": false,
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "type": "environments"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export environment_id="550e8400-e29b-41d4-a716-446655440001"
# Curl command
curl -X PUT "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/environments/${environment_id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": {
    "attributes": {},
    "type": "environments"
  }
}
EOF

Get an environment

GET https://api.ap1.datadoghq.com/api/v2/feature-flags/environments/{environment_id}https://api.ap2.datadoghq.com/api/v2/feature-flags/environments/{environment_id}https://api.datadoghq.eu/api/v2/feature-flags/environments/{environment_id}https://api.ddog-gov.com/api/v2/feature-flags/environments/{environment_id}https://api.datadoghq.com/api/v2/feature-flags/environments/{environment_id}https://api.us3.datadoghq.com/api/v2/feature-flags/environments/{environment_id}https://api.us5.datadoghq.com/api/v2/feature-flags/environments/{environment_id}

Overview

Returns the details of a specific environment. This endpoint requires the feature_flag_environment_config_read permission.

Arguments

Path Parameters

Name

Type

Description

environment_id [required]

string

The ID of the environment.

Response

OK

Response containing an environment.

Expand All

Field

Type

Description

data [required]

object

A feature flag environment resource.

attributes [required]

object

Attributes of an environment.

created_at

date-time

The timestamp when the environment was created.

description

string

The description of the environment.

is_production

boolean

Indicates whether this is a production environment.

key

string

The unique key of the environment.

name [required]

string

The name of the environment.

queries

[string]

List of queries to define the environment scope.

require_feature_flag_approval

boolean

Indicates whether feature flag changes require approval in this environment.

updated_at

date-time

The timestamp when the environment was last updated.

id [required]

uuid

The unique identifier of the environment.

type [required]

enum

The resource type. Allowed enum values: environments

{
  "data": {
    "attributes": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "Test environment XYZ789",
      "is_production": false,
      "key": "env-search-term",
      "name": "env-search-term",
      "queries": [
        "staging",
        "test"
      ],
      "require_feature_flag_approval": false,
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "type": "environments"
  }
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export environment_id="550e8400-e29b-41d4-a716-446655440001"
# Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/environments/${environment_id}" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

Create an environment

POST https://api.ap1.datadoghq.com/api/v2/feature-flags/environmentshttps://api.ap2.datadoghq.com/api/v2/feature-flags/environmentshttps://api.datadoghq.eu/api/v2/feature-flags/environmentshttps://api.ddog-gov.com/api/v2/feature-flags/environmentshttps://api.datadoghq.com/api/v2/feature-flags/environmentshttps://api.us3.datadoghq.com/api/v2/feature-flags/environmentshttps://api.us5.datadoghq.com/api/v2/feature-flags/environments

Overview

Creates a new environment for organizing feature flags. This endpoint requires the feature_flag_environment_config_write permission.

Request

Body Data (required)

Expand All

Field

Type

Description

data [required]

object

Data for creating a new environment.

attributes [required]

object

Attributes for creating a new environment.

is_production

boolean

Indicates whether this is a production environment.

name [required]

string

The name of the environment.

queries [required]

[string]

List of queries to define the environment scope.

require_feature_flag_approval

boolean

Indicates whether feature flag changes require approval in this environment.

type [required]

enum

The resource type. Allowed enum values: environments

{
  "data": {
    "type": "environments",
    "attributes": {
      "name": "Test Environment Example-Feature-Flag",
      "queries": [
        "test-Example-Feature-Flag",
        "env-Example-Feature-Flag"
      ]
    }
  }
}

Response

Created

Response containing an environment.

Expand All

Field

Type

Description

data [required]

object

A feature flag environment resource.

attributes [required]

object

Attributes of an environment.

created_at

date-time

The timestamp when the environment was created.

description

string

The description of the environment.

is_production

boolean

Indicates whether this is a production environment.

key

string

The unique key of the environment.

name [required]

string

The name of the environment.

queries

[string]

List of queries to define the environment scope.

require_feature_flag_approval

boolean

Indicates whether feature flag changes require approval in this environment.

updated_at

date-time

The timestamp when the environment was last updated.

id [required]

uuid

The unique identifier of the environment.

type [required]

enum

The resource type. Allowed enum values: environments

{
  "data": {
    "attributes": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "Test environment XYZ789",
      "is_production": false,
      "key": "env-search-term",
      "name": "env-search-term",
      "queries": [
        "staging",
        "test"
      ],
      "require_feature_flag_approval": false,
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "type": "environments"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Conflict

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                          # Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/environments" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": {
    "type": "environments",
    "attributes": {
      "name": "Test Environment Example-Feature-Flag",
      "queries": [
        "test-Example-Feature-Flag",
        "env-Example-Feature-Flag"
      ]
    }
  }
}
EOF

List environments

GET https://api.ap1.datadoghq.com/api/v2/feature-flags/environmentshttps://api.ap2.datadoghq.com/api/v2/feature-flags/environmentshttps://api.datadoghq.eu/api/v2/feature-flags/environmentshttps://api.ddog-gov.com/api/v2/feature-flags/environmentshttps://api.datadoghq.com/api/v2/feature-flags/environmentshttps://api.us3.datadoghq.com/api/v2/feature-flags/environmentshttps://api.us5.datadoghq.com/api/v2/feature-flags/environments

Overview

Returns a list of environments for the organization. Supports filtering by name and key. This endpoint requires the feature_flag_environment_config_read permission.

Arguments

Query Strings

Name

Type

Description

name

string

Filter environments by name (partial matching).

key

string

Filter environments by key (partial matching).

limit

integer

Maximum number of results to return.

offset

integer

Number of results to skip.

Response

OK

Response containing a list of environments.

Expand All

Field

Type

Description

data [required]

[object]

List of environments.

attributes [required]

object

Attributes of an environment.

created_at

date-time

The timestamp when the environment was created.

description

string

The description of the environment.

is_production

boolean

Indicates whether this is a production environment.

key

string

The unique key of the environment.

name [required]

string

The name of the environment.

queries

[string]

List of queries to define the environment scope.

require_feature_flag_approval

boolean

Indicates whether feature flag changes require approval in this environment.

updated_at

date-time

The timestamp when the environment was last updated.

id [required]

uuid

The unique identifier of the environment.

type [required]

enum

The resource type. Allowed enum values: environments

meta

object

Pagination metadata for environments.

page

object

Pagination metadata for environments list responses.

total_count

int64

Total number of items.

total_filtered_count

int64

Total number of items matching the filter.

{
  "data": [
    {
      "attributes": {
        "created_at": "2023-01-01T00:00:00Z",
        "description": "Test environment XYZ789",
        "is_production": false,
        "key": "env-search-term",
        "name": "env-search-term",
        "queries": [
          "staging",
          "test"
        ],
        "require_feature_flag_approval": false,
        "updated_at": "2023-01-01T00:00:00Z"
      },
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "type": "environments"
    }
  ],
  "meta": {
    "page": {
      "total_count": 10,
      "total_filtered_count": 5
    }
  }
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/environments" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

Stop a progressive rollout

POST https://api.ap1.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/stophttps://api.ap2.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/stophttps://api.datadoghq.eu/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/stophttps://api.ddog-gov.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/stophttps://api.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/stophttps://api.us3.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/stophttps://api.us5.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/stop

Overview

Stops a progressive rollout and marks it as aborted. This endpoint requires the feature_flag_config_write permission.

Arguments

Path Parameters

Name

Type

Description

exposure_schedule_id [required]

string

The ID of the exposure schedule.

Response

OK

Response containing a progressive rollout schedule.

Expand All

Field

Type

Description

data [required]

object

Data wrapper for progressive rollout schedule responses.

attributes [required]

object

Progressive release details for a targeting rule allocation.

absolute_start_time

date-time

The absolute UTC start time for this schedule.

allocation_id [required]

uuid

The targeting rule allocation ID this progressive rollout belongs to.

control_variant_id

string

The control variant ID used for experiment comparisons.

created_at [required]

date-time

The timestamp when the schedule was created.

guardrail_triggered_action

string

Last guardrail action triggered for this schedule.

guardrail_triggers [required]

[object]

Guardrail trigger records for this schedule.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this trigger belongs to.

created_at [required]

date-time

The timestamp when this trigger was created.

flagging_variant_id [required]

uuid

The variant ID that triggered this event.

id [required]

uuid

The unique identifier of the guardrail trigger.

metric_id [required]

string

The metric ID associated with the trigger.

triggered_action [required]

string

The action that was triggered.

updated_at [required]

date-time

The timestamp when this trigger was last updated.

id

uuid

The unique identifier of the progressive rollout.

rollout_options [required]

object

Applied progression options for a progressive rollout.

autostart [required]

boolean

Whether the schedule starts automatically.

selection_interval_ms [required]

int64

Interval in milliseconds for uniform interval strategies.

strategy [required]

enum

The progression strategy used by a progressive rollout. Allowed enum values: UNIFORM_INTERVALS,NO_ROLLOUT

rollout_steps [required]

[object]

Ordered progression steps for exposure.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this step belongs to.

created_at [required]

date-time

The timestamp when the progression step was created.

exposure_ratio [required]

double

The exposure ratio for this step.

grouped_step_index [required]

int64

Logical index grouping related steps.

id [required]

uuid

The unique identifier of the progression step.

interval_ms

int64

Step duration in milliseconds.

is_pause_record [required]

boolean

Whether this step represents a pause record.

order_position [required]

int64

Sort order for the progression step.

updated_at [required]

date-time

The timestamp when the progression step was last updated.

updated_at [required]

date-time

The timestamp when the schedule was last updated.

id [required]

uuid

The unique identifier of the progressive rollout.

type [required]

enum

The resource type for progressive rollout schedules. Allowed enum values: allocation_exposure_schedules

{
  "data": {
    "attributes": {
      "absolute_start_time": "2025-06-13T12:00:00Z",
      "allocation_id": "550e8400-e29b-41d4-a716-446655440020",
      "control_variant_id": "550e8400-e29b-41d4-a716-446655440012",
      "created_at": "2024-01-01T12:00:00Z",
      "guardrail_triggered_action": "PAUSE",
      "guardrail_triggers": [
        {
          "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
          "created_at": "2024-01-01T12:00:00Z",
          "flagging_variant_id": "550e8400-e29b-41d4-a716-446655440001",
          "id": "550e8400-e29b-41d4-a716-446655440080",
          "metric_id": "metric-error-rate",
          "triggered_action": "PAUSE",
          "updated_at": "2024-01-01T12:00:00Z"
        }
      ],
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "rollout_options": {
        "autostart": false,
        "selection_interval_ms": 3600000,
        "strategy": "UNIFORM_INTERVALS"
      },
      "rollout_steps": [
        {
          "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
          "created_at": "2024-01-01T12:00:00Z",
          "exposure_ratio": 0.1,
          "grouped_step_index": 0,
          "id": "550e8400-e29b-41d4-a716-446655440040",
          "interval_ms": 3600000,
          "is_pause_record": false,
          "order_position": 0,
          "updated_at": "2024-01-01T12:00:00Z"
        }
      ],
      "updated_at": "2024-01-01T12:00:00Z"
    },
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "type": "allocation_exposure_schedules"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Conflict

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export exposure_schedule_id="550e8400-e29b-41d4-a716-446655440010"
# Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/exposure-schedules/${exposure_schedule_id}/stop" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

Resume a progressive rollout

POST https://api.ap1.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/resumehttps://api.ap2.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/resumehttps://api.datadoghq.eu/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/resumehttps://api.ddog-gov.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/resumehttps://api.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/resumehttps://api.us3.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/resumehttps://api.us5.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/resume

Overview

Resumes progression for a previously paused progressive rollout. This endpoint requires the feature_flag_config_write permission.

Arguments

Path Parameters

Name

Type

Description

exposure_schedule_id [required]

string

The ID of the exposure schedule.

Response

OK

Response containing a progressive rollout schedule.

Expand All

Field

Type

Description

data [required]

object

Data wrapper for progressive rollout schedule responses.

attributes [required]

object

Progressive release details for a targeting rule allocation.

absolute_start_time

date-time

The absolute UTC start time for this schedule.

allocation_id [required]

uuid

The targeting rule allocation ID this progressive rollout belongs to.

control_variant_id

string

The control variant ID used for experiment comparisons.

created_at [required]

date-time

The timestamp when the schedule was created.

guardrail_triggered_action

string

Last guardrail action triggered for this schedule.

guardrail_triggers [required]

[object]

Guardrail trigger records for this schedule.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this trigger belongs to.

created_at [required]

date-time

The timestamp when this trigger was created.

flagging_variant_id [required]

uuid

The variant ID that triggered this event.

id [required]

uuid

The unique identifier of the guardrail trigger.

metric_id [required]

string

The metric ID associated with the trigger.

triggered_action [required]

string

The action that was triggered.

updated_at [required]

date-time

The timestamp when this trigger was last updated.

id

uuid

The unique identifier of the progressive rollout.

rollout_options [required]

object

Applied progression options for a progressive rollout.

autostart [required]

boolean

Whether the schedule starts automatically.

selection_interval_ms [required]

int64

Interval in milliseconds for uniform interval strategies.

strategy [required]

enum

The progression strategy used by a progressive rollout. Allowed enum values: UNIFORM_INTERVALS,NO_ROLLOUT

rollout_steps [required]

[object]

Ordered progression steps for exposure.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this step belongs to.

created_at [required]

date-time

The timestamp when the progression step was created.

exposure_ratio [required]

double

The exposure ratio for this step.

grouped_step_index [required]

int64

Logical index grouping related steps.

id [required]

uuid

The unique identifier of the progression step.

interval_ms

int64

Step duration in milliseconds.

is_pause_record [required]

boolean

Whether this step represents a pause record.

order_position [required]

int64

Sort order for the progression step.

updated_at [required]

date-time

The timestamp when the progression step was last updated.

updated_at [required]

date-time

The timestamp when the schedule was last updated.

id [required]

uuid

The unique identifier of the progressive rollout.

type [required]

enum

The resource type for progressive rollout schedules. Allowed enum values: allocation_exposure_schedules

{
  "data": {
    "attributes": {
      "absolute_start_time": "2025-06-13T12:00:00Z",
      "allocation_id": "550e8400-e29b-41d4-a716-446655440020",
      "control_variant_id": "550e8400-e29b-41d4-a716-446655440012",
      "created_at": "2024-01-01T12:00:00Z",
      "guardrail_triggered_action": "PAUSE",
      "guardrail_triggers": [
        {
          "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
          "created_at": "2024-01-01T12:00:00Z",
          "flagging_variant_id": "550e8400-e29b-41d4-a716-446655440001",
          "id": "550e8400-e29b-41d4-a716-446655440080",
          "metric_id": "metric-error-rate",
          "triggered_action": "PAUSE",
          "updated_at": "2024-01-01T12:00:00Z"
        }
      ],
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "rollout_options": {
        "autostart": false,
        "selection_interval_ms": 3600000,
        "strategy": "UNIFORM_INTERVALS"
      },
      "rollout_steps": [
        {
          "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
          "created_at": "2024-01-01T12:00:00Z",
          "exposure_ratio": 0.1,
          "grouped_step_index": 0,
          "id": "550e8400-e29b-41d4-a716-446655440040",
          "interval_ms": 3600000,
          "is_pause_record": false,
          "order_position": 0,
          "updated_at": "2024-01-01T12:00:00Z"
        }
      ],
      "updated_at": "2024-01-01T12:00:00Z"
    },
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "type": "allocation_exposure_schedules"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Conflict

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export exposure_schedule_id="550e8400-e29b-41d4-a716-446655440010"
# Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/exposure-schedules/${exposure_schedule_id}/resume" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

Pause a progressive rollout

POST https://api.ap1.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/pausehttps://api.ap2.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/pausehttps://api.datadoghq.eu/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/pausehttps://api.ddog-gov.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/pausehttps://api.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/pausehttps://api.us3.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/pausehttps://api.us5.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/pause

Overview

Pauses a progressive rollout while preserving rollout state. This endpoint requires the feature_flag_config_write permission.

Arguments

Path Parameters

Name

Type

Description

exposure_schedule_id [required]

string

The ID of the exposure schedule.

Response

OK

Response containing a progressive rollout schedule.

Expand All

Field

Type

Description

data [required]

object

Data wrapper for progressive rollout schedule responses.

attributes [required]

object

Progressive release details for a targeting rule allocation.

absolute_start_time

date-time

The absolute UTC start time for this schedule.

allocation_id [required]

uuid

The targeting rule allocation ID this progressive rollout belongs to.

control_variant_id

string

The control variant ID used for experiment comparisons.

created_at [required]

date-time

The timestamp when the schedule was created.

guardrail_triggered_action

string

Last guardrail action triggered for this schedule.

guardrail_triggers [required]

[object]

Guardrail trigger records for this schedule.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this trigger belongs to.

created_at [required]

date-time

The timestamp when this trigger was created.

flagging_variant_id [required]

uuid

The variant ID that triggered this event.

id [required]

uuid

The unique identifier of the guardrail trigger.

metric_id [required]

string

The metric ID associated with the trigger.

triggered_action [required]

string

The action that was triggered.

updated_at [required]

date-time

The timestamp when this trigger was last updated.

id

uuid

The unique identifier of the progressive rollout.

rollout_options [required]

object

Applied progression options for a progressive rollout.

autostart [required]

boolean

Whether the schedule starts automatically.

selection_interval_ms [required]

int64

Interval in milliseconds for uniform interval strategies.

strategy [required]

enum

The progression strategy used by a progressive rollout. Allowed enum values: UNIFORM_INTERVALS,NO_ROLLOUT

rollout_steps [required]

[object]

Ordered progression steps for exposure.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this step belongs to.

created_at [required]

date-time

The timestamp when the progression step was created.

exposure_ratio [required]

double

The exposure ratio for this step.

grouped_step_index [required]

int64

Logical index grouping related steps.

id [required]

uuid

The unique identifier of the progression step.

interval_ms

int64

Step duration in milliseconds.

is_pause_record [required]

boolean

Whether this step represents a pause record.

order_position [required]

int64

Sort order for the progression step.

updated_at [required]

date-time

The timestamp when the progression step was last updated.

updated_at [required]

date-time

The timestamp when the schedule was last updated.

id [required]

uuid

The unique identifier of the progressive rollout.

type [required]

enum

The resource type for progressive rollout schedules. Allowed enum values: allocation_exposure_schedules

{
  "data": {
    "attributes": {
      "absolute_start_time": "2025-06-13T12:00:00Z",
      "allocation_id": "550e8400-e29b-41d4-a716-446655440020",
      "control_variant_id": "550e8400-e29b-41d4-a716-446655440012",
      "created_at": "2024-01-01T12:00:00Z",
      "guardrail_triggered_action": "PAUSE",
      "guardrail_triggers": [
        {
          "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
          "created_at": "2024-01-01T12:00:00Z",
          "flagging_variant_id": "550e8400-e29b-41d4-a716-446655440001",
          "id": "550e8400-e29b-41d4-a716-446655440080",
          "metric_id": "metric-error-rate",
          "triggered_action": "PAUSE",
          "updated_at": "2024-01-01T12:00:00Z"
        }
      ],
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "rollout_options": {
        "autostart": false,
        "selection_interval_ms": 3600000,
        "strategy": "UNIFORM_INTERVALS"
      },
      "rollout_steps": [
        {
          "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
          "created_at": "2024-01-01T12:00:00Z",
          "exposure_ratio": 0.1,
          "grouped_step_index": 0,
          "id": "550e8400-e29b-41d4-a716-446655440040",
          "interval_ms": 3600000,
          "is_pause_record": false,
          "order_position": 0,
          "updated_at": "2024-01-01T12:00:00Z"
        }
      ],
      "updated_at": "2024-01-01T12:00:00Z"
    },
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "type": "allocation_exposure_schedules"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Conflict

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export exposure_schedule_id="550e8400-e29b-41d4-a716-446655440010"
# Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/exposure-schedules/${exposure_schedule_id}/pause" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

Start a progressive rollout

POST https://api.ap1.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/starthttps://api.ap2.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/starthttps://api.datadoghq.eu/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/starthttps://api.ddog-gov.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/starthttps://api.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/starthttps://api.us3.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/starthttps://api.us5.datadoghq.com/api/v2/feature-flags/exposure-schedules/{exposure_schedule_id}/start

Overview

Starts a progressive rollout and begins progression. This endpoint requires the feature_flag_config_write permission.

Arguments

Path Parameters

Name

Type

Description

exposure_schedule_id [required]

string

The ID of the exposure schedule.

Response

OK

Response containing a progressive rollout schedule.

Expand All

Field

Type

Description

data [required]

object

Data wrapper for progressive rollout schedule responses.

attributes [required]

object

Progressive release details for a targeting rule allocation.

absolute_start_time

date-time

The absolute UTC start time for this schedule.

allocation_id [required]

uuid

The targeting rule allocation ID this progressive rollout belongs to.

control_variant_id

string

The control variant ID used for experiment comparisons.

created_at [required]

date-time

The timestamp when the schedule was created.

guardrail_triggered_action

string

Last guardrail action triggered for this schedule.

guardrail_triggers [required]

[object]

Guardrail trigger records for this schedule.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this trigger belongs to.

created_at [required]

date-time

The timestamp when this trigger was created.

flagging_variant_id [required]

uuid

The variant ID that triggered this event.

id [required]

uuid

The unique identifier of the guardrail trigger.

metric_id [required]

string

The metric ID associated with the trigger.

triggered_action [required]

string

The action that was triggered.

updated_at [required]

date-time

The timestamp when this trigger was last updated.

id

uuid

The unique identifier of the progressive rollout.

rollout_options [required]

object

Applied progression options for a progressive rollout.

autostart [required]

boolean

Whether the schedule starts automatically.

selection_interval_ms [required]

int64

Interval in milliseconds for uniform interval strategies.

strategy [required]

enum

The progression strategy used by a progressive rollout. Allowed enum values: UNIFORM_INTERVALS,NO_ROLLOUT

rollout_steps [required]

[object]

Ordered progression steps for exposure.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this step belongs to.

created_at [required]

date-time

The timestamp when the progression step was created.

exposure_ratio [required]

double

The exposure ratio for this step.

grouped_step_index [required]

int64

Logical index grouping related steps.

id [required]

uuid

The unique identifier of the progression step.

interval_ms

int64

Step duration in milliseconds.

is_pause_record [required]

boolean

Whether this step represents a pause record.

order_position [required]

int64

Sort order for the progression step.

updated_at [required]

date-time

The timestamp when the progression step was last updated.

updated_at [required]

date-time

The timestamp when the schedule was last updated.

id [required]

uuid

The unique identifier of the progressive rollout.

type [required]

enum

The resource type for progressive rollout schedules. Allowed enum values: allocation_exposure_schedules

{
  "data": {
    "attributes": {
      "absolute_start_time": "2025-06-13T12:00:00Z",
      "allocation_id": "550e8400-e29b-41d4-a716-446655440020",
      "control_variant_id": "550e8400-e29b-41d4-a716-446655440012",
      "created_at": "2024-01-01T12:00:00Z",
      "guardrail_triggered_action": "PAUSE",
      "guardrail_triggers": [
        {
          "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
          "created_at": "2024-01-01T12:00:00Z",
          "flagging_variant_id": "550e8400-e29b-41d4-a716-446655440001",
          "id": "550e8400-e29b-41d4-a716-446655440080",
          "metric_id": "metric-error-rate",
          "triggered_action": "PAUSE",
          "updated_at": "2024-01-01T12:00:00Z"
        }
      ],
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "rollout_options": {
        "autostart": false,
        "selection_interval_ms": 3600000,
        "strategy": "UNIFORM_INTERVALS"
      },
      "rollout_steps": [
        {
          "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
          "created_at": "2024-01-01T12:00:00Z",
          "exposure_ratio": 0.1,
          "grouped_step_index": 0,
          "id": "550e8400-e29b-41d4-a716-446655440040",
          "interval_ms": 3600000,
          "is_pause_record": false,
          "order_position": 0,
          "updated_at": "2024-01-01T12:00:00Z"
        }
      ],
      "updated_at": "2024-01-01T12:00:00Z"
    },
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "type": "allocation_exposure_schedules"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Conflict

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export exposure_schedule_id="550e8400-e29b-41d4-a716-446655440010"
# Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/exposure-schedules/${exposure_schedule_id}/start" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

Update targeting rules for a flag

PUT https://api.ap1.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/allocationshttps://api.ap2.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/allocationshttps://api.datadoghq.eu/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/allocationshttps://api.ddog-gov.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/allocationshttps://api.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/allocationshttps://api.us3.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/allocationshttps://api.us5.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/allocations

Overview

Updates targeting rules (allocations) for a specific feature flag in a specific environment. This operation replaces the existing allocation set with the request payload. This endpoint requires the feature_flag_config_write permission.

Arguments

Path Parameters

Name

Type

Description

feature_flag_id [required]

string

The ID of the feature flag.

environment_id [required]

string

The ID of the environment.

Request

Body Data (required)

Expand All

Field

Type

Description

data [required]

[object]

Targeting rules (allocations) to replace existing ones with.

attributes [required]

object

Request to create or update a targeting rule (allocation) for a feature flag environment.

experiment_id

string

The experiment ID for experiment-linked allocations.

exposure_schedule

object

Progressive release request payload.

absolute_start_time

date-time

The absolute UTC start time for this schedule.

control_variant_id

string

The control variant ID used for experiment comparisons.

control_variant_key

string

The control variant key used during creation workflows.

id

uuid

The unique identifier of the progressive rollout.

rollout_options [required]

object

Rollout options request payload.

autostart

boolean

Whether the schedule should begin automatically.

selection_interval_ms

int64

Interval in milliseconds for uniform interval strategies.

strategy [required]

enum

The progression strategy used by a progressive rollout. Allowed enum values: UNIFORM_INTERVALS,NO_ROLLOUT

rollout_steps [required]

[object]

Ordered progression steps for exposure.

exposure_ratio [required]

double

The exposure ratio for this step.

grouped_step_index [required]

int64

Logical index grouping related steps.

id

uuid

The unique identifier of the progression step.

interval_ms

int64

Step duration in milliseconds.

is_pause_record [required]

boolean

Whether this step represents a pause record.

guardrail_metrics

[object]

Guardrail metrics used to monitor and auto-pause or abort.

metric_id [required]

string

The metric ID to monitor.

trigger_action [required]

enum

Action to perform when a guardrail threshold is triggered. Allowed enum values: PAUSE,ABORT

id

uuid

The unique identifier of the targeting rule allocation.

key [required]

string

The unique key of the targeting rule allocation.

name [required]

string

The display name of the targeting rule.

targeting_rules

[object]

Targeting rules that determine audience eligibility.

conditions [required]

[object]

Conditions that must match for this rule.

attribute [required]

string

The user or request attribute to evaluate.

operator [required]

enum

The operator used in a targeting condition. Allowed enum values: LT,LTE,GT,GTE,MATCHES,NOT_MATCHES,ONE_OF,NOT_ONE_OF,IS_NULL,EQUALS

value [required]

[string]

Values used by the selected operator.

type [required]

enum

The type of targeting rule (called allocation in the API model). Allowed enum values: FEATURE_GATE,CANARY

variant_weights

[object]

Variant distribution weights.

value [required]

double

The percentage weight for this variant.

variant_id

uuid

The variant ID to assign weight to.

variant_key

string

The variant key to assign weight to.

type [required]

enum

The resource type. Allowed enum values: allocations

{
  "data": [
    {
      "type": "allocations",
      "attributes": {
        "key": "overwrite-allocation-example-feature-flag",
        "name": "New targeting rule Example-Feature-Flag",
        "targeting_rules": [],
        "variant_weights": [
          {
            "variant_id": "550e8400-e29b-41d4-a716-446655440002",
            "value": 100
          }
        ],
        "exposure_schedule": {
          "rollout_options": {
            "strategy": "UNIFORM_INTERVALS",
            "autostart": false,
            "selection_interval_ms": 86400000
          },
          "rollout_steps": [
            {
              "exposure_ratio": 0.05,
              "interval_ms": null,
              "is_pause_record": false,
              "grouped_step_index": 0
            },
            {
              "exposure_ratio": 0.25,
              "interval_ms": null,
              "is_pause_record": false,
              "grouped_step_index": 1
            },
            {
              "exposure_ratio": 1,
              "interval_ms": null,
              "is_pause_record": false,
              "grouped_step_index": 2
            }
          ]
        },
        "guardrail_metrics": [],
        "type": "CANARY"
      }
    }
  ]
}

Response

OK

Response containing a list of targeting rules (allocations).

Expand All

Field

Type

Description

data [required]

[object]

List of targeting rules (allocations).

attributes [required]

object

Targeting rule (allocation) details for a feature flag environment.

created_at [required]

date-time

The timestamp when the targeting rule allocation was created.

environment_ids [required]

[string]

Environment IDs associated with this targeting rule allocation.

experiment_id

string

The experiment ID linked to this targeting rule allocation.

exposure_schedule

object

Progressive release details for a targeting rule allocation.

absolute_start_time

date-time

The absolute UTC start time for this schedule.

allocation_id [required]

uuid

The targeting rule allocation ID this progressive rollout belongs to.

control_variant_id

string

The control variant ID used for experiment comparisons.

created_at [required]

date-time

The timestamp when the schedule was created.

guardrail_triggered_action

string

Last guardrail action triggered for this schedule.

guardrail_triggers [required]

[object]

Guardrail trigger records for this schedule.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this trigger belongs to.

created_at [required]

date-time

The timestamp when this trigger was created.

flagging_variant_id [required]

uuid

The variant ID that triggered this event.

id [required]

uuid

The unique identifier of the guardrail trigger.

metric_id [required]

string

The metric ID associated with the trigger.

triggered_action [required]

string

The action that was triggered.

updated_at [required]

date-time

The timestamp when this trigger was last updated.

id

uuid

The unique identifier of the progressive rollout.

rollout_options [required]

object

Applied progression options for a progressive rollout.

autostart [required]

boolean

Whether the schedule starts automatically.

selection_interval_ms [required]

int64

Interval in milliseconds for uniform interval strategies.

strategy [required]

enum

The progression strategy used by a progressive rollout. Allowed enum values: UNIFORM_INTERVALS,NO_ROLLOUT

rollout_steps [required]

[object]

Ordered progression steps for exposure.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this step belongs to.

created_at [required]

date-time

The timestamp when the progression step was created.

exposure_ratio [required]

double

The exposure ratio for this step.

grouped_step_index [required]

int64

Logical index grouping related steps.

id [required]

uuid

The unique identifier of the progression step.

interval_ms

int64

Step duration in milliseconds.

is_pause_record [required]

boolean

Whether this step represents a pause record.

order_position [required]

int64

Sort order for the progression step.

updated_at [required]

date-time

The timestamp when the progression step was last updated.

updated_at [required]

date-time

The timestamp when the schedule was last updated.

guardrail_metrics [required]

[object]

Guardrail metrics associated with this targeting rule allocation.

metric_id [required]

string

The metric ID to monitor.

trigger_action [required]

enum

Action to perform when a guardrail threshold is triggered. Allowed enum values: PAUSE,ABORT

triggered_by

string

The signal or system that triggered the action.

id

uuid

The unique identifier of the targeting rule allocation.

key [required]

string

The unique key of the targeting rule allocation.

name [required]

string

The display name of the targeting rule.

order_position [required]

int64

Sort order position within the environment.

targeting_rules [required]

[object]

Conditions associated with this targeting rule allocation.

conditions [required]

[object]

Conditions evaluated by this targeting rule.

attribute [required]

string

The user or request attribute to evaluate.

created_at [required]

date-time

The timestamp when the condition was created.

id [required]

uuid

The unique identifier of the condition.

operator [required]

enum

The operator used in a targeting condition. Allowed enum values: LT,LTE,GT,GTE,MATCHES,NOT_MATCHES,ONE_OF,NOT_ONE_OF,IS_NULL,EQUALS

updated_at [required]

date-time

The timestamp when the condition was last updated.

value [required]

[string]

Values used by the selected operator.

created_at [required]

date-time

The timestamp when the targeting rule was created.

id [required]

uuid

The unique identifier of the targeting rule.

updated_at [required]

date-time

The timestamp when the targeting rule was last updated.

type [required]

enum

The type of targeting rule (called allocation in the API model). Allowed enum values: FEATURE_GATE,CANARY

updated_at [required]

date-time

The timestamp when the targeting rule allocation was last updated.

variant_weights [required]

[object]

Weighted variant assignments for this targeting rule allocation.

created_at

date-time

The timestamp when the variant weight was created.

id

uuid

Unique identifier of the variant weight assignment.

updated_at

date-time

The timestamp when the variant weight was last updated.

value [required]

double

The percentage weight for the variant.

variant

object

A variant of a feature flag.

created_at

date-time

The timestamp when the variant was created.

id [required]

uuid

The unique identifier of the variant.

key [required]

string

The unique key of the variant.

name [required]

string

The name of the variant.

updated_at

date-time

The timestamp when the variant was last updated.

value [required]

string

The value of the variant as a string.

variant_id [required]

uuid

The variant ID.

id [required]

uuid

The unique identifier of the targeting rule allocation.

type [required]

enum

The resource type. Allowed enum values: allocations

{
  "data": [
    {
      "attributes": {
        "created_at": "2024-01-01T12:00:00Z",
        "environment_ids": [
          "550e8400-e29b-41d4-a716-446655440001"
        ],
        "experiment_id": "550e8400-e29b-41d4-a716-446655440030",
        "exposure_schedule": {
          "absolute_start_time": "2025-06-13T12:00:00Z",
          "allocation_id": "550e8400-e29b-41d4-a716-446655440020",
          "control_variant_id": "550e8400-e29b-41d4-a716-446655440012",
          "created_at": "2024-01-01T12:00:00Z",
          "guardrail_triggered_action": "PAUSE",
          "guardrail_triggers": [
            {
              "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
              "created_at": "2024-01-01T12:00:00Z",
              "flagging_variant_id": "550e8400-e29b-41d4-a716-446655440001",
              "id": "550e8400-e29b-41d4-a716-446655440080",
              "metric_id": "metric-error-rate",
              "triggered_action": "PAUSE",
              "updated_at": "2024-01-01T12:00:00Z"
            }
          ],
          "id": "550e8400-e29b-41d4-a716-446655440010",
          "rollout_options": {
            "autostart": false,
            "selection_interval_ms": 3600000,
            "strategy": "UNIFORM_INTERVALS"
          },
          "rollout_steps": [
            {
              "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
              "created_at": "2024-01-01T12:00:00Z",
              "exposure_ratio": 0.1,
              "grouped_step_index": 0,
              "id": "550e8400-e29b-41d4-a716-446655440040",
              "interval_ms": 3600000,
              "is_pause_record": false,
              "order_position": 0,
              "updated_at": "2024-01-01T12:00:00Z"
            }
          ],
          "updated_at": "2024-01-01T12:00:00Z"
        },
        "guardrail_metrics": [
          {
            "metric_id": "metric-error-rate",
            "trigger_action": "PAUSE",
            "triggered_by": "guardrail_monitor"
          }
        ],
        "id": "550e8400-e29b-41d4-a716-446655440020",
        "key": "prod-rollout",
        "name": "Production Rollout",
        "order_position": 0,
        "targeting_rules": [
          {
            "conditions": [
              {
                "attribute": "country",
                "created_at": "2024-01-01T12:00:00Z",
                "id": "550e8400-e29b-41d4-a716-446655440070",
                "operator": "ONE_OF",
                "updated_at": "2024-01-01T12:00:00Z",
                "value": [
                  "US",
                  "CA"
                ]
              }
            ],
            "created_at": "2024-01-01T12:00:00Z",
            "id": "550e8400-e29b-41d4-a716-446655440060",
            "updated_at": "2024-01-01T12:00:00Z"
          }
        ],
        "type": "FEATURE_GATE",
        "updated_at": "2024-01-01T12:00:00Z",
        "variant_weights": [
          {
            "created_at": "2024-01-01T12:00:00Z",
            "id": "59061199-e2ff-46e9-8b40-2193e3b21687",
            "updated_at": "2024-01-01T12:00:00Z",
            "value": 50,
            "variant": {
              "created_at": "2023-01-01T00:00:00Z",
              "id": "550e8400-e29b-41d4-a716-446655440002",
              "key": "variant-abc123",
              "name": "Variant ABC123",
              "updated_at": "2023-01-01T00:00:00Z",
              "value": "true"
            },
            "variant_id": "550e8400-e29b-41d4-a716-446655440001"
          }
        ]
      },
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "type": "allocations"
    }
  ]
}

Accepted - Approval required for this change

Response containing a list of targeting rules (allocations).

Expand All

Field

Type

Description

data [required]

[object]

List of targeting rules (allocations).

attributes [required]

object

Targeting rule (allocation) details for a feature flag environment.

created_at [required]

date-time

The timestamp when the targeting rule allocation was created.

environment_ids [required]

[string]

Environment IDs associated with this targeting rule allocation.

experiment_id

string

The experiment ID linked to this targeting rule allocation.

exposure_schedule

object

Progressive release details for a targeting rule allocation.

absolute_start_time

date-time

The absolute UTC start time for this schedule.

allocation_id [required]

uuid

The targeting rule allocation ID this progressive rollout belongs to.

control_variant_id

string

The control variant ID used for experiment comparisons.

created_at [required]

date-time

The timestamp when the schedule was created.

guardrail_triggered_action

string

Last guardrail action triggered for this schedule.

guardrail_triggers [required]

[object]

Guardrail trigger records for this schedule.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this trigger belongs to.

created_at [required]

date-time

The timestamp when this trigger was created.

flagging_variant_id [required]

uuid

The variant ID that triggered this event.

id [required]

uuid

The unique identifier of the guardrail trigger.

metric_id [required]

string

The metric ID associated with the trigger.

triggered_action [required]

string

The action that was triggered.

updated_at [required]

date-time

The timestamp when this trigger was last updated.

id

uuid

The unique identifier of the progressive rollout.

rollout_options [required]

object

Applied progression options for a progressive rollout.

autostart [required]

boolean

Whether the schedule starts automatically.

selection_interval_ms [required]

int64

Interval in milliseconds for uniform interval strategies.

strategy [required]

enum

The progression strategy used by a progressive rollout. Allowed enum values: UNIFORM_INTERVALS,NO_ROLLOUT

rollout_steps [required]

[object]

Ordered progression steps for exposure.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this step belongs to.

created_at [required]

date-time

The timestamp when the progression step was created.

exposure_ratio [required]

double

The exposure ratio for this step.

grouped_step_index [required]

int64

Logical index grouping related steps.

id [required]

uuid

The unique identifier of the progression step.

interval_ms

int64

Step duration in milliseconds.

is_pause_record [required]

boolean

Whether this step represents a pause record.

order_position [required]

int64

Sort order for the progression step.

updated_at [required]

date-time

The timestamp when the progression step was last updated.

updated_at [required]

date-time

The timestamp when the schedule was last updated.

guardrail_metrics [required]

[object]

Guardrail metrics associated with this targeting rule allocation.

metric_id [required]

string

The metric ID to monitor.

trigger_action [required]

enum

Action to perform when a guardrail threshold is triggered. Allowed enum values: PAUSE,ABORT

triggered_by

string

The signal or system that triggered the action.

id

uuid

The unique identifier of the targeting rule allocation.

key [required]

string

The unique key of the targeting rule allocation.

name [required]

string

The display name of the targeting rule.

order_position [required]

int64

Sort order position within the environment.

targeting_rules [required]

[object]

Conditions associated with this targeting rule allocation.

conditions [required]

[object]

Conditions evaluated by this targeting rule.

attribute [required]

string

The user or request attribute to evaluate.

created_at [required]

date-time

The timestamp when the condition was created.

id [required]

uuid

The unique identifier of the condition.

operator [required]

enum

The operator used in a targeting condition. Allowed enum values: LT,LTE,GT,GTE,MATCHES,NOT_MATCHES,ONE_OF,NOT_ONE_OF,IS_NULL,EQUALS

updated_at [required]

date-time

The timestamp when the condition was last updated.

value [required]

[string]

Values used by the selected operator.

created_at [required]

date-time

The timestamp when the targeting rule was created.

id [required]

uuid

The unique identifier of the targeting rule.

updated_at [required]

date-time

The timestamp when the targeting rule was last updated.

type [required]

enum

The type of targeting rule (called allocation in the API model). Allowed enum values: FEATURE_GATE,CANARY

updated_at [required]

date-time

The timestamp when the targeting rule allocation was last updated.

variant_weights [required]

[object]

Weighted variant assignments for this targeting rule allocation.

created_at

date-time

The timestamp when the variant weight was created.

id

uuid

Unique identifier of the variant weight assignment.

updated_at

date-time

The timestamp when the variant weight was last updated.

value [required]

double

The percentage weight for the variant.

variant

object

A variant of a feature flag.

created_at

date-time

The timestamp when the variant was created.

id [required]

uuid

The unique identifier of the variant.

key [required]

string

The unique key of the variant.

name [required]

string

The name of the variant.

updated_at

date-time

The timestamp when the variant was last updated.

value [required]

string

The value of the variant as a string.

variant_id [required]

uuid

The variant ID.

id [required]

uuid

The unique identifier of the targeting rule allocation.

type [required]

enum

The resource type. Allowed enum values: allocations

{
  "data": [
    {
      "attributes": {
        "created_at": "2024-01-01T12:00:00Z",
        "environment_ids": [
          "550e8400-e29b-41d4-a716-446655440001"
        ],
        "experiment_id": "550e8400-e29b-41d4-a716-446655440030",
        "exposure_schedule": {
          "absolute_start_time": "2025-06-13T12:00:00Z",
          "allocation_id": "550e8400-e29b-41d4-a716-446655440020",
          "control_variant_id": "550e8400-e29b-41d4-a716-446655440012",
          "created_at": "2024-01-01T12:00:00Z",
          "guardrail_triggered_action": "PAUSE",
          "guardrail_triggers": [
            {
              "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
              "created_at": "2024-01-01T12:00:00Z",
              "flagging_variant_id": "550e8400-e29b-41d4-a716-446655440001",
              "id": "550e8400-e29b-41d4-a716-446655440080",
              "metric_id": "metric-error-rate",
              "triggered_action": "PAUSE",
              "updated_at": "2024-01-01T12:00:00Z"
            }
          ],
          "id": "550e8400-e29b-41d4-a716-446655440010",
          "rollout_options": {
            "autostart": false,
            "selection_interval_ms": 3600000,
            "strategy": "UNIFORM_INTERVALS"
          },
          "rollout_steps": [
            {
              "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
              "created_at": "2024-01-01T12:00:00Z",
              "exposure_ratio": 0.1,
              "grouped_step_index": 0,
              "id": "550e8400-e29b-41d4-a716-446655440040",
              "interval_ms": 3600000,
              "is_pause_record": false,
              "order_position": 0,
              "updated_at": "2024-01-01T12:00:00Z"
            }
          ],
          "updated_at": "2024-01-01T12:00:00Z"
        },
        "guardrail_metrics": [
          {
            "metric_id": "metric-error-rate",
            "trigger_action": "PAUSE",
            "triggered_by": "guardrail_monitor"
          }
        ],
        "id": "550e8400-e29b-41d4-a716-446655440020",
        "key": "prod-rollout",
        "name": "Production Rollout",
        "order_position": 0,
        "targeting_rules": [
          {
            "conditions": [
              {
                "attribute": "country",
                "created_at": "2024-01-01T12:00:00Z",
                "id": "550e8400-e29b-41d4-a716-446655440070",
                "operator": "ONE_OF",
                "updated_at": "2024-01-01T12:00:00Z",
                "value": [
                  "US",
                  "CA"
                ]
              }
            ],
            "created_at": "2024-01-01T12:00:00Z",
            "id": "550e8400-e29b-41d4-a716-446655440060",
            "updated_at": "2024-01-01T12:00:00Z"
          }
        ],
        "type": "FEATURE_GATE",
        "updated_at": "2024-01-01T12:00:00Z",
        "variant_weights": [
          {
            "created_at": "2024-01-01T12:00:00Z",
            "id": "59061199-e2ff-46e9-8b40-2193e3b21687",
            "updated_at": "2024-01-01T12:00:00Z",
            "value": 50,
            "variant": {
              "created_at": "2023-01-01T00:00:00Z",
              "id": "550e8400-e29b-41d4-a716-446655440002",
              "key": "variant-abc123",
              "name": "Variant ABC123",
              "updated_at": "2023-01-01T00:00:00Z",
              "value": "true"
            },
            "variant_id": "550e8400-e29b-41d4-a716-446655440001"
          }
        ]
      },
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "type": "allocations"
    }
  ]
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Conflict

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                          # Path parameters
export feature_flag_id="550e8400-e29b-41d4-a716-446655440000"
export environment_id="550e8400-e29b-41d4-a716-446655440001"
# Curl command
curl -X PUT "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/${feature_flag_id}/environments/${environment_id}/allocations" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": [
    {
      "type": "allocations",
      "attributes": {
        "key": "overwrite-allocation-example-feature-flag",
        "name": "New targeting rule Example-Feature-Flag",
        "targeting_rules": [],
        "variant_weights": [
          {
            "variant_id": "550e8400-e29b-41d4-a716-446655440002",
            "value": 100
          }
        ],
        "exposure_schedule": {
          "rollout_options": {
            "strategy": "UNIFORM_INTERVALS",
            "autostart": false,
            "selection_interval_ms": 86400000
          },
          "rollout_steps": [
            {
              "exposure_ratio": 0.05,
              "interval_ms": null,
              "is_pause_record": false,
              "grouped_step_index": 0
            },
            {
              "exposure_ratio": 0.25,
              "interval_ms": null,
              "is_pause_record": false,
              "grouped_step_index": 1
            },
            {
              "exposure_ratio": 1,
              "interval_ms": null,
              "is_pause_record": false,
              "grouped_step_index": 2
            }
          ]
        },
        "guardrail_metrics": [],
        "type": "CANARY"
      }
    }
  ]
}
EOF

Create targeting rules for a flag env

POST https://api.ap1.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/allocationshttps://api.ap2.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/allocationshttps://api.datadoghq.eu/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/allocationshttps://api.ddog-gov.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/allocationshttps://api.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/allocationshttps://api.us3.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/allocationshttps://api.us5.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/allocations

Overview

Creates a new targeting rule (allocation) for a specific feature flag in a specific environment. This endpoint requires the feature_flag_config_write permission.

Arguments

Path Parameters

Name

Type

Description

feature_flag_id [required]

string

The ID of the feature flag.

environment_id [required]

string

The ID of the environment.

Request

Body Data (required)

Expand All

Field

Type

Description

data [required]

object

Data wrapper for allocation request payloads.

attributes [required]

object

Request to create or update a targeting rule (allocation) for a feature flag environment.

experiment_id

string

The experiment ID for experiment-linked allocations.

exposure_schedule

object

Progressive release request payload.

absolute_start_time

date-time

The absolute UTC start time for this schedule.

control_variant_id

string

The control variant ID used for experiment comparisons.

control_variant_key

string

The control variant key used during creation workflows.

id

uuid

The unique identifier of the progressive rollout.

rollout_options [required]

object

Rollout options request payload.

autostart

boolean

Whether the schedule should begin automatically.

selection_interval_ms

int64

Interval in milliseconds for uniform interval strategies.

strategy [required]

enum

The progression strategy used by a progressive rollout. Allowed enum values: UNIFORM_INTERVALS,NO_ROLLOUT

rollout_steps [required]

[object]

Ordered progression steps for exposure.

exposure_ratio [required]

double

The exposure ratio for this step.

grouped_step_index [required]

int64

Logical index grouping related steps.

id

uuid

The unique identifier of the progression step.

interval_ms

int64

Step duration in milliseconds.

is_pause_record [required]

boolean

Whether this step represents a pause record.

guardrail_metrics

[object]

Guardrail metrics used to monitor and auto-pause or abort.

metric_id [required]

string

The metric ID to monitor.

trigger_action [required]

enum

Action to perform when a guardrail threshold is triggered. Allowed enum values: PAUSE,ABORT

id

uuid

The unique identifier of the targeting rule allocation.

key [required]

string

The unique key of the targeting rule allocation.

name [required]

string

The display name of the targeting rule.

targeting_rules

[object]

Targeting rules that determine audience eligibility.

conditions [required]

[object]

Conditions that must match for this rule.

attribute [required]

string

The user or request attribute to evaluate.

operator [required]

enum

The operator used in a targeting condition. Allowed enum values: LT,LTE,GT,GTE,MATCHES,NOT_MATCHES,ONE_OF,NOT_ONE_OF,IS_NULL,EQUALS

value [required]

[string]

Values used by the selected operator.

type [required]

enum

The type of targeting rule (called allocation in the API model). Allowed enum values: FEATURE_GATE,CANARY

variant_weights

[object]

Variant distribution weights.

value [required]

double

The percentage weight for this variant.

variant_id

uuid

The variant ID to assign weight to.

variant_key

string

The variant key to assign weight to.

type [required]

enum

The resource type. Allowed enum values: allocations

{
  "data": {
    "type": "allocations",
    "attributes": {
      "name": "New targeting rule Example-Feature-Flag",
      "key": "new-targeting-rule-example-feature-flag",
      "targeting_rules": [],
      "variant_weights": [
        {
          "variant_id": "550e8400-e29b-41d4-a716-446655440002",
          "value": 100
        }
      ],
      "guardrail_metrics": [],
      "type": "CANARY"
    }
  }
}

Response

Created

Response containing a single targeting rule (allocation).

Expand All

Field

Type

Description

data [required]

object

Data wrapper for targeting rule allocation responses.

attributes [required]

object

Targeting rule (allocation) details for a feature flag environment.

created_at [required]

date-time

The timestamp when the targeting rule allocation was created.

environment_ids [required]

[string]

Environment IDs associated with this targeting rule allocation.

experiment_id

string

The experiment ID linked to this targeting rule allocation.

exposure_schedule

object

Progressive release details for a targeting rule allocation.

absolute_start_time

date-time

The absolute UTC start time for this schedule.

allocation_id [required]

uuid

The targeting rule allocation ID this progressive rollout belongs to.

control_variant_id

string

The control variant ID used for experiment comparisons.

created_at [required]

date-time

The timestamp when the schedule was created.

guardrail_triggered_action

string

Last guardrail action triggered for this schedule.

guardrail_triggers [required]

[object]

Guardrail trigger records for this schedule.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this trigger belongs to.

created_at [required]

date-time

The timestamp when this trigger was created.

flagging_variant_id [required]

uuid

The variant ID that triggered this event.

id [required]

uuid

The unique identifier of the guardrail trigger.

metric_id [required]

string

The metric ID associated with the trigger.

triggered_action [required]

string

The action that was triggered.

updated_at [required]

date-time

The timestamp when this trigger was last updated.

id

uuid

The unique identifier of the progressive rollout.

rollout_options [required]

object

Applied progression options for a progressive rollout.

autostart [required]

boolean

Whether the schedule starts automatically.

selection_interval_ms [required]

int64

Interval in milliseconds for uniform interval strategies.

strategy [required]

enum

The progression strategy used by a progressive rollout. Allowed enum values: UNIFORM_INTERVALS,NO_ROLLOUT

rollout_steps [required]

[object]

Ordered progression steps for exposure.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this step belongs to.

created_at [required]

date-time

The timestamp when the progression step was created.

exposure_ratio [required]

double

The exposure ratio for this step.

grouped_step_index [required]

int64

Logical index grouping related steps.

id [required]

uuid

The unique identifier of the progression step.

interval_ms

int64

Step duration in milliseconds.

is_pause_record [required]

boolean

Whether this step represents a pause record.

order_position [required]

int64

Sort order for the progression step.

updated_at [required]

date-time

The timestamp when the progression step was last updated.

updated_at [required]

date-time

The timestamp when the schedule was last updated.

guardrail_metrics [required]

[object]

Guardrail metrics associated with this targeting rule allocation.

metric_id [required]

string

The metric ID to monitor.

trigger_action [required]

enum

Action to perform when a guardrail threshold is triggered. Allowed enum values: PAUSE,ABORT

triggered_by

string

The signal or system that triggered the action.

id

uuid

The unique identifier of the targeting rule allocation.

key [required]

string

The unique key of the targeting rule allocation.

name [required]

string

The display name of the targeting rule.

order_position [required]

int64

Sort order position within the environment.

targeting_rules [required]

[object]

Conditions associated with this targeting rule allocation.

conditions [required]

[object]

Conditions evaluated by this targeting rule.

attribute [required]

string

The user or request attribute to evaluate.

created_at [required]

date-time

The timestamp when the condition was created.

id [required]

uuid

The unique identifier of the condition.

operator [required]

enum

The operator used in a targeting condition. Allowed enum values: LT,LTE,GT,GTE,MATCHES,NOT_MATCHES,ONE_OF,NOT_ONE_OF,IS_NULL,EQUALS

updated_at [required]

date-time

The timestamp when the condition was last updated.

value [required]

[string]

Values used by the selected operator.

created_at [required]

date-time

The timestamp when the targeting rule was created.

id [required]

uuid

The unique identifier of the targeting rule.

updated_at [required]

date-time

The timestamp when the targeting rule was last updated.

type [required]

enum

The type of targeting rule (called allocation in the API model). Allowed enum values: FEATURE_GATE,CANARY

updated_at [required]

date-time

The timestamp when the targeting rule allocation was last updated.

variant_weights [required]

[object]

Weighted variant assignments for this targeting rule allocation.

created_at

date-time

The timestamp when the variant weight was created.

id

uuid

Unique identifier of the variant weight assignment.

updated_at

date-time

The timestamp when the variant weight was last updated.

value [required]

double

The percentage weight for the variant.

variant

object

A variant of a feature flag.

created_at

date-time

The timestamp when the variant was created.

id [required]

uuid

The unique identifier of the variant.

key [required]

string

The unique key of the variant.

name [required]

string

The name of the variant.

updated_at

date-time

The timestamp when the variant was last updated.

value [required]

string

The value of the variant as a string.

variant_id [required]

uuid

The variant ID.

id [required]

uuid

The unique identifier of the targeting rule allocation.

type [required]

enum

The resource type. Allowed enum values: allocations

{
  "data": {
    "attributes": {
      "created_at": "2024-01-01T12:00:00Z",
      "environment_ids": [
        "550e8400-e29b-41d4-a716-446655440001"
      ],
      "experiment_id": "550e8400-e29b-41d4-a716-446655440030",
      "exposure_schedule": {
        "absolute_start_time": "2025-06-13T12:00:00Z",
        "allocation_id": "550e8400-e29b-41d4-a716-446655440020",
        "control_variant_id": "550e8400-e29b-41d4-a716-446655440012",
        "created_at": "2024-01-01T12:00:00Z",
        "guardrail_triggered_action": "PAUSE",
        "guardrail_triggers": [
          {
            "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
            "created_at": "2024-01-01T12:00:00Z",
            "flagging_variant_id": "550e8400-e29b-41d4-a716-446655440001",
            "id": "550e8400-e29b-41d4-a716-446655440080",
            "metric_id": "metric-error-rate",
            "triggered_action": "PAUSE",
            "updated_at": "2024-01-01T12:00:00Z"
          }
        ],
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "rollout_options": {
          "autostart": false,
          "selection_interval_ms": 3600000,
          "strategy": "UNIFORM_INTERVALS"
        },
        "rollout_steps": [
          {
            "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
            "created_at": "2024-01-01T12:00:00Z",
            "exposure_ratio": 0.1,
            "grouped_step_index": 0,
            "id": "550e8400-e29b-41d4-a716-446655440040",
            "interval_ms": 3600000,
            "is_pause_record": false,
            "order_position": 0,
            "updated_at": "2024-01-01T12:00:00Z"
          }
        ],
        "updated_at": "2024-01-01T12:00:00Z"
      },
      "guardrail_metrics": [
        {
          "metric_id": "metric-error-rate",
          "trigger_action": "PAUSE",
          "triggered_by": "guardrail_monitor"
        }
      ],
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "key": "prod-rollout",
      "name": "Production Rollout",
      "order_position": 0,
      "targeting_rules": [
        {
          "conditions": [
            {
              "attribute": "country",
              "created_at": "2024-01-01T12:00:00Z",
              "id": "550e8400-e29b-41d4-a716-446655440070",
              "operator": "ONE_OF",
              "updated_at": "2024-01-01T12:00:00Z",
              "value": [
                "US",
                "CA"
              ]
            }
          ],
          "created_at": "2024-01-01T12:00:00Z",
          "id": "550e8400-e29b-41d4-a716-446655440060",
          "updated_at": "2024-01-01T12:00:00Z"
        }
      ],
      "type": "FEATURE_GATE",
      "updated_at": "2024-01-01T12:00:00Z",
      "variant_weights": [
        {
          "created_at": "2024-01-01T12:00:00Z",
          "id": "59061199-e2ff-46e9-8b40-2193e3b21687",
          "updated_at": "2024-01-01T12:00:00Z",
          "value": 50,
          "variant": {
            "created_at": "2023-01-01T00:00:00Z",
            "id": "550e8400-e29b-41d4-a716-446655440002",
            "key": "variant-abc123",
            "name": "Variant ABC123",
            "updated_at": "2023-01-01T00:00:00Z",
            "value": "true"
          },
          "variant_id": "550e8400-e29b-41d4-a716-446655440001"
        }
      ]
    },
    "id": "550e8400-e29b-41d4-a716-446655440020",
    "type": "allocations"
  }
}

Accepted - Approval required for this change

Response containing a single targeting rule (allocation).

Expand All

Field

Type

Description

data [required]

object

Data wrapper for targeting rule allocation responses.

attributes [required]

object

Targeting rule (allocation) details for a feature flag environment.

created_at [required]

date-time

The timestamp when the targeting rule allocation was created.

environment_ids [required]

[string]

Environment IDs associated with this targeting rule allocation.

experiment_id

string

The experiment ID linked to this targeting rule allocation.

exposure_schedule

object

Progressive release details for a targeting rule allocation.

absolute_start_time

date-time

The absolute UTC start time for this schedule.

allocation_id [required]

uuid

The targeting rule allocation ID this progressive rollout belongs to.

control_variant_id

string

The control variant ID used for experiment comparisons.

created_at [required]

date-time

The timestamp when the schedule was created.

guardrail_triggered_action

string

Last guardrail action triggered for this schedule.

guardrail_triggers [required]

[object]

Guardrail trigger records for this schedule.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this trigger belongs to.

created_at [required]

date-time

The timestamp when this trigger was created.

flagging_variant_id [required]

uuid

The variant ID that triggered this event.

id [required]

uuid

The unique identifier of the guardrail trigger.

metric_id [required]

string

The metric ID associated with the trigger.

triggered_action [required]

string

The action that was triggered.

updated_at [required]

date-time

The timestamp when this trigger was last updated.

id

uuid

The unique identifier of the progressive rollout.

rollout_options [required]

object

Applied progression options for a progressive rollout.

autostart [required]

boolean

Whether the schedule starts automatically.

selection_interval_ms [required]

int64

Interval in milliseconds for uniform interval strategies.

strategy [required]

enum

The progression strategy used by a progressive rollout. Allowed enum values: UNIFORM_INTERVALS,NO_ROLLOUT

rollout_steps [required]

[object]

Ordered progression steps for exposure.

allocation_exposure_schedule_id [required]

uuid

The progressive rollout ID this step belongs to.

created_at [required]

date-time

The timestamp when the progression step was created.

exposure_ratio [required]

double

The exposure ratio for this step.

grouped_step_index [required]

int64

Logical index grouping related steps.

id [required]

uuid

The unique identifier of the progression step.

interval_ms

int64

Step duration in milliseconds.

is_pause_record [required]

boolean

Whether this step represents a pause record.

order_position [required]

int64

Sort order for the progression step.

updated_at [required]

date-time

The timestamp when the progression step was last updated.

updated_at [required]

date-time

The timestamp when the schedule was last updated.

guardrail_metrics [required]

[object]

Guardrail metrics associated with this targeting rule allocation.

metric_id [required]

string

The metric ID to monitor.

trigger_action [required]

enum

Action to perform when a guardrail threshold is triggered. Allowed enum values: PAUSE,ABORT

triggered_by

string

The signal or system that triggered the action.

id

uuid

The unique identifier of the targeting rule allocation.

key [required]

string

The unique key of the targeting rule allocation.

name [required]

string

The display name of the targeting rule.

order_position [required]

int64

Sort order position within the environment.

targeting_rules [required]

[object]

Conditions associated with this targeting rule allocation.

conditions [required]

[object]

Conditions evaluated by this targeting rule.

attribute [required]

string

The user or request attribute to evaluate.

created_at [required]

date-time

The timestamp when the condition was created.

id [required]

uuid

The unique identifier of the condition.

operator [required]

enum

The operator used in a targeting condition. Allowed enum values: LT,LTE,GT,GTE,MATCHES,NOT_MATCHES,ONE_OF,NOT_ONE_OF,IS_NULL,EQUALS

updated_at [required]

date-time

The timestamp when the condition was last updated.

value [required]

[string]

Values used by the selected operator.

created_at [required]

date-time

The timestamp when the targeting rule was created.

id [required]

uuid

The unique identifier of the targeting rule.

updated_at [required]

date-time

The timestamp when the targeting rule was last updated.

type [required]

enum

The type of targeting rule (called allocation in the API model). Allowed enum values: FEATURE_GATE,CANARY

updated_at [required]

date-time

The timestamp when the targeting rule allocation was last updated.

variant_weights [required]

[object]

Weighted variant assignments for this targeting rule allocation.

created_at

date-time

The timestamp when the variant weight was created.

id

uuid

Unique identifier of the variant weight assignment.

updated_at

date-time

The timestamp when the variant weight was last updated.

value [required]

double

The percentage weight for the variant.

variant

object

A variant of a feature flag.

created_at

date-time

The timestamp when the variant was created.

id [required]

uuid

The unique identifier of the variant.

key [required]

string

The unique key of the variant.

name [required]

string

The name of the variant.

updated_at

date-time

The timestamp when the variant was last updated.

value [required]

string

The value of the variant as a string.

variant_id [required]

uuid

The variant ID.

id [required]

uuid

The unique identifier of the targeting rule allocation.

type [required]

enum

The resource type. Allowed enum values: allocations

{
  "data": {
    "attributes": {
      "created_at": "2024-01-01T12:00:00Z",
      "environment_ids": [
        "550e8400-e29b-41d4-a716-446655440001"
      ],
      "experiment_id": "550e8400-e29b-41d4-a716-446655440030",
      "exposure_schedule": {
        "absolute_start_time": "2025-06-13T12:00:00Z",
        "allocation_id": "550e8400-e29b-41d4-a716-446655440020",
        "control_variant_id": "550e8400-e29b-41d4-a716-446655440012",
        "created_at": "2024-01-01T12:00:00Z",
        "guardrail_triggered_action": "PAUSE",
        "guardrail_triggers": [
          {
            "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
            "created_at": "2024-01-01T12:00:00Z",
            "flagging_variant_id": "550e8400-e29b-41d4-a716-446655440001",
            "id": "550e8400-e29b-41d4-a716-446655440080",
            "metric_id": "metric-error-rate",
            "triggered_action": "PAUSE",
            "updated_at": "2024-01-01T12:00:00Z"
          }
        ],
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "rollout_options": {
          "autostart": false,
          "selection_interval_ms": 3600000,
          "strategy": "UNIFORM_INTERVALS"
        },
        "rollout_steps": [
          {
            "allocation_exposure_schedule_id": "550e8400-e29b-41d4-a716-446655440010",
            "created_at": "2024-01-01T12:00:00Z",
            "exposure_ratio": 0.1,
            "grouped_step_index": 0,
            "id": "550e8400-e29b-41d4-a716-446655440040",
            "interval_ms": 3600000,
            "is_pause_record": false,
            "order_position": 0,
            "updated_at": "2024-01-01T12:00:00Z"
          }
        ],
        "updated_at": "2024-01-01T12:00:00Z"
      },
      "guardrail_metrics": [
        {
          "metric_id": "metric-error-rate",
          "trigger_action": "PAUSE",
          "triggered_by": "guardrail_monitor"
        }
      ],
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "key": "prod-rollout",
      "name": "Production Rollout",
      "order_position": 0,
      "targeting_rules": [
        {
          "conditions": [
            {
              "attribute": "country",
              "created_at": "2024-01-01T12:00:00Z",
              "id": "550e8400-e29b-41d4-a716-446655440070",
              "operator": "ONE_OF",
              "updated_at": "2024-01-01T12:00:00Z",
              "value": [
                "US",
                "CA"
              ]
            }
          ],
          "created_at": "2024-01-01T12:00:00Z",
          "id": "550e8400-e29b-41d4-a716-446655440060",
          "updated_at": "2024-01-01T12:00:00Z"
        }
      ],
      "type": "FEATURE_GATE",
      "updated_at": "2024-01-01T12:00:00Z",
      "variant_weights": [
        {
          "created_at": "2024-01-01T12:00:00Z",
          "id": "59061199-e2ff-46e9-8b40-2193e3b21687",
          "updated_at": "2024-01-01T12:00:00Z",
          "value": 50,
          "variant": {
            "created_at": "2023-01-01T00:00:00Z",
            "id": "550e8400-e29b-41d4-a716-446655440002",
            "key": "variant-abc123",
            "name": "Variant ABC123",
            "updated_at": "2023-01-01T00:00:00Z",
            "value": "true"
          },
          "variant_id": "550e8400-e29b-41d4-a716-446655440001"
        }
      ]
    },
    "id": "550e8400-e29b-41d4-a716-446655440020",
    "type": "allocations"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Conflict

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                          # Path parameters
export feature_flag_id="550e8400-e29b-41d4-a716-446655440000"
export environment_id="550e8400-e29b-41d4-a716-446655440001"
# Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/${feature_flag_id}/environments/${environment_id}/allocations" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": {
    "type": "allocations",
    "attributes": {
      "name": "New targeting rule Example-Feature-Flag",
      "key": "new-targeting-rule-example-feature-flag",
      "targeting_rules": [],
      "variant_weights": [
        {
          "variant_id": "550e8400-e29b-41d4-a716-446655440002",
          "value": 100
        }
      ],
      "guardrail_metrics": [],
      "type": "CANARY"
    }
  }
}
EOF

Disable a feature flag in an environment

POST https://api.ap1.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/disablehttps://api.ap2.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/disablehttps://api.datadoghq.eu/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/disablehttps://api.ddog-gov.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/disablehttps://api.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/disablehttps://api.us3.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/disablehttps://api.us5.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/disable

Overview

Disable a feature flag in a specific environment. This endpoint requires all of the following permissions:

  • feature_flag_config_write
  • feature_flag_environment_config_read

    • Arguments

    Path Parameters

    Name

    Type

    Description

    feature_flag_id [required]

    string

    The ID of the feature flag.

    environment_id [required]

    string

    The ID of the environment.

    Response

    OK

    Accepted - Approval required for this change

    Forbidden

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Not Found

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Code Example

                      # Path parameters
    export feature_flag_id="550e8400-e29b-41d4-a716-446655440000"
    export environment_id="550e8400-e29b-41d4-a716-446655440001"
    # Curl command
    curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/${feature_flag_id}/environments/${environment_id}/disable" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

    Enable a feature flag in an environment

    POST https://api.ap1.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/enablehttps://api.ap2.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/enablehttps://api.datadoghq.eu/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/enablehttps://api.ddog-gov.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/enablehttps://api.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/enablehttps://api.us3.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/enablehttps://api.us5.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/environments/{environment_id}/enable

    Overview

    Enable a feature flag in a specific environment. This endpoint requires all of the following permissions:

  • feature_flag_config_write
  • feature_flag_environment_config_read

    • Arguments

    Path Parameters

    Name

    Type

    Description

    feature_flag_id [required]

    string

    The ID of the feature flag.

    environment_id [required]

    string

    The ID of the environment.

    Response

    OK

    Accepted - Approval required for this change

    Forbidden

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Not Found

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Code Example

                      # Path parameters
    export feature_flag_id="550e8400-e29b-41d4-a716-446655440000"
    export environment_id="550e8400-e29b-41d4-a716-446655440001"
    # Curl command
    curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/${feature_flag_id}/environments/${environment_id}/enable" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

    Unarchive a feature flag

    POST https://api.ap1.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/unarchivehttps://api.ap2.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/unarchivehttps://api.datadoghq.eu/api/v2/feature-flags/{feature_flag_id}/unarchivehttps://api.ddog-gov.com/api/v2/feature-flags/{feature_flag_id}/unarchivehttps://api.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/unarchivehttps://api.us3.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/unarchivehttps://api.us5.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/unarchive

    Overview

    Unarchives a previously archived feature flag, making it visible in the main list again. This endpoint requires all of the following permissions:

  • feature_flag_config_write
  • feature_flag_environment_config_read

    • Arguments

    Path Parameters

    Name

    Type

    Description

    feature_flag_id [required]

    string

    The ID of the feature flag.

    Response

    OK

    Response containing a feature flag.

    Expand All

    Field

    Type

    Description

    data [required]

    object

    A feature flag resource.

    attributes [required]

    object

    Attributes of a feature flag.

    archived_at

    date-time

    The timestamp when the feature flag was archived.

    created_at

    date-time

    The timestamp when the feature flag was created.

    created_by

    uuid

    The ID of the user who created the feature flag.

    description [required]

    string

    The description of the feature flag.

    distribution_channel

    string

    Distribution channel for the feature flag.

    feature_flag_environments

    [object]

    Environment-specific settings for the feature flag.

    allocations

    object

    Allocation metadata for this environment.

    default_allocation_key

    string

    The allocation key used for the default variant.

    default_variant_id

    string

    The ID of the default variant for this environment.

    environment_id [required]

    uuid

    The ID of the environment.

    environment_name

    string

    The name of the environment.

    environment_queries

    [string]

    Queries that target this environment.

    is_production

    boolean

    Indicates whether the environment is production.

    override_allocation_key

    string

    The allocation key used for the override variant.

    override_variant_id

    string

    The ID of the override variant for this environment.

    pending_suggestion_id

    string

    Pending suggestion identifier, if approval is required.

    require_feature_flag_approval

    boolean

    Indicates whether feature flag changes require approval in this environment.

    rollout_percentage

    int64

    Rollout percentage for this environment.

    rules

    [object]

    Environment targeting rules for this feature flag.

    status [required]

    enum

    The status of a feature flag in an environment. Allowed enum values: ENABLED,DISABLED

    json_schema

    string

    JSON schema for validation when value_type is JSON.

    key [required]

    string

    The unique key of the feature flag.

    last_updated_by

    uuid

    The ID of the user who last updated the feature flag.

    name [required]

    string

    The name of the feature flag.

    require_approval

    boolean

    Indicates whether this feature flag requires approval for changes.

    tags

    [string]

    Tags associated with the feature flag.

    updated_at

    date-time

    The timestamp when the feature flag was last updated.

    value_type [required]

    enum

    The type of values for the feature flag variants. Allowed enum values: BOOLEAN,INTEGER,NUMERIC,STRING,JSON

    variants [required]

    [object]

    The variants of the feature flag.

    created_at

    date-time

    The timestamp when the variant was created.

    id [required]

    uuid

    The unique identifier of the variant.

    key [required]

    string

    The unique key of the variant.

    name [required]

    string

    The name of the variant.

    updated_at

    date-time

    The timestamp when the variant was last updated.

    value [required]

    string

    The value of the variant as a string.

    id [required]

    uuid

    The unique identifier of the feature flag.

    type [required]

    enum

    The resource type. Allowed enum values: feature-flags

    {
  "data": {
    "attributes": {
      "archived_at": "2023-01-01T00:00:00Z",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440010",
      "description": "This is an example feature flag for demonstration",
      "distribution_channel": "ALL",
      "feature_flag_environments": [
        {
          "allocations": {},
          "default_allocation_key": "allocation-default-123abc",
          "default_variant_id": "550e8400-e29b-41d4-a716-446655440002",
          "environment_id": "550e8400-e29b-41d4-a716-446655440001",
          "environment_name": "env-search-term",
          "environment_queries": [
            "test-feature-flag",
            "env-search-term"
          ],
          "is_production": false,
          "override_allocation_key": "allocation-override-123abc",
          "override_variant_id": "550e8400-e29b-41d4-a716-446655440003",
          "pending_suggestion_id": "550e8400-e29b-41d4-a716-446655440099",
          "require_feature_flag_approval": false,
          "rollout_percentage": 0,
          "rules": [],
          "status": "ENABLED"
        }
      ],
      "json_schema": "{\"type\": \"object\", \"properties\": {\"enabled\": {\"type\": \"boolean\"}}}",
      "key": "feature-flag-abc123",
      "last_updated_by": "550e8400-e29b-41d4-a716-446655440010",
      "name": "Feature Flag ABC123",
      "require_approval": false,
      "tags": [
        []
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "value_type": "BOOLEAN",
      "variants": [
        {
          "created_at": "2023-01-01T00:00:00Z",
          "id": "550e8400-e29b-41d4-a716-446655440002",
          "key": "variant-abc123",
          "name": "Variant ABC123",
          "updated_at": "2023-01-01T00:00:00Z",
          "value": "true"
        }
      ]
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "feature-flags"
  }
}

    Bad Request

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Forbidden

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Not Found

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Code Example

                      # Path parameters
    export feature_flag_id="550e8400-e29b-41d4-a716-446655440000"
    # Curl command
    curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/${feature_flag_id}/unarchive" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

    Archive a feature flag

    POST https://api.ap1.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/archivehttps://api.ap2.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/archivehttps://api.datadoghq.eu/api/v2/feature-flags/{feature_flag_id}/archivehttps://api.ddog-gov.com/api/v2/feature-flags/{feature_flag_id}/archivehttps://api.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/archivehttps://api.us3.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/archivehttps://api.us5.datadoghq.com/api/v2/feature-flags/{feature_flag_id}/archive

    Overview

    Archives a feature flag. Archived flags are hidden from the main list but remain accessible and can be unarchived. This endpoint requires all of the following permissions:

  • feature_flag_config_write
  • feature_flag_environment_config_read

    • Arguments

    Path Parameters

    Name

    Type

    Description

    feature_flag_id [required]

    string

    The ID of the feature flag.

    Response

    OK

    Response containing a feature flag.

    Expand All

    Field

    Type

    Description

    data [required]

    object

    A feature flag resource.

    attributes [required]

    object

    Attributes of a feature flag.

    archived_at

    date-time

    The timestamp when the feature flag was archived.

    created_at

    date-time

    The timestamp when the feature flag was created.

    created_by

    uuid

    The ID of the user who created the feature flag.

    description [required]

    string

    The description of the feature flag.

    distribution_channel

    string

    Distribution channel for the feature flag.

    feature_flag_environments

    [object]

    Environment-specific settings for the feature flag.

    allocations

    object

    Allocation metadata for this environment.

    default_allocation_key

    string

    The allocation key used for the default variant.

    default_variant_id

    string

    The ID of the default variant for this environment.

    environment_id [required]

    uuid

    The ID of the environment.

    environment_name

    string

    The name of the environment.

    environment_queries

    [string]

    Queries that target this environment.

    is_production

    boolean

    Indicates whether the environment is production.

    override_allocation_key

    string

    The allocation key used for the override variant.

    override_variant_id

    string

    The ID of the override variant for this environment.

    pending_suggestion_id

    string

    Pending suggestion identifier, if approval is required.

    require_feature_flag_approval

    boolean

    Indicates whether feature flag changes require approval in this environment.

    rollout_percentage

    int64

    Rollout percentage for this environment.

    rules

    [object]

    Environment targeting rules for this feature flag.

    status [required]

    enum

    The status of a feature flag in an environment. Allowed enum values: ENABLED,DISABLED

    json_schema

    string

    JSON schema for validation when value_type is JSON.

    key [required]

    string

    The unique key of the feature flag.

    last_updated_by

    uuid

    The ID of the user who last updated the feature flag.

    name [required]

    string

    The name of the feature flag.

    require_approval

    boolean

    Indicates whether this feature flag requires approval for changes.

    tags

    [string]

    Tags associated with the feature flag.

    updated_at

    date-time

    The timestamp when the feature flag was last updated.

    value_type [required]

    enum

    The type of values for the feature flag variants. Allowed enum values: BOOLEAN,INTEGER,NUMERIC,STRING,JSON

    variants [required]

    [object]

    The variants of the feature flag.

    created_at

    date-time

    The timestamp when the variant was created.

    id [required]

    uuid

    The unique identifier of the variant.

    key [required]

    string

    The unique key of the variant.

    name [required]

    string

    The name of the variant.

    updated_at

    date-time

    The timestamp when the variant was last updated.

    value [required]

    string

    The value of the variant as a string.

    id [required]

    uuid

    The unique identifier of the feature flag.

    type [required]

    enum

    The resource type. Allowed enum values: feature-flags

    {
  "data": {
    "attributes": {
      "archived_at": "2023-01-01T00:00:00Z",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440010",
      "description": "This is an example feature flag for demonstration",
      "distribution_channel": "ALL",
      "feature_flag_environments": [
        {
          "allocations": {},
          "default_allocation_key": "allocation-default-123abc",
          "default_variant_id": "550e8400-e29b-41d4-a716-446655440002",
          "environment_id": "550e8400-e29b-41d4-a716-446655440001",
          "environment_name": "env-search-term",
          "environment_queries": [
            "test-feature-flag",
            "env-search-term"
          ],
          "is_production": false,
          "override_allocation_key": "allocation-override-123abc",
          "override_variant_id": "550e8400-e29b-41d4-a716-446655440003",
          "pending_suggestion_id": "550e8400-e29b-41d4-a716-446655440099",
          "require_feature_flag_approval": false,
          "rollout_percentage": 0,
          "rules": [],
          "status": "ENABLED"
        }
      ],
      "json_schema": "{\"type\": \"object\", \"properties\": {\"enabled\": {\"type\": \"boolean\"}}}",
      "key": "feature-flag-abc123",
      "last_updated_by": "550e8400-e29b-41d4-a716-446655440010",
      "name": "Feature Flag ABC123",
      "require_approval": false,
      "tags": [
        []
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "value_type": "BOOLEAN",
      "variants": [
        {
          "created_at": "2023-01-01T00:00:00Z",
          "id": "550e8400-e29b-41d4-a716-446655440002",
          "key": "variant-abc123",
          "name": "Variant ABC123",
          "updated_at": "2023-01-01T00:00:00Z",
          "value": "true"
        }
      ]
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "feature-flags"
  }
}

    Bad Request

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Forbidden

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Not Found

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Code Example

                      # Path parameters
    export feature_flag_id="550e8400-e29b-41d4-a716-446655440000"
    # Curl command
    curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/${feature_flag_id}/archive" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

    Update a feature flag

    PUT https://api.ap1.datadoghq.com/api/v2/feature-flags/{feature_flag_id}https://api.ap2.datadoghq.com/api/v2/feature-flags/{feature_flag_id}https://api.datadoghq.eu/api/v2/feature-flags/{feature_flag_id}https://api.ddog-gov.com/api/v2/feature-flags/{feature_flag_id}https://api.datadoghq.com/api/v2/feature-flags/{feature_flag_id}https://api.us3.datadoghq.com/api/v2/feature-flags/{feature_flag_id}https://api.us5.datadoghq.com/api/v2/feature-flags/{feature_flag_id}

    Overview

    Updates an existing feature flag’s metadata such as name and description. Does not modify targeting rules or allocations. This endpoint requires all of the following permissions:

  • feature_flag_config_write
  • feature_flag_environment_config_read

    • Arguments

    Path Parameters

    Name

    Type

    Description

    feature_flag_id [required]

    string

    The ID of the feature flag.

    Request

    Body Data (required)

    Expand All

    Field

    Type

    Description

    data [required]

    object

    Data for updating a feature flag.

    attributes [required]

    object

    Attributes for updating a feature flag.

    description

    string

    The description of the feature flag.

    json_schema

    string

    JSON schema for validation when value_type is JSON.

    name

    string

    The name of the feature flag.

    type [required]

    enum

    The resource type. Allowed enum values: feature-flags

    {
  "data": {
    "type": "feature-flags",
    "attributes": {
      "description": "Updated description for the feature flag",
      "name": "Updated Test Feature Flag Example-Feature-Flag"
    }
  }
}

    Response

    OK

    Response containing a feature flag.

    Expand All

    Field

    Type

    Description

    data [required]

    object

    A feature flag resource.

    attributes [required]

    object

    Attributes of a feature flag.

    archived_at

    date-time

    The timestamp when the feature flag was archived.

    created_at

    date-time

    The timestamp when the feature flag was created.

    created_by

    uuid

    The ID of the user who created the feature flag.

    description [required]

    string

    The description of the feature flag.

    distribution_channel

    string

    Distribution channel for the feature flag.

    feature_flag_environments

    [object]

    Environment-specific settings for the feature flag.

    allocations

    object

    Allocation metadata for this environment.

    default_allocation_key

    string

    The allocation key used for the default variant.

    default_variant_id

    string

    The ID of the default variant for this environment.

    environment_id [required]

    uuid

    The ID of the environment.

    environment_name

    string

    The name of the environment.

    environment_queries

    [string]

    Queries that target this environment.

    is_production

    boolean

    Indicates whether the environment is production.

    override_allocation_key

    string

    The allocation key used for the override variant.

    override_variant_id

    string

    The ID of the override variant for this environment.

    pending_suggestion_id

    string

    Pending suggestion identifier, if approval is required.

    require_feature_flag_approval

    boolean

    Indicates whether feature flag changes require approval in this environment.

    rollout_percentage

    int64

    Rollout percentage for this environment.

    rules

    [object]

    Environment targeting rules for this feature flag.

    status [required]

    enum

    The status of a feature flag in an environment. Allowed enum values: ENABLED,DISABLED

    json_schema

    string

    JSON schema for validation when value_type is JSON.

    key [required]

    string

    The unique key of the feature flag.

    last_updated_by

    uuid

    The ID of the user who last updated the feature flag.

    name [required]

    string

    The name of the feature flag.

    require_approval

    boolean

    Indicates whether this feature flag requires approval for changes.

    tags

    [string]

    Tags associated with the feature flag.

    updated_at

    date-time

    The timestamp when the feature flag was last updated.

    value_type [required]

    enum

    The type of values for the feature flag variants. Allowed enum values: BOOLEAN,INTEGER,NUMERIC,STRING,JSON

    variants [required]

    [object]

    The variants of the feature flag.

    created_at

    date-time

    The timestamp when the variant was created.

    id [required]

    uuid

    The unique identifier of the variant.

    key [required]

    string

    The unique key of the variant.

    name [required]

    string

    The name of the variant.

    updated_at

    date-time

    The timestamp when the variant was last updated.

    value [required]

    string

    The value of the variant as a string.

    id [required]

    uuid

    The unique identifier of the feature flag.

    type [required]

    enum

    The resource type. Allowed enum values: feature-flags

    {
  "data": {
    "attributes": {
      "archived_at": "2023-01-01T00:00:00Z",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440010",
      "description": "This is an example feature flag for demonstration",
      "distribution_channel": "ALL",
      "feature_flag_environments": [
        {
          "allocations": {},
          "default_allocation_key": "allocation-default-123abc",
          "default_variant_id": "550e8400-e29b-41d4-a716-446655440002",
          "environment_id": "550e8400-e29b-41d4-a716-446655440001",
          "environment_name": "env-search-term",
          "environment_queries": [
            "test-feature-flag",
            "env-search-term"
          ],
          "is_production": false,
          "override_allocation_key": "allocation-override-123abc",
          "override_variant_id": "550e8400-e29b-41d4-a716-446655440003",
          "pending_suggestion_id": "550e8400-e29b-41d4-a716-446655440099",
          "require_feature_flag_approval": false,
          "rollout_percentage": 0,
          "rules": [],
          "status": "ENABLED"
        }
      ],
      "json_schema": "{\"type\": \"object\", \"properties\": {\"enabled\": {\"type\": \"boolean\"}}}",
      "key": "feature-flag-abc123",
      "last_updated_by": "550e8400-e29b-41d4-a716-446655440010",
      "name": "Feature Flag ABC123",
      "require_approval": false,
      "tags": [
        []
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "value_type": "BOOLEAN",
      "variants": [
        {
          "created_at": "2023-01-01T00:00:00Z",
          "id": "550e8400-e29b-41d4-a716-446655440002",
          "key": "variant-abc123",
          "name": "Variant ABC123",
          "updated_at": "2023-01-01T00:00:00Z",
          "value": "true"
        }
      ]
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "feature-flags"
  }
}

    Bad Request

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Forbidden

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Not Found

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Code Example

                              # Path parameters
    export feature_flag_id="550e8400-e29b-41d4-a716-446655440000"
    # Curl command
    curl -X PUT "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/${feature_flag_id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": {
    "type": "feature-flags",
    "attributes": {
      "description": "Updated description for the feature flag",
      "name": "Updated Test Feature Flag Example-Feature-Flag"
    }
  }
}
EOF

    Get a feature flag

    GET https://api.ap1.datadoghq.com/api/v2/feature-flags/{feature_flag_id}https://api.ap2.datadoghq.com/api/v2/feature-flags/{feature_flag_id}https://api.datadoghq.eu/api/v2/feature-flags/{feature_flag_id}https://api.ddog-gov.com/api/v2/feature-flags/{feature_flag_id}https://api.datadoghq.com/api/v2/feature-flags/{feature_flag_id}https://api.us3.datadoghq.com/api/v2/feature-flags/{feature_flag_id}https://api.us5.datadoghq.com/api/v2/feature-flags/{feature_flag_id}

    Overview

    Returns the details of a specific feature flag including variants and environment status. This endpoint requires all of the following permissions:

  • feature_flag_config_read
  • feature_flag_environment_config_read

    • Arguments

    Path Parameters

    Name

    Type

    Description

    feature_flag_id [required]

    string

    The ID of the feature flag.

    Response

    OK

    Response containing a feature flag.

    Expand All

    Field

    Type

    Description

    data [required]

    object

    A feature flag resource.

    attributes [required]

    object

    Attributes of a feature flag.

    archived_at

    date-time

    The timestamp when the feature flag was archived.

    created_at

    date-time

    The timestamp when the feature flag was created.

    created_by

    uuid

    The ID of the user who created the feature flag.

    description [required]

    string

    The description of the feature flag.

    distribution_channel

    string

    Distribution channel for the feature flag.

    feature_flag_environments

    [object]

    Environment-specific settings for the feature flag.

    allocations

    object

    Allocation metadata for this environment.

    default_allocation_key

    string

    The allocation key used for the default variant.

    default_variant_id

    string

    The ID of the default variant for this environment.

    environment_id [required]

    uuid

    The ID of the environment.

    environment_name

    string

    The name of the environment.

    environment_queries

    [string]

    Queries that target this environment.

    is_production

    boolean

    Indicates whether the environment is production.

    override_allocation_key

    string

    The allocation key used for the override variant.

    override_variant_id

    string

    The ID of the override variant for this environment.

    pending_suggestion_id

    string

    Pending suggestion identifier, if approval is required.

    require_feature_flag_approval

    boolean

    Indicates whether feature flag changes require approval in this environment.

    rollout_percentage

    int64

    Rollout percentage for this environment.

    rules

    [object]

    Environment targeting rules for this feature flag.

    status [required]

    enum

    The status of a feature flag in an environment. Allowed enum values: ENABLED,DISABLED

    json_schema

    string

    JSON schema for validation when value_type is JSON.

    key [required]

    string

    The unique key of the feature flag.

    last_updated_by

    uuid

    The ID of the user who last updated the feature flag.

    name [required]

    string

    The name of the feature flag.

    require_approval

    boolean

    Indicates whether this feature flag requires approval for changes.

    tags

    [string]

    Tags associated with the feature flag.

    updated_at

    date-time

    The timestamp when the feature flag was last updated.

    value_type [required]

    enum

    The type of values for the feature flag variants. Allowed enum values: BOOLEAN,INTEGER,NUMERIC,STRING,JSON

    variants [required]

    [object]

    The variants of the feature flag.

    created_at

    date-time

    The timestamp when the variant was created.

    id [required]

    uuid

    The unique identifier of the variant.

    key [required]

    string

    The unique key of the variant.

    name [required]

    string

    The name of the variant.

    updated_at

    date-time

    The timestamp when the variant was last updated.

    value [required]

    string

    The value of the variant as a string.

    id [required]

    uuid

    The unique identifier of the feature flag.

    type [required]

    enum

    The resource type. Allowed enum values: feature-flags

    {
  "data": {
    "attributes": {
      "archived_at": "2023-01-01T00:00:00Z",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440010",
      "description": "This is an example feature flag for demonstration",
      "distribution_channel": "ALL",
      "feature_flag_environments": [
        {
          "allocations": {},
          "default_allocation_key": "allocation-default-123abc",
          "default_variant_id": "550e8400-e29b-41d4-a716-446655440002",
          "environment_id": "550e8400-e29b-41d4-a716-446655440001",
          "environment_name": "env-search-term",
          "environment_queries": [
            "test-feature-flag",
            "env-search-term"
          ],
          "is_production": false,
          "override_allocation_key": "allocation-override-123abc",
          "override_variant_id": "550e8400-e29b-41d4-a716-446655440003",
          "pending_suggestion_id": "550e8400-e29b-41d4-a716-446655440099",
          "require_feature_flag_approval": false,
          "rollout_percentage": 0,
          "rules": [],
          "status": "ENABLED"
        }
      ],
      "json_schema": "{\"type\": \"object\", \"properties\": {\"enabled\": {\"type\": \"boolean\"}}}",
      "key": "feature-flag-abc123",
      "last_updated_by": "550e8400-e29b-41d4-a716-446655440010",
      "name": "Feature Flag ABC123",
      "require_approval": false,
      "tags": [
        []
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "value_type": "BOOLEAN",
      "variants": [
        {
          "created_at": "2023-01-01T00:00:00Z",
          "id": "550e8400-e29b-41d4-a716-446655440002",
          "key": "variant-abc123",
          "name": "Variant ABC123",
          "updated_at": "2023-01-01T00:00:00Z",
          "value": "true"
        }
      ]
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "feature-flags"
  }
}

    Forbidden

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Not Found

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Code Example

                      # Path parameters
    export feature_flag_id="550e8400-e29b-41d4-a716-446655440000"
    # Curl command
    curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags/${feature_flag_id}" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

    Create a feature flag

    POST https://api.ap1.datadoghq.com/api/v2/feature-flagshttps://api.ap2.datadoghq.com/api/v2/feature-flagshttps://api.datadoghq.eu/api/v2/feature-flagshttps://api.ddog-gov.com/api/v2/feature-flagshttps://api.datadoghq.com/api/v2/feature-flagshttps://api.us3.datadoghq.com/api/v2/feature-flagshttps://api.us5.datadoghq.com/api/v2/feature-flags

    Overview

    Creates a new feature flag with variants. This endpoint requires all of the following permissions:

  • feature_flag_config_write
  • feature_flag_environment_config_read

    • Request

    Body Data (required)

    Expand All

    Field

    Type

    Description

    data [required]

    object

    Data for creating a new feature flag.

    attributes [required]

    object

    Attributes for creating a new feature flag.

    default_variant_key

    string

    The key of the default variant.

    description [required]

    string

    The description of the feature flag.

    json_schema

    string

    JSON schema for validation when value_type is JSON.

    key [required]

    string

    The unique key of the feature flag.

    name [required]

    string

    The name of the feature flag.

    value_type [required]

    enum

    The type of values for the feature flag variants. Allowed enum values: BOOLEAN,INTEGER,NUMERIC,STRING,JSON

    variants [required]

    [object]

    The variants of the feature flag.

    key [required]

    string

    The unique key of the variant.

    name [required]

    string

    The name of the variant.

    value [required]

    string

    The value of the variant as a string.

    type [required]

    enum

    The resource type. Allowed enum values: feature-flags

    {
  "data": {
    "type": "feature-flags",
    "attributes": {
      "default_variant_key": "variant-Example-Feature-Flag-1",
      "description": "Test feature flag for BDD scenarios",
      "key": "test-feature-flag-Example-Feature-Flag",
      "name": "Test Feature Flag Example-Feature-Flag",
      "value_type": "BOOLEAN",
      "variants": [
        {
          "key": "variant-Example-Feature-Flag-1",
          "name": "Variant Example-Feature-Flag A",
          "value": "true"
        },
        {
          "key": "variant-Example-Feature-Flag-2",
          "name": "Variant Example-Feature-Flag B",
          "value": "false"
        }
      ]
    }
  }
}

    Response

    Created

    Response containing a feature flag.

    Expand All

    Field

    Type

    Description

    data [required]

    object

    A feature flag resource.

    attributes [required]

    object

    Attributes of a feature flag.

    archived_at

    date-time

    The timestamp when the feature flag was archived.

    created_at

    date-time

    The timestamp when the feature flag was created.

    created_by

    uuid

    The ID of the user who created the feature flag.

    description [required]

    string

    The description of the feature flag.

    distribution_channel

    string

    Distribution channel for the feature flag.

    feature_flag_environments

    [object]

    Environment-specific settings for the feature flag.

    allocations

    object

    Allocation metadata for this environment.

    default_allocation_key

    string

    The allocation key used for the default variant.

    default_variant_id

    string

    The ID of the default variant for this environment.

    environment_id [required]

    uuid

    The ID of the environment.

    environment_name

    string

    The name of the environment.

    environment_queries

    [string]

    Queries that target this environment.

    is_production

    boolean

    Indicates whether the environment is production.

    override_allocation_key

    string

    The allocation key used for the override variant.

    override_variant_id

    string

    The ID of the override variant for this environment.

    pending_suggestion_id

    string

    Pending suggestion identifier, if approval is required.

    require_feature_flag_approval

    boolean

    Indicates whether feature flag changes require approval in this environment.

    rollout_percentage

    int64

    Rollout percentage for this environment.

    rules

    [object]

    Environment targeting rules for this feature flag.

    status [required]

    enum

    The status of a feature flag in an environment. Allowed enum values: ENABLED,DISABLED

    json_schema

    string

    JSON schema for validation when value_type is JSON.

    key [required]

    string

    The unique key of the feature flag.

    last_updated_by

    uuid

    The ID of the user who last updated the feature flag.

    name [required]

    string

    The name of the feature flag.

    require_approval

    boolean

    Indicates whether this feature flag requires approval for changes.

    tags

    [string]

    Tags associated with the feature flag.

    updated_at

    date-time

    The timestamp when the feature flag was last updated.

    value_type [required]

    enum

    The type of values for the feature flag variants. Allowed enum values: BOOLEAN,INTEGER,NUMERIC,STRING,JSON

    variants [required]

    [object]

    The variants of the feature flag.

    created_at

    date-time

    The timestamp when the variant was created.

    id [required]

    uuid

    The unique identifier of the variant.

    key [required]

    string

    The unique key of the variant.

    name [required]

    string

    The name of the variant.

    updated_at

    date-time

    The timestamp when the variant was last updated.

    value [required]

    string

    The value of the variant as a string.

    id [required]

    uuid

    The unique identifier of the feature flag.

    type [required]

    enum

    The resource type. Allowed enum values: feature-flags

    {
  "data": {
    "attributes": {
      "archived_at": "2023-01-01T00:00:00Z",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440010",
      "description": "This is an example feature flag for demonstration",
      "distribution_channel": "ALL",
      "feature_flag_environments": [
        {
          "allocations": {},
          "default_allocation_key": "allocation-default-123abc",
          "default_variant_id": "550e8400-e29b-41d4-a716-446655440002",
          "environment_id": "550e8400-e29b-41d4-a716-446655440001",
          "environment_name": "env-search-term",
          "environment_queries": [
            "test-feature-flag",
            "env-search-term"
          ],
          "is_production": false,
          "override_allocation_key": "allocation-override-123abc",
          "override_variant_id": "550e8400-e29b-41d4-a716-446655440003",
          "pending_suggestion_id": "550e8400-e29b-41d4-a716-446655440099",
          "require_feature_flag_approval": false,
          "rollout_percentage": 0,
          "rules": [],
          "status": "ENABLED"
        }
      ],
      "json_schema": "{\"type\": \"object\", \"properties\": {\"enabled\": {\"type\": \"boolean\"}}}",
      "key": "feature-flag-abc123",
      "last_updated_by": "550e8400-e29b-41d4-a716-446655440010",
      "name": "Feature Flag ABC123",
      "require_approval": false,
      "tags": [
        []
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "value_type": "BOOLEAN",
      "variants": [
        {
          "created_at": "2023-01-01T00:00:00Z",
          "id": "550e8400-e29b-41d4-a716-446655440002",
          "key": "variant-abc123",
          "name": "Variant ABC123",
          "updated_at": "2023-01-01T00:00:00Z",
          "value": "true"
        }
      ]
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "feature-flags"
  }
}

    Bad Request

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Forbidden

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Conflict

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Code Example

                              # Curl command
    curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": {
    "type": "feature-flags",
    "attributes": {
      "default_variant_key": "variant-Example-Feature-Flag-1",
      "description": "Test feature flag for BDD scenarios",
      "key": "test-feature-flag-Example-Feature-Flag",
      "name": "Test Feature Flag Example-Feature-Flag",
      "value_type": "BOOLEAN",
      "variants": [
        {
          "key": "variant-Example-Feature-Flag-1",
          "name": "Variant Example-Feature-Flag A",
          "value": "true"
        },
        {
          "key": "variant-Example-Feature-Flag-2",
          "name": "Variant Example-Feature-Flag B",
          "value": "false"
        }
      ]
    }
  }
}
EOF

    List feature flags

    GET https://api.ap1.datadoghq.com/api/v2/feature-flagshttps://api.ap2.datadoghq.com/api/v2/feature-flagshttps://api.datadoghq.eu/api/v2/feature-flagshttps://api.ddog-gov.com/api/v2/feature-flagshttps://api.datadoghq.com/api/v2/feature-flagshttps://api.us3.datadoghq.com/api/v2/feature-flagshttps://api.us5.datadoghq.com/api/v2/feature-flags

    Overview

    Returns a list of feature flags for the organization. Supports filtering by key and archived status. This endpoint requires all of the following permissions:

  • feature_flag_config_read
  • feature_flag_environment_config_read

    • Arguments

    Query Strings

    Name

    Type

    Description

    key

    string

    Filter feature flags by key (partial matching).

    is_archived

    boolean

    Filter by archived status.

    limit

    integer

    Maximum number of results to return.

    offset

    integer

    Number of results to skip.

    Response

    OK

    Response containing a list of feature flags.

    Expand All

    Field

    Type

    Description

    data [required]

    [object]

    List of feature flags.

    attributes [required]

    object

    Attributes of a feature flag.

    archived_at

    date-time

    The timestamp when the feature flag was archived.

    created_at

    date-time

    The timestamp when the feature flag was created.

    created_by

    uuid

    The ID of the user who created the feature flag.

    description [required]

    string

    The description of the feature flag.

    distribution_channel

    string

    Distribution channel for the feature flag.

    feature_flag_environments

    [object]

    Environment-specific settings for the feature flag.

    allocations

    object

    Allocation metadata for this environment.

    default_allocation_key

    string

    The allocation key used for the default variant.

    default_variant_id

    string

    The ID of the default variant for this environment.

    environment_id [required]

    uuid

    The ID of the environment.

    environment_name

    string

    The name of the environment.

    environment_queries

    [string]

    Queries that target this environment.

    is_production

    boolean

    Indicates whether the environment is production.

    override_allocation_key

    string

    The allocation key used for the override variant.

    override_variant_id

    string

    The ID of the override variant for this environment.

    pending_suggestion_id

    string

    Pending suggestion identifier, if approval is required.

    require_feature_flag_approval

    boolean

    Indicates whether feature flag changes require approval in this environment.

    rollout_percentage

    int64

    Rollout percentage for this environment.

    rules

    [object]

    Environment targeting rules for this feature flag.

    status [required]

    enum

    The status of a feature flag in an environment. Allowed enum values: ENABLED,DISABLED

    json_schema

    string

    JSON schema for validation when value_type is JSON.

    key [required]

    string

    The unique key of the feature flag.

    last_updated_by

    uuid

    The ID of the user who last updated the feature flag.

    name [required]

    string

    The name of the feature flag.

    require_approval

    boolean

    Indicates whether this feature flag requires approval for changes.

    tags

    [string]

    Tags associated with the feature flag.

    updated_at

    date-time

    The timestamp when the feature flag was last updated.

    value_type [required]

    enum

    The type of values for the feature flag variants. Allowed enum values: BOOLEAN,INTEGER,NUMERIC,STRING,JSON

    variants [required]

    [object]

    The variants of the feature flag.

    created_at

    date-time

    The timestamp when the variant was created.

    id [required]

    uuid

    The unique identifier of the variant.

    key [required]

    string

    The unique key of the variant.

    name [required]

    string

    The name of the variant.

    updated_at

    date-time

    The timestamp when the variant was last updated.

    value [required]

    string

    The value of the variant as a string.

    id [required]

    uuid

    The unique identifier of the feature flag.

    type [required]

    enum

    The resource type. Allowed enum values: feature-flags

    meta

    object

    Pagination metadata for feature flags.

    page

    object

    Pagination metadata for feature flags list responses.

    total_count

    int64

    Total number of items.

    total_filtered_count

    int64

    Total number of items matching the filter.

    {
  "data": [
    {
      "attributes": {
        "archived_at": "2023-01-01T00:00:00Z",
        "created_at": "2023-01-01T00:00:00Z",
        "created_by": "550e8400-e29b-41d4-a716-446655440010",
        "description": "This is an example feature flag for demonstration",
        "distribution_channel": "ALL",
        "feature_flag_environments": [
          {
            "allocations": {},
            "default_allocation_key": "allocation-default-123abc",
            "default_variant_id": "550e8400-e29b-41d4-a716-446655440002",
            "environment_id": "550e8400-e29b-41d4-a716-446655440001",
            "environment_name": "env-search-term",
            "environment_queries": [
              "test-feature-flag",
              "env-search-term"
            ],
            "is_production": false,
            "override_allocation_key": "allocation-override-123abc",
            "override_variant_id": "550e8400-e29b-41d4-a716-446655440003",
            "pending_suggestion_id": "550e8400-e29b-41d4-a716-446655440099",
            "require_feature_flag_approval": false,
            "rollout_percentage": 0,
            "rules": [],
            "status": "ENABLED"
          }
        ],
        "json_schema": "{\"type\": \"object\", \"properties\": {\"enabled\": {\"type\": \"boolean\"}}}",
        "key": "feature-flag-abc123",
        "last_updated_by": "550e8400-e29b-41d4-a716-446655440010",
        "name": "Feature Flag ABC123",
        "require_approval": false,
        "tags": [
          []
        ],
        "updated_at": "2023-01-01T00:00:00Z",
        "value_type": "BOOLEAN",
        "variants": [
          {
            "created_at": "2023-01-01T00:00:00Z",
            "id": "550e8400-e29b-41d4-a716-446655440002",
            "key": "variant-abc123",
            "name": "Variant ABC123",
            "updated_at": "2023-01-01T00:00:00Z",
            "value": "true"
          }
        ]
      },
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "feature-flags"
    }
  ],
  "meta": {
    "page": {
      "total_count": 100,
      "total_filtered_count": 25
    }
  }
}

    Forbidden

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
  "errors": [
    "Bad Request"
  ]
}

    Code Example

                      # Curl command
    curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/feature-flags" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"