The Amplitude Experiment Evaluation API retrieves variant assignment data for users through remote evaluation. When called, it evaluates targeting rules and returns the assigned variant for each active experiment or feature flag. The API also tracks assignment events automatically in Amplitude Analytics. It is used by server-side applications that need to determine which experiment variant or feature flag value to serve to a given user in real time.
openapi: 3.1.0
info:
title: Amplitude Experiment Evaluation API
description: >-
The Amplitude Experiment Evaluation API retrieves variant assignment data
for users through remote evaluation. When called, it evaluates targeting
rules and returns the assigned variant for each active experiment or
feature flag. The API also tracks assignment events automatically in
Amplitude Analytics. It is used by server-side applications that need
to determine which experiment variant or feature flag value to serve
to a given user in real time.
version: '1'
contact:
name: Amplitude Support
url: https://amplitude.com/contact
termsOfService: https://amplitude.com/terms
externalDocs:
description: Amplitude Experiment Evaluation API Documentation
url: https://amplitude.com/docs/apis/experiment/experiment-evaluation-api
servers:
- url: https://api.lab.amplitude.com
description: Amplitude Experiment Evaluation Server
tags:
- name: Evaluation
description: Remote flag and experiment evaluation operations
- name: Flags
description: Flag configuration retrieval for local evaluation
security:
- apiKeyAuth: []
paths:
/v1/vardata:
post:
operationId: evaluateVariants
summary: Amplitude Evaluate Variants for a User
description: >-
Remotely evaluate all active experiments and feature flags for a
specific user. Returns the variant assignments based on the user's
properties and targeting rules. Amplitude automatically tracks an
Experiment Assignment event for each evaluation.
tags:
- Evaluation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluationRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluationResponse'
examples:
evaluateVariants200Example:
summary: Default evaluateVariants 200 response
x-microcks-default: true
value: {}
'400':
description: Bad request - missing user context
'401':
description: Unauthorized - invalid deployment key
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
get:
operationId: evaluateVariantsGet
summary: Amplitude Evaluate Variants for a User via GET
description: >-
Remotely evaluate all active experiments and feature flags for a
user identified by query parameters. Returns variant assignments
based on targeting rules.
tags:
- Evaluation
parameters:
- name: user_id
in: query
description: >-
The user ID to evaluate variants for.
schema:
type: string
- name: device_id
in: query
description: >-
The device ID to evaluate variants for.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluationResponse'
examples:
evaluateVariantsGet200Example:
summary: Default evaluateVariantsGet 200 response
x-microcks-default: true
value: {}
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v1/flags:
get:
operationId: getFlags
summary: Amplitude Get Flag Configurations
description: >-
Download all flag configurations for local evaluation. This endpoint
returns the full flag configuration including targeting rules,
variants, and segment definitions. Useful for bootstrapping
client-side local evaluation SDKs with initialFlags or running
evaluation in edge environments.
tags:
- Flags
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
description: >-
Array of flag configuration objects.
items:
$ref: '#/components/schemas/FlagConfiguration'
examples:
getFlags200Example:
summary: Default getFlags 200 response
x-microcks-default: true
value:
- example_value
'401':
description: Unauthorized - invalid deployment key
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
Pass your deployment key in the Authorization header with the prefix
Api-Key, for example Api-Key YOUR_DEPLOYMENT_KEY.
schemas:
EvaluationRequest:
type: object
properties:
user_id:
type: string
description: >-
The user ID to evaluate experiments and flags for.
device_id:
type: string
description: >-
The device ID to evaluate experiments and flags for.
user_properties:
type: object
description: >-
User properties to use for targeting rule evaluation.
additionalProperties: true
groups:
type: object
description: >-
Group type to group name mappings for group-level targeting.
additionalProperties: true
group_properties:
type: object
description: >-
Group properties to use for targeting rule evaluation.
additionalProperties: true
EvaluationResponse:
type: object
description: >-
A map of flag keys to variant objects representing the evaluated
variant assignments for the user.
additionalProperties:
$ref: '#/components/schemas/Variant'
Variant:
type: object
properties:
key:
type: string
description: >-
The variant key identifying this variant.
value:
type: string
description: >-
The variant value or payload.
payload:
description: >-
An optional JSON payload associated with the variant.
metadata:
type: object
description: >-
Metadata about the variant assignment.
properties:
experimentKey:
type: string
description: >-
The key of the experiment that assigned this variant.
flagType:
type: string
description: >-
The type of flag, such as experiment or release.
flagVersion:
type: integer
description: >-
The version of the flag configuration.
default:
type: boolean
description: >-
Whether this is the default variant.
FlagConfiguration:
type: object
properties:
key:
type: string
description: >-
The unique key identifying the flag.
metadata:
type: object
description: >-
Metadata about the flag configuration.
properties:
deployed:
type: boolean
description: >-
Whether the flag is currently deployed.
evaluationMode:
type: string
description: >-
The evaluation mode, either local or remote.
flagType:
type: string
description: >-
The type of flag, such as experiment or release.
flagVersion:
type: integer
description: >-
The version of the flag configuration.
segments:
type: array
description: >-
Array of targeting segments for this flag.
items:
type: object
properties:
conditions:
type: array
description: >-
Array of targeting conditions.
items:
type: object
additionalProperties: true
variant:
type: string
description: >-
The variant key to assign when conditions are met.
variants:
type: object
description: >-
Map of variant keys to variant configuration objects.
additionalProperties:
type: object
properties:
key:
type: string
description: >-
The variant key.
payload:
description: >-
Optional payload for the variant.