The Amplitude Experiment Management API provides programmatic control over feature flags and experiments. It supports creating, updating, activating, and archiving experiments and flags, as well as managing deployments, variants, holdout groups, and mutual exclusion groups. This API enables teams to integrate experiment lifecycle management into their CI/CD pipelines, automate flag rollouts, and manage experimentation workflows without using the Amplitude UI.
openapi: 3.1.0
info:
title: Amplitude Experiment Management API
description: >-
The Amplitude Experiment Management API provides programmatic control
over feature flags and experiments. It supports creating, updating,
activating, and archiving experiments and flags, as well as managing
deployments, variants, holdout groups, and mutual exclusion groups.
This API enables teams to integrate experiment lifecycle management
into their CI/CD pipelines, automate flag rollouts, and manage
experimentation workflows without using the Amplitude UI.
version: '1'
contact:
name: Amplitude Support
url: https://amplitude.com/contact
termsOfService: https://amplitude.com/terms
externalDocs:
description: Amplitude Experiment Management API Documentation
url: https://amplitude.com/docs/apis/experiment/experiment-management-api
servers:
- url: https://experiment.amplitude.com
description: Amplitude Experiment Management Server
tags:
- name: Deployments
description: Deployment management operations
- name: Experiments
description: Experiment management operations
- name: Flags
description: Feature flag management operations
- name: Versions
description: Flag and experiment version history operations
security:
- bearerAuth: []
paths:
/api/1/flags:
get:
operationId: listFlags
summary: Amplitude List All Flags
description: >-
Retrieve a list of all feature flags in the project. Returns flag
metadata including status, variants, and deployment information.
tags:
- Flags
parameters:
- name: limit
in: query
description: >-
The maximum number of flags to return.
schema:
type: integer
- name: cursor
in: query
description: >-
A cursor for pagination returned from a previous request.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/FlagListResponse'
examples:
listFlags200Example:
summary: Default listFlags 200 response
x-microcks-default: true
value:
flags:
- example_value
nextCursor: example_value
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createFlag
summary: Amplitude Create a Flag
description: >-
Create a new feature flag with the specified key, variants, and
targeting configuration.
tags:
- Flags
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFlagRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Flag'
examples:
createFlag200Example:
summary: Default createFlag 200 response
x-microcks-default: true
value:
id: '500123'
projectId: '500123'
key: example_value
name: Example Name
description: Example description text
enabled: true
evaluationMode: local
bucketingKey: example_value
bucketingSalt: example_value
variants:
- example_value
deployments:
- example_value
segments:
- example_value
state: draft
'400':
description: Bad request - invalid flag configuration
'401':
description: Unauthorized
'409':
description: Flag key already exists
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/1/flags/{id}:
get:
operationId: getFlag
summary: Amplitude Get a Flag
description: >-
Retrieve a single feature flag by its ID including full configuration
details such as deployments, variants, and targeting segments.
tags:
- Flags
parameters:
- $ref: '#/components/parameters/flagId'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Flag'
examples:
getFlag200Example:
summary: Default getFlag 200 response
x-microcks-default: true
value:
id: '500123'
projectId: '500123'
key: example_value
name: Example Name
description: Example description text
enabled: true
evaluationMode: local
bucketingKey: example_value
bucketingSalt: example_value
variants:
- example_value
deployments:
- example_value
segments:
- example_value
state: draft
'401':
description: Unauthorized
'404':
description: Flag not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
operationId: updateFlag
summary: Amplitude Update a Flag
description: >-
Update an existing feature flag's configuration. Only the fields
included in the request body are updated.
tags:
- Flags
parameters:
- $ref: '#/components/parameters/flagId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFlagRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Flag'
examples:
updateFlag200Example:
summary: Default updateFlag 200 response
x-microcks-default: true
value:
id: '500123'
projectId: '500123'
key: example_value
name: Example Name
description: Example description text
enabled: true
evaluationMode: local
bucketingKey: example_value
bucketingSalt: example_value
variants:
- example_value
deployments:
- example_value
segments:
- example_value
state: draft
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Flag not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/1/experiments:
get:
operationId: listExperiments
summary: Amplitude List All Experiments
description: >-
Retrieve a list of all experiments in the project. Returns experiment
metadata including status, variants, and deployment information.
tags:
- Experiments
parameters:
- name: limit
in: query
description: >-
The maximum number of experiments to return.
schema:
type: integer
- name: cursor
in: query
description: >-
A cursor for pagination.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ExperimentListResponse'
examples:
listExperiments200Example:
summary: Default listExperiments 200 response
x-microcks-default: true
value:
experiments:
- example_value
nextCursor: example_value
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createExperiment
summary: Amplitude Create an Experiment
description: >-
Create a new A/B test experiment with the specified key, variants,
and targeting configuration.
tags:
- Experiments
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateExperimentRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Experiment'
examples:
createExperiment200Example:
summary: Default createExperiment 200 response
x-microcks-default: true
value:
id: '500123'
projectId: '500123'
key: example_value
name: Example Name
description: Example description text
enabled: true
evaluationMode: local
bucketingKey: example_value
bucketingSalt: example_value
variants:
- example_value
deployments:
- example_value
segments:
- example_value
state: draft
rolledOutVariant: example_value
startDate: '2025-03-15T14:30:00Z'
endDate: '2025-03-15T14:30:00Z'
'400':
description: Bad request
'401':
description: Unauthorized
'409':
description: Experiment key already exists
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/1/experiments/{id}:
get:
operationId: getExperiment
summary: Amplitude Get an Experiment
description: >-
Retrieve a single experiment by its ID including full configuration
details.
tags:
- Experiments
parameters:
- $ref: '#/components/parameters/experimentId'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Experiment'
examples:
getExperiment200Example:
summary: Default getExperiment 200 response
x-microcks-default: true
value:
id: '500123'
projectId: '500123'
key: example_value
name: Example Name
description: Example description text
enabled: true
evaluationMode: local
bucketingKey: example_value
bucketingSalt: example_value
variants:
- example_value
deployments:
- example_value
segments:
- example_value
state: draft
rolledOutVariant: example_value
startDate: '2025-03-15T14:30:00Z'
endDate: '2025-03-15T14:30:00Z'
'401':
description: Unauthorized
'404':
description: Experiment not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
operationId: updateExperiment
summary: Amplitude Update an Experiment
description: >-
Update an existing experiment's configuration.
tags:
- Experiments
parameters:
- $ref: '#/components/parameters/experimentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateExperimentRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Experiment'
examples:
updateExperiment200Example:
summary: Default updateExperiment 200 response
x-microcks-default: true
value:
id: '500123'
projectId: '500123'
key: example_value
name: Example Name
description: Example description text
enabled: true
evaluationMode: local
bucketingKey: example_value
bucketingSalt: example_value
variants:
- example_value
deployments:
- example_value
segments:
- example_value
state: draft
rolledOutVariant: example_value
startDate: '2025-03-15T14:30:00Z'
endDate: '2025-03-15T14:30:00Z'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Experiment not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/1/deployments:
get:
operationId: listDeployments
summary: Amplitude List All Deployments
description: >-
Retrieve a list of all deployments that experiments and flags can
be assigned to. Deployments represent environments or platforms
where flags are evaluated.
tags:
- Deployments
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentListResponse'
examples:
listDeployments200Example:
summary: Default listDeployments 200 response
x-microcks-default: true
value:
deployments:
- example_value
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/1/deployments/{id}:
get:
operationId: getDeployment
summary: Amplitude Get a Deployment
description: >-
Retrieve a single deployment by its ID.
tags:
- Deployments
parameters:
- name: id
in: path
required: true
description: >-
The unique identifier of the deployment.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Deployment'
examples:
getDeployment200Example:
summary: Default getDeployment 200 response
x-microcks-default: true
value:
id: '500123'
projectId: '500123'
label: example_value
key: example_value
deleted: true
'401':
description: Unauthorized
'404':
description: Deployment not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/1/versions:
get:
operationId: listVersions
summary: Amplitude List Flag and Experiment Versions
description: >-
Retrieve the version history for flags and experiments. Returns
a paginated list of version records with change details.
tags:
- Versions
parameters:
- name: limit
in: query
description: >-
The maximum number of versions to return.
schema:
type: integer
- name: cursor
in: query
description: >-
A cursor for pagination.
schema:
type: string
- name: start
in: query
description: >-
The start date for filtering versions.
schema:
type: string
format: date
- name: end
in: query
description: >-
The end date for filtering versions.
schema:
type: string
format: date
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/VersionListResponse'
examples:
listVersions200Example:
summary: Default listVersions 200 response
x-microcks-default: true
value:
versions:
- id: {}
flagId: {}
version: {}
createdAt: {}
createdBy: {}
nextCursor: example_value
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Use a Management API key generated in the Experiment sidebar of the
Amplitude UI. Pass it in the Authorization header as Bearer
YOUR_MANAGEMENT_API_KEY.
parameters:
flagId:
name: id
in: path
required: true
description: >-
The unique identifier of the feature flag.
schema:
type: string
experimentId:
name: id
in: path
required: true
description: >-
The unique identifier of the experiment.
schema:
type: string
schemas:
FlagListResponse:
type: object
properties:
flags:
type: array
description: >-
Array of feature flag objects.
items:
$ref: '#/components/schemas/Flag'
nextCursor:
type: string
description: >-
A cursor for fetching the next page of results.
Flag:
type: object
properties:
id:
type: string
description: >-
The unique identifier for the flag.
projectId:
type: string
description: >-
The project ID the flag belongs to.
key:
type: string
description: >-
The unique key used to reference the flag in code.
name:
type: string
description: >-
The display name of the flag.
description:
type: string
description: >-
A description of the flag's purpose.
enabled:
type: boolean
description: >-
Whether the flag is enabled.
evaluationMode:
type: string
description: >-
The evaluation mode, either local or remote.
enum:
- local
- remote
bucketingKey:
type: string
description: >-
The property used for bucketing users into variants.
bucketingSalt:
type: string
description: >-
The salt used for hashing during bucketing.
variants:
type: array
description: >-
Array of variant configurations.
items:
$ref: '#/components/schemas/VariantConfig'
deployments:
type: array
description: >-
Array of deployment IDs the flag is deployed to.
items:
type: string
segments:
type: array
description: >-
Array of targeting segment configurations.
items:
$ref: '#/components/schemas/Segment'
state:
type: string
description: >-
The current state of the flag.
enum:
- draft
- active
- archived
CreateFlagRequest:
type: object
required:
- key
properties:
key:
type: string
description: >-
The unique key for the flag.
name:
type: string
description: >-
The display name of the flag.
description:
type: string
description: >-
A description of the flag's purpose.
variants:
type: array
description: >-
Array of variant configurations.
items:
$ref: '#/components/schemas/VariantConfig'
bucketingKey:
type: string
description: >-
The property used for bucketing.
UpdateFlagRequest:
type: object
properties:
name:
type: string
description: >-
The updated display name.
description:
type: string
description: >-
The updated description.
enabled:
type: boolean
description: >-
Whether the flag should be enabled.
variants:
type: array
description: >-
Updated variant configurations.
items:
$ref: '#/components/schemas/VariantConfig'
segments:
type: array
description: >-
Updated targeting segment configurations.
items:
$ref: '#/components/schemas/Segment'
ExperimentListResponse:
type: object
properties:
experiments:
type: array
description: >-
Array of experiment objects.
items:
$ref: '#/components/schemas/Experiment'
nextCursor:
type: string
description: >-
A cursor for fetching the next page.
Experiment:
type: object
properties:
id:
type: string
description: >-
The unique identifier for the experiment.
projectId:
type: string
description: >-
The project ID the experiment belongs to.
key:
type: string
description: >-
The unique key used to reference the experiment in code.
name:
type: string
description: >-
The display name of the experiment.
description:
type: string
description: >-
A description of the experiment's purpose.
enabled:
type: boolean
description: >-
Whether the experiment is enabled.
evaluationMode:
type: string
description: >-
The evaluation mode, either local or remote.
enum:
- local
- remote
bucketingKey:
type: string
description: >-
The property used for bucketing.
bucketingSalt:
type: string
description: >-
The salt used for hashing.
variants:
type: array
description: >-
Array of variant configurations including control and treatment
groups.
items:
$ref: '#/components/schemas/VariantConfig'
deployments:
type: array
description: >-
Array of deployment IDs.
items:
type: string
segments:
type: array
description: >-
Array of targeting segments.
items:
$ref: '#/components/schemas/Segment'
state:
type: string
description: >-
The current state of the experiment.
enum:
- draft
- running
- stopped
- archived
rolledOutVariant:
type: string
description: >-
The variant key that was rolled out, if the experiment has
concluded.
startDate:
type: string
format: date-time
description: >-
The date and time the experiment started running.
endDate:
type: string
format: date-time
description: >-
The date and time the experiment stopped running.
CreateExperimentRequest:
type: object
required:
- key
properties:
key:
type: string
description: >-
The unique key for the experiment.
name:
type: string
description: >-
The display name of the experiment.
description:
type: string
description: >-
A description of the experiment.
variants:
type: array
description: >-
Array of variant configurations.
items:
$ref: '#/components/schemas/VariantConfig'
bucketingKey:
type: string
description: >-
The property used for bucketing.
UpdateExperimentRequest:
type: object
properties:
name:
type: string
description: >-
The updated display name.
description:
type: string
description: >-
The updated description.
enabled:
type: boolean
description: >-
Whether the experiment should be enabled.
variants:
type: array
description: >-
Updated variant configurations.
items:
$ref: '#/components/schemas/VariantConfig'
segments:
type: array
description: >-
Updated targeting segments.
items:
$ref: '#/components/schemas/Segment'
VariantConfig:
type: object
properties:
key:
type: string
description: >-
The unique key for the variant.
name:
type: string
description: >-
The display name of the variant.
payload:
description: >-
An optional JSON payload associated with the variant.
description:
type: string
description: >-
A description of what this variant does.
rolloutWeight:
type: integer
description: >-
The rollout weight as a percentage (0-100) controlling traffic
allocation to this variant.
minimum: 0
maximum: 100
Segment:
type: object
properties:
name:
type: string
description: >-
The display name of the segment.
conditions:
type: array
description: >-
Array of targeting conditions that define this segment.
items:
type: object
properties:
type:
type: string
description: >-
The condition type.
prop:
type: string
description: >-
The property to evaluate.
op:
type: string
description: >-
The comparison operator.
values:
type: array
description: >-
The values to compare against.
items:
type: string
variant:
type: string
description: >-
The variant key to assign when this segment matches.
percentage:
type: integer
description: >-
The percentage of matching users to include (0-100).
minimum: 0
maximum: 100
DeploymentListResponse:
type: object
properties:
deployments:
type: array
description: >-
Array of deployment objects.
items:
$ref: '#/components/schemas/Deployment'
Deployment:
type: object
properties:
id:
type: string
description: >-
The unique identifier for the deployment.
projectId:
type: string
description: >-
The project the deployment belongs to.
label:
type: string
description: >-
The display label for the deployment.
key:
type: string
description: >-
The deployment key used for API authentication.
deleted:
type: boolean
description: >-
Whether the deployment has been deleted.
VersionListResponse:
type: object
properties:
versions:
type: array
description: >-
Array of version records.
items:
type: object
properties:
id:
type: string
description: >-
The version record ID.
flagId:
type: string
description: >-
The flag or experiment ID.
version:
type: integer
description: >-
The version number.
createdAt:
type: string
format: date-time
description: >-
The date and time the version was created.
createdBy:
type: string
description: >-
The user who created this version.
nextCursor:
type: string
description: >-
A cursor for fetching the next page.