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.