Amplitude Evaluation API

openapi: 3.1.0
info:
  title: Amplitude Attribution Annotations Evaluation API
  description: The Amplitude Attribution API allows developers to send attribution campaign events to Amplitude from ad networks, attribution providers, or custom marketing tools. It associates users with the campaigns, channels, and creatives that drove their acquisition or re-engagement. This API is used to enrich Amplitude user profiles with marketing attribution data for campaign performance analysis and ROI measurement.
  version: '2'
  contact:
    name: Amplitude Support
    url: https://amplitude.com/contact
  termsOfService: https://amplitude.com/terms
servers:
- url: https://api2.amplitude.com
  description: Amplitude US Production Server
- url: https://api.eu.amplitude.com
  description: Amplitude EU Production Server
security: []
tags:
- name: Evaluation
  description: Remote flag and experiment evaluation operations
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
components:
  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
    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.
    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'
externalDocs:
  description: Amplitude Attribution API Documentation
  url: https://amplitude.com/docs/apis/analytics/attribution