Convert Experience Variations API

openapi: 3.2.0
info:
  title: Convert Accounts Experience Variations API
  description: 'Move your app forward with the Convert API. The Convert API allows

    you to manage your Convert Experiences projects using code. The REST API is

    an interface for managing and extending functionality of Convert. For

    example, instead of creating and maintaining projects using the Convert

    Experiences web dashboard you can create an experiment programmatically.

    Additionally, if you prefer to run custom analysis on experiment results you

    can leverage the API to pull data from Convert Experiences into your own

    workflow. If you do not have a Convert account already, sign up for a free

    developer account at https://www.convert.com/api/.


    *[Convert API V1](/doc/v1) is still available and documentation can be found [here](/doc/v1) but using it is highly discouraged

    as it will be phased out in the future*

    '
  version: 2.0.0
servers:
- url: https://api.convert.com/api/v2
  description: Live API server
- url: https://apidev.convert.com/api/v2
  description: DEV API server
- url: http://apidev.convert.com:5000/api/v2
  description: DEV mocked API server
tags:
- name: Experience Variations
  description: 'Each **Experience** has one or more **Variations** which are presented to different groups of visitor

    in order to monitor the results of different changes or to personalize visitor''s experience

    '
paths:
  /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/variations/{variation_id}/update:
    put:
      operationId: updateExperienceVariation
      summary: Update an experience variation
      description: 'Modifies an existing variation within an experience.

        This can include changing its name, description, traffic distribution, status (running/stopped), or the actual changes (CSS, JS, HTML modifications) it applies.

        The Knowledge Base article "How do I edit my variations?" covers the UI aspect.

        '
      tags:
      - Experience Variations
      parameters:
      - name: account_id
        in: path
        required: true
        description: ID of the account that owns the retrieved/saved data
        schema:
          type: integer
      - name: project_id
        description: ID of the project to which save/retrieved data is connected
        in: path
        required: true
        schema:
          type: integer
      - name: experience_id
        description: The ID of the updated experience
        in: path
        required: true
        schema:
          type: integer
      - name: variation_id
        description: The ID of the variation to be updated
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/UpdateExperienceVariationRequest'
      responses:
        '200':
          $ref: '#/components/responses/ExperienceVariationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/variations/{variation_id}/delete:
    delete:
      operationId: deleteExperienceVariation
      summary: Delete an experience variation
      description: 'Permanently removes a variation from an experience.

        Note: Deleting variations from an active or previously active experiment can impact statistical validity and is generally discouraged.

        It''s often better to stop traffic to a variation.

        The Knowledge Base article "The Visual Editor in Convert Experiences" (Variations section) mentions: "You cannot delete a variation from an experience that is active or has been previously started and then paused."

        '
      tags:
      - Experience Variations
      parameters:
      - name: account_id
        in: path
        required: true
        description: ID of the account that owns the retrieved/saved data
        schema:
          type: integer
      - name: project_id
        description: ID of the project to which save/retrieved data is connected
        in: path
        required: true
        schema:
          type: integer
      - name: experience_id
        description: The ID of the experience to which the variation belongs
        in: path
        required: true
        schema:
          type: integer
      - name: variation_id
        description: The ID of the variation to be deleted
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/variations/{variation_id}/screenshot:
    get:
      operationId: getExperienceVariationScreenshot
      summary: Get screenshot for an experience variation
      description: 'Retrieves the screenshot image for a specific variation, base64 encoded.

        Screenshots help visualize the changes applied by a variation and are shown in the Convert UI.

        Can request a full-size image or a thumbnail.

        The Knowledge Base article "Whitelist IPs for Screenshot Previews" is related.

        '
      tags:
      - Experience Variations
      parameters:
      - name: account_id
        in: path
        required: true
        description: ID of the account that owns the retrieved/saved data
        schema:
          type: integer
      - name: project_id
        description: ID of the project to which save/retrieved data is connected
        in: path
        required: true
        schema:
          type: integer
      - name: experience_id
        description: The ID of the experience to which the variation belongs
        in: path
        required: true
        schema:
          type: integer
      - name: variation_id
        description: The ID of the variation to be deleted
        in: path
        required: true
        schema:
          type: integer
      - name: size
        description: The size of the returned image, if omitted will return full size
        in: query
        schema:
          type: string
          enum:
          - thumb
      - name: force_download
        description: Flag used to force download instead of inline response
        in: query
        schema:
          type: boolean
      responses:
        '200':
          $ref: '#/components/responses/ImageResponseBase64'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      operationId: uploadExperienceVariationScreenshot
      summary: Upload a screenshot for an experience variation
      description: 'Allows uploading a custom screenshot image for a specific variation.

        This can be useful if automatic screenshot generation fails or if a specific view needs to be captured.

        The uploaded image will be displayed in the Convert UI for this variation.

        '
      tags:
      - Experience Variations
      parameters:
      - name: account_id
        in: path
        required: true
        description: ID of the account that owns the retrieved/saved data
        schema:
          type: integer
      - name: project_id
        description: ID of the project to which save/retrieved data is connected
        in: path
        required: true
        schema:
          type: integer
      - name: experience_id
        description: The ID of the experience to which the variation belongs
        in: path
        required: true
        schema:
          type: integer
      - name: variation_id
        description: The ID of the variation to be deleted
        in: path
        required: true
        schema:
          type: integer
      - name: size
        description: The size of the returned image, if omitted will return full size
        in: query
        schema:
          type: string
          enum:
          - thumb
      - name: force_download
        description: Flag used to force download instead of inline response
        in: query
        schema:
          type: boolean
      requestBody:
        $ref: '#/components/requestBodies/UploadImageNoNameRequest'
      responses:
        '200':
          $ref: '#/components/responses/ImageResponseBase64'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/variations/{variation_id}/convert:
    post:
      operationId: convertExperienceVariation
      summary: Convert a winning variation into a new experience (Deploy or A/B)
      description: 'Takes a variation (often a winning one from an A/B test) and creates a new, separate experience from it.

        This new experience can be a ''Deploy'' (to roll out the change to a specific audience) or another ''A/B'' test (to further iterate).

        This is a common step after an A/B test concludes with a winner.

        The Knowledge Base article "What about Deployments?" mentions: "Create a new Deploy from a Variation or Winning Variation from another Experiment".

        '
      tags:
      - Experience Variations
      parameters:
      - name: account_id
        in: path
        required: true
        description: ID of the account that owns the retrieved/saved data
        schema:
          type: integer
      - name: project_id
        description: ID of the project to which save/retrieved data is connected
        in: path
        required: true
        schema:
          type: integer
      - name: experience_id
        description: The ID of the experience to which the variation belongs
        in: path
        required: true
        schema:
          type: integer
      - name: variation_id
        description: The ID of the variation to be converted
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/ConvertExperienceVariationRequest'
      responses:
        '200':
          $ref: '#/components/responses/ExperienceResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    SE_ProcTypes:
      type: string
      description: 'The statistical methodology used for analyzing experiment results and determining winners.

        - `frequentist`: Traditional hypothesis testing approach using p-values and confidence intervals (e.g., T-tests). KB: "Statistical Methods Used".

        - `bayesian`: Bayesian statistical approach providing probabilities of one variation being better than another (e.g., Chance to Win). KB: "Statistical Models in Convert.com''s A/B Testing Platform".

        '
      enum:
      - frequentist
      - bayesian
    BaseRuleWithBrowserNameValue:
      allOf:
      - $ref: '#/components/schemas/BaseRule'
      - type: object
        properties:
          value:
            description: Browser name used for matching
            type: string
            enum:
            - chrome
            - microsoft_ie
            - firefox
            - microsoft_edge
            - mozilla
            - opera
            - safari
    AudienceTypesWithUrl:
      description: 'Defines the behavior for an audience that *includes* URL-based conditions in its rules.

        - `segmentation`: Once a visitor matches the audience criteria (which can include URL rules), they are tagged and permanently added to this segment. This segment membership persists across sessions and can be used for long-term targeting or analysis. URL rules are evaluated to determine initial entry into the segment.

        Knowledge Base: "A segment basically allows a visitor to qualify for an audience on subsequent visits even if they do not meet the audience conditions."

        '
      type: string
      enum:
      - segmentation
    ExperienceChangeId:
      description: Represents the unique identifier of an existing change within an experience variation. Used when updating or referencing a specific change.
      type: object
      additionalProperties: false
      properties:
        id:
          description: The unique numerical identifier for this specific change.
          type: integer
      required:
      - id
    BaseRuleWithSegmentBucketedValue:
      allOf:
      - $ref: '#/components/schemas/BaseRule'
      - type: object
        properties:
          value:
            description: ID of the segment used for matching
            type: number
    ExperienceChangeBase:
      description: The fundamental structure representing a single modification applied within an experience's variation. The specific content and behavior of the change are determined by its `type` and detailed in the `data` object.
      type: object
      properties:
        type:
          type: string
          enum:
          - richStructure
          - customCode
          - defaultCode
          - defaultCodeMultipage
          - defaultRedirect
          - fullStackFeature
        data:
          description: 'A flexible object containing the specific details and content for this change, structured according to the change `type`.

            For example, for `customCode`, it would contain `js` and `css` strings. For `defaultRedirect`, it would contain `original_pattern` and `variation_pattern`.

            This field is included by default when fetching a single `ExperienceChange` but might be omitted in list views unless specified in an `include` parameter.

            '
          type: object
    GenericTextKeyValueMatchRule:
      allOf:
      - $ref: '#/components/schemas/BaseRuleWithStringValue'
      - type: object
        required:
        - rule_type
        properties:
          rule_type:
            $ref: '#/components/schemas/GenericTextKeyValueMatchRulesTypes'
          matching:
            allOf:
            - $ref: '#/components/schemas/BaseMatch'
            - type: object
              properties:
                match_type:
                  $ref: '#/components/schemas/TextMatchingOptions'
      - $ref: '#/components/schemas/GenericKey'
    DayOfWeekMatchRule:
      allOf:
      - $ref: '#/components/schemas/BaseRuleWithDayOfWeekValue'
      - type: object
        required:
        - rule_type
        properties:
          rule_type:
            $ref: '#/components/schemas/DayOfWeekMatchRulesTypes'
          matching:
            allOf:
            - $ref: '#/components/schemas/BaseMatch'
            - type: object
              properties:
                match_type:
                  $ref: '#/components/schemas/NumericMatchingOptions'
    WeatherConditionMatchRulesTypes:
      type: string
      enum:
      - weather_condition
    GenericBoolMatchRule:
      allOf:
      - $ref: '#/components/schemas/BaseRuleWithBooleanValue'
      - type: object
        required:
        - rule_type
        properties:
          rule_type:
            $ref: '#/components/schemas/BoolMatchRulesTypes'
          matching:
            allOf:
            - $ref: '#/components/schemas/BaseMatch'
            - type: object
              properties:
                match_type:
                  $ref: '#/components/schemas/ChoiceMatchingOptions'
    IntegrationGA3:
      type: object
      properties:
        type:
          enum:
          - ga3
        property_UA:
          type: string
          maxLength: 150
          nullable: true
          description: The Universal Analytics Property ID (e.g., "UA-XXXXXXXX-Y") to which Convert experiment data will be sent.
    ExperienceChangeFullStackFeatureUpdate:
      type: object
      description: Data for updating an existing 'fullStackFeature' type change, identified by its `id`.
      allOf:
      - $ref: '#/components/schemas/ExperienceChangeId'
      - $ref: '#/components/schemas/ExperienceChangeFullStackFeatureBase'
      - type: object
        properties:
          concurrency_key:
            $ref: '#/components/schemas/ConcurrencyKey'
      - required:
        - type
        - data
    ExperienceVariationBaseExtended:
      allOf:
      - type: object
        properties:
          id:
            description: Variation unique ID
            type: integer
            readOnly: true
      - $ref: '#/components/schemas/ExperienceVariationBase'
      - type: object
        properties:
          status:
            $ref: '#/components/schemas/ExperienceVariationStatuses'
    ExperienceIntegrationGoogleAnalytics:
      oneOf:
      - $ref: '#/components/schemas/ExperienceIntegrationGA3'
      - $ref: '#/components/schemas/ExperienceIntegrationGA4'
      discriminator:
        propertyName: type
        mapping:
          ga3: '#/components/schemas/ExperienceIntegrationGA3'
          ga4: '#/components/schemas/ExperienceIntegrationGA4'
    ExperienceChangeDefaultRedirectData:
      type: object
      description: Represents a 'defaultRedirect' type change, including its system-assigned ID.
      allOf:
      - $ref: '#/components/schemas/ExperienceChangeIdReadOnly'
      - $ref: '#/components/schemas/ExperienceChangeDefaultRedirectDataBase'
      - type: object
        properties:
          concurrency_key:
            $ref: '#/components/schemas/ConcurrencyKey'
    ConvertExperienceVariationRequestData:
      description: Request parameters for converting an existing variation into a new, standalone experience.
      type: object
      properties:
        experience_type:
          allOf:
          - type: string
            description: Type of the experience to be converted to
          - $ref: '#/components/schemas/ConvertibleExperienceTypes'
    GenericListMatchingOptions:
      type: string
      enum:
      - any
      - all
      description: 'Defines how multiple conditions within a list (e.g., multiple audiences or locations linked to an experience) are logically combined:

        - `any`: The overall condition is met if *at least one* item in the list matches (logical OR).

        - `all`: The overall condition is met only if *all* items in the list match (logical AND).

        Default is typically ''any'' (OR).

        '
      default: any
    TrackingScriptReleaseLatest:
      allOf:
      - $ref: '#/components/schemas/TrackingScriptReleaseBase'
      - type: object
        additionalProperties: false
        properties:
          type:
            enum:
            - latest
    TextMatchingOptions:
      type: string
      enum:
      - matches
      - regexMatches
      - contains
      - endsWith
      - startsWith
    MinuteOfHourMatchRulesTypes:
      type: string
      enum:
      - local_time_minute_of_hour
      - project_time_minute_of_hour
    SimpleLocation:
      type: object
      properties:
        id:
          type: integer
          description: The unique numerical identifier of the location.
          readOnly: true
        name:
          type: string
          description: The user-defined, friendly name of the location.
          maxLength: 100
    TagExpandable:
      description: Represents a tag, either as its unique ID or as the full tag object (ID, name, description) if expanded.
      oneOf:
      - type: integer
        description: Tag ID
      - $ref: '#/components/schemas/Tag'
    ExperienceIntegrationClicky:
      allOf:
      - $ref: '#/components/schemas/ExperienceIntegrationBase'
    BaseProject:
      type: object
      properties:
        global_javascript:
          type: string
          nullable: true
          description: 'Custom JavaScript code that will be included on all pages where this project''s tracking script is installed.

            This script runs before any experience-specific code, making it suitable for global helper functions, third-party integrations setup (like analytics), or defining global variables.

            KB: "Project, Experience, Variation Javascript" - "Global Project JavaScript".

            '
        name:
          type: string
          maxLength: 200
          description: A user-defined, friendly name for the project (e.g., "Main Website Optimization", "Q3 Marketing Campaigns", "Mobile App Features").
        project_type:
          type: string
          description: 'The type of project, determining its capabilities and how it''s used:

            - `web`: For traditional website A/B testing, MVT, Split URL, personalization, and deploys using the client-side JavaScript tracking snippet.

            - `fullstack`: For server-side experiments, feature flagging, and mobile app testing using Convert''s Full Stack SDKs.

            KB: "Full Stack Experiments on Convert".

            '
          enum:
          - web
          - fullstack
          default: web
        reporting_settings:
          allOf:
          - type: object
            description: Project settings used for reporting
            properties:
              tested_visitors_quota:
                type: integer
                minimum: 0
                description: Maximum number of tested visitors that is allowed to go through this project in a billing cycle. After that number has been reached, no experiences that have influence over tested visitors will run in this project.
              currency_symbol:
                type: string
                description: Currency symbol used in the reporting.
                maxLength: 10
              blocked_ips:
                type: object
                nullable: true
                properties:
                  single:
                    type: array
                    description: List of single ip addresses blocked.
                    items:
                      type: object
                      minProperties: 1
                      properties:
                        value:
                          type: string
                          format: ip-address
                        name:
                          type: string
                          nullable: true
                          maxLength: 64
                      required:
                      - value
                  range:
                    type: array
                    description: List of ip addresses range.
                    items:
                      type: object
                      minProperties: 1
                      properties:
                        start:
                          type: string
                          format: ip-address
                          description: Starts from ip.
                        end:
                          type: string
                          format: ip-address
                          description: Ends with ip.
                        name:
                          type: string
                          nullable: true
                          maxLength: 64
                      required:
                      - start
                      - end
                description: A list of blocked IPs that are not allowed to be counted in the reports
              stop_tracking_goals_after_days:
                type: string
                description: 'Defines goals tracking life time: goals won''t be tracking after specified days unless used in active experiments.'
                enum:
                - 'OFF'
                - 1 day
                - 15 days
                - 30 days
                - 60 days
              smart_recommendations:
                type: boolean
                default: true
                description: 'Whether to run or not Smart Recommendations.

                  '
              keep_running_until_confidence:
                type: boolean
                description: 'If true, experiments do not auto-complete when planned sample size (100% progress) is reached alone.

                  They only auto-complete when both planned sample size is reached and the confidence threshold is met.

                  If false, experiments complete automatically when planned sample size is reached, regardless of confidence level.

                  Default depends on automation toggle: when keep_winner or stop_loser is enabled, default is true; otherwise false.

                  '
          - $ref: '#/components/schemas/ExperienceReportingSettings'
        settings:
          type: object
          description: General operational settings for the project.
          properties:
            allow_crossdomain_tracking:
              type: boolean
              description: 'If true, enables automatic passing of Convert tracking cookies (`_conv_v`, `_conv_s`) as URL parameters when visitors navigate between different domains listed in this project''s `Active Websites`.

                Essential for maintaining consistent visitor identity and experiment bucketing across multiple domains (e.g., main site to a separate checkout domain).

                KB: "Cookies and Cross-Domain Testing".

                '
            allow_gdpr:
              type: boolean
              description: 'If true, displays GDPR-related warnings in the Convert UI for settings or features that might have privacy implications (e.g., using certain audience conditions, enabling cross-domain tracking).

                KB: "GDPR warnings".

                '
            data_anonymization:
              type: boolean
              description: 'If true, masks the names of experiences, variations, segments, and goals in the public JavaScript tracking snippet and in data sent to some third-party integrations.

                Instead of names, their numerical IDs are used. Enhances privacy by preventing public disclosure of experiment details.

                KB: "Prevent Experiment Details Data Leak with Data Anonymization".

                '
            do_not_track:
              type: string
              enum:
              - 'OFF'
              - EU ONLY
              - EEA ONLY
              - Worldwide
              description: 'Configures if and how the project respects the "Do Not Track" (DNT) browser setting sent by visitors.

                - `OFF`: DNT signals are ignored.

                - `EU ONLY`: Respects DNT for visitors from EU countries.

                - `EEA ONLY`: Respects DNT for visitors from European Economic Area countries.

                - `Worldwide`: Respects DNT for all visitors globally.

                If respected, the Convert script may not load or track for visitors with DNT enabled.

                KB: "Respect Browser Do Not Track Setting".

                '
            global_privacy_control:
              type: string
              enum:
              - 'OFF'
              - EU ONLY
              - EEA ONLY
              - Worldwide
              description: 'Configures if and how the project respects Global Privacy Control (GPC) signals sent by visitors'' browsers.

                Options are similar to `do_not_track`. If respected, data collection and tracking may be limited.

                KB: "Respect Browser Do Not Track Setting" - "Global Privacy Control (GPC)".

                '
            include_jquery:
              type: boolean
              description: '(For legacy tracking script) If true, Convert''s tracking script will include its own version of the jQuery library.

                If your website already loads jQuery, set this to false to avoid loading it twice and improve page performance. Ensure your site''s jQuery loads before the Convert script.

                KB: "Do not include jQuery into the tracking scripts".

                '
            include_jquery_v1:
              type: boolean
              default: false
              description: '(For new v1 tracking script) If true, includes a jQuery-compatible API within the Convert script, even though the core script is jQuery-independent.

                Set to true if your variation code or global JS relies on `convert.$()` syntax and your site doesn''t globally provide jQuery.

                The new script itself does not require jQuery to function.

                '
            disable_spa_functionality:
              type: boolean
              default: false
              description: 'If true, disables Convert''s built-in optimizations and automatic handling for Single Page Applications (SPAs).

                Most SPAs work well with default SPA functionality enabled. Only disable if encountering specific conflicts or issues.

                KB: "SPA Optimizations", "Running Experiments on Single Page Apps".

                '
            do_not_track_referral:
              type: boolean
              default: false
              description: 'If true, Convert will not store referral data (like HTTP referrer or UTM parameters) in visitor cookies for use across subsequent pages or sessions.

                Referral data will still be used for targeting on the initial page view where it''s present.

                '
            time_zone:
              type: string
              description: 'The primary timezone for this project (e.g., "America/New_York", "Europe/London", "UTC").

                This timezone is used for scheduling experiences, interpreting time-based audience conditions (like ''hour of day - project_tz''), and displaying timestamps in reports.

                '
            utc_offset:
              $ref: '#/components/schemas/UTC_Offset'
            time_format:
              type: string
              description: Preferred time format for display within the Convert application UI for this project (12-hour or 24-hour).
              enum:
              - 12h
              - 24h
            debug_token:
              $ref: '#/components/schemas/GenerateDebugTokenData'
            disable_default_config:
              type: boolean
              default: false
              description: '(For Full Stack projects) If true, disables the default public configuration endpoint for this project.

                Access to project configuration via SDKs would then strictly require an authenticated SDK key. Enhances security for Full Stack projects.

                '
            include_experience_collaborators:
              type: boolean
              default: false
              description: 'If true, experience details retrieved via API will include information about the experience owner and collaborators.

                KB: "Assign Visible Owners and Collaborators to Experiences".

                '
            version:
              type: string
              maxLength: 50
              nullable: true
              readOnly: true
              description: 'An internal version identifier for the project''s configuration.

                This version string changes whenever a modification is made that affects the tracking script''s content (e.g., updating an experience, goal, or project setting).

                Format: [ISO_datetime]-[incremental_number].

                '
            legacy_script:
              type: boolean
              default: false
              description: 'If true, this project is configured to use Convert''s legacy tracking script.

                If false, it uses the newer, more performant v1 tracking script.

                New projects default to `false`. Existing projects retain their current script setting.

                KB: "How to Install the Main Tag / Convert Tracking Code / JavaScript" - "The Tracking Script vs Legacy Tracking Script".

                '
            ignore_unused_locations:
              type: boolean
              default: false
              description: 'If true, locations that are not currently associated with any active experiences will be excluded from the tracking script data downloaded by visitors.

                This can help reduce snippet size and improve performance.

                KB: "Benefits of Archiving Unused Goals, Locations, and Audiences." (Related concept for goals).

                '
            personalization:
              type: object
              nullable: true
              description: Personalization settings.
              properties:
                enabled:
                  type: boolean
                  default: false
                  description: Indicates whether personalization is enabled for this project.
            tracking_script:
              type: object
              description: 'Settings related to the management and versioning of the Convert tracking script for this project.

                Allows choosing a release strategy (manual, latest, scheduled) and viewing available/applied script versions.

                KB: "Tracking Script Version Management".

                '
              additionalProperties: false
              nullable

# --- truncated at 32 KB (188 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/convert/refs/heads/main/openapi/convert-experience-variations-api-openapi.yml