Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors Examples See Also

CreateExperimentDefinition

Creates an experiment definition in AWS AppConfig. An experiment definition describes the purpose, scope, and operational configuration of an experiment, including the target audience, feature flag, and treatment configurations.

Request Syntax


POST /applications/ApplicationIdentifier/experimentdefinitions HTTP/1.1
Content-type: application/json

{
   "AudienceDescription": "string",
   "AudienceRule": "string",
   "ConfigurationProfileIdentifier": "string",
   "Control": { 
      "Description": "string",
      "FlagValue": { 
         "AttributeValues": { 
            "string" : { ... }
         },
         "Enabled": boolean
      },
      "Weight": number
   },
   "EnvironmentIdentifier": "string",
   "FlagKey": "string",
   "Hypothesis": "string",
   "LaunchCriteria": "string",
   "Name": "string",
   "Tags": { 
      "string" : "string" 
   },
   "Treatments": [ 
      { 
         "Description": "string",
         "FlagValue": { 
            "AttributeValues": { 
               "string" : { ... }
            },
            "Enabled": boolean
         },
         "Weight": number
      }
   ]
}

URI Request Parameters

The request uses the following URI parameters.

ApplicationIdentifier

The application ID or name.

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

Request Body

The request accepts the following data in JSON format.

AudienceDescription

A description of the intended audience for the experiment.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1024.

Required: No

AudienceRule

A rule that defines which users are eligible to be assigned to treatments during the experiment.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 16384.

Required: Yes

ConfigurationProfileIdentifier

The configuration profile ID or name that stores the feature flag.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

Control

The control treatment that represents the baseline experience for comparison.

Type: TreatmentInput object

Required: Yes

EnvironmentIdentifier

The environment ID or name where the experiment will run.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

FlagKey

The key of the existing feature flag to use with the experiment.

Type: String

Pattern: ^[a-z][a-zA-Z0-9_-]{1,64}

Required: Yes

Hypothesis

A description of the goal or hypothesis the experiment is designed to validate.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1024.

Required: No

LaunchCriteria

Information about the conditions under which you would launch the winning treatment.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1024.

Required: No

Name

A name for the experiment definition.

Type: String

Pattern: ^(?!AWS\.).{1,64}$

Required: Yes

Tags

The tags to assign to the experiment definition. Tags help organize and categorize your AWS AppConfig resources.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Value Length Constraints: Maximum length of 256.

Required: No

Treatments

A list of treatments to evaluate during the experiment. Each treatment defines a distinct variation compared to the control.

Type: Array of TreatmentInput objects

Array Members: Minimum number of 1 item. Maximum number of 5 items.

Required: Yes

Response Syntax


HTTP/1.1 201
Content-type: application/json

{
   "ApplicationId": "string",
   "AudienceDescription": "string",
   "AudienceRule": "string",
   "ConfigurationProfileId": "string",
   "Control": { 
      "Description": "string",
      "FlagValue": { 
         "AttributeValues": { 
            "string" : { ... }
         },
         "Enabled": boolean
      },
      "Key": "string",
      "Weight": number
   },
   "CreatedAt": "string",
   "EnvironmentId": "string",
   "FlagKey": "string",
   "Hypothesis": "string",
   "Id": "string",
   "KmsKeyIdentifier": "string",
   "LaunchCriteria": "string",
   "Name": "string",
   "Status": "string",
   "Treatments": [ 
      { 
         "Description": "string",
         "FlagValue": { 
            "AttributeValues": { 
               "string" : { ... }
            },
            "Enabled": boolean
         },
         "Key": "string",
         "Weight": number
      }
   ],
   "UpdatedAt": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 201 response.

The following data is returned in JSON format by the service.

ApplicationId

The application ID.

Type: String

Pattern: [a-z0-9]{4,7}

AudienceDescription

A description of the intended audience for the experiment.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1024.

AudienceRule

The rule that defines which users are eligible to be assigned to treatments.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 16384.

ConfigurationProfileId

The configuration profile ID associated with the experiment.

Type: String

Pattern: [a-z0-9]{4,7}

Control

The control treatment used as the baseline for comparison.

Type: Treatment object

CreatedAt

The date and time the experiment definition was created, in ISO 8601 format.

Type: Timestamp

EnvironmentId

The environment ID where the experiment runs.

Type: String

Pattern: [a-z0-9]{4,7}

FlagKey

The key of the feature flag used by the experiment.

Type: String

Pattern: ^[a-z][a-zA-Z0-9_-]{1,64}

Hypothesis

The hypothesis that the experiment is designed to validate.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1024.

Id

The experiment definition ID.

Type: String

Pattern: [a-z0-9]{4,7}

KmsKeyIdentifier

The Amazon Resource Name (ARN) of the AWS KMS key used to encrypt experiment data.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

LaunchCriteria

The conditions under which the winning treatment should be launched.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1024.

Name

The name of the experiment definition.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Status

The current status of the experiment definition. Valid values: ACTIVE, IDLE, ARCHIVED.

Type: String

Valid Values: ACTIVE | IDLE | ARCHIVED

Treatments

The list of treatments defined for the experiment.

Type: Array of Treatment objects

Array Members: Minimum number of 1 item. Maximum number of 5 items.

UpdatedAt

The date and time the experiment definition was last updated, in ISO 8601 format.

Type: Timestamp

Errors

For information about the errors that are common to all actions, see Common Error Types.

BadRequestException

The input fails to satisfy the constraints specified by an AWS service.

Details: Detailed information about the input that failed to satisfy the constraints specified by a call.

HTTP Status Code: 400

ConflictException

The request could not be processed because of conflict in the current state of the resource.

HTTP Status Code: 409

InternalServerException

There was an internal failure in the AWS AppConfig service.

HTTP Status Code: 500

ResourceNotFoundException

The requested resource could not be found.

HTTP Status Code: 404

ServiceQuotaExceededException

The number of one more AWS AppConfig resources exceeds the maximum allowed. Verify that your environment doesn't exceed the following service quotas:

Applications: 100 max

To resolve this issue, you can delete one or more resources and try again. Or, you can request a quota increase. For more information about quotas and to request an increase, see Service quotas for AWS AppConfig in the Amazon Web Services General Reference.

HTTP Status Code: 402

Examples

Example

This example illustrates one usage of CreateExperimentDefinition.

Sample Request


POST /applications/abc1234/experimentdefinitions HTTP/1.1
Host: appconfig.us-east-1.amazonaws.com
Content-Type: application/json
User-Agent: aws-cli
X-Amz-Date: 20210916T175455Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20210916/us-east-1/appconfig/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=39c3b3042cd2aEXAMPLE
Content-Length: 306

{
	"Name": "Example-Experiment-Definition",
	"ConfigurationProfileIdentifier": "ur8hx2f",
	"EnvironmentIdentifier": "env1234",
	"FlagKey": "my-feature-flag",
	"Treatments": [
		{
			"Weight": 50,
			"FlagValue": {
				"Enabled": true
			}
		}
	],
	"Control": {
		"Weight": 50,
		"FlagValue": {
			"Enabled": false
		}
	},
	"AudienceRule": "(eq $country \"US\")"
}

Sample Response


{
	"ApplicationId": "abc1234",
	"AudienceRule": "(eq $country \"US\")",
	"ConfigurationProfileId": "ur8hx2f",
	"Control": {
		"FlagValue": {
			"Enabled": false
		},
		"Key": "c",
		"Weight": 50.0
	},
	"CreatedAt": "2026-06-16T17:54:55.847Z",
	"EnvironmentId": "env1234",
	"FlagKey": "my-feature-flag",
	"Id": "bsxyd7k",
	"Name": "Example-Experiment-Definition",
	"Status": "IDLE",
	"Treatments": [
		{
			"FlagValue": {
				"Enabled": true
			},
			"Key": "t1",
			"Weight": 50.0
		}
	],
	"UpdatedAt": "2026-06-16T17:54:55.847Z"
}