Each **Experience's Variation** has one or more **Changes**; a change represent the actual modification that is applied to a visitor. It can be a piece of javascript or CSS code for web experiences or it can be a string value for example in case of a fullstack experience.
openapi: 3.1.0
info:
title: Convert Accounts Version Changes 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: Version Changes
description: 'Each **Experience''s Variation** has one or more **Changes**; a change represent the actual modification that
is applied to a visitor. It can be a piece of javascript or CSS code for web experiences or it can be a string value for example
in case of a fullstack experience.
'
paths:
/accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/changes/{change_id}:
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
in: path
required: true
description: ID of the experience
schema:
type: integer
- name: change_id
in: path
required: true
description: ID of the experience change to get/update
schema:
type: integer
get:
operationId: getExperienceChange
summary: Get details of a specific change in a variation
description: 'Retrieves the details of a single change applied within an experience''s variation.
A change can be CSS modifications, JavaScript code, HTML insertions, or configurations for Split URL redirects or Full Stack features.
The `data` field structure depends on the `type` of the change.
'
tags:
- Version Changes
responses:
'200':
$ref: '#/components/responses/ExperienceChangeResponse'
default:
$ref: '#/components/responses/ErrorResponse'
put:
operationId: updateExperienceChange
summary: Update a specific change in a variation
description: 'Modifies the content or settings of an existing change within an experience''s variation.
For example, updating the JavaScript code, CSS rules, or redirect pattern for a change.
The structure of the `data` field in the request body must match the `type` of the change being updated.
'
tags:
- Version Changes
requestBody:
$ref: '#/components/requestBodies/UpdateExperienceChangeRequest'
responses:
'200':
$ref: '#/components/responses/ExperienceChangeResponse'
default:
$ref: '#/components/responses/ErrorResponse'
components:
schemas:
ExperienceChangeDefaultRedirectDataAdd:
type: object
description: Data for creating a new 'defaultRedirect' type change.
allOf:
- $ref: '#/components/schemas/ExperienceChangeIdReadOnly'
- $ref: '#/components/schemas/ExperienceChangeDefaultRedirectDataBase'
- properties:
data:
required:
- original_pattern
- variation_pattern
required:
- type
- data
ExperienceChangeDefaultCodeDataAdd:
type: object
description: Data for creating a new 'defaultCode' type change.
allOf:
- $ref: '#/components/schemas/ExperienceChangeIdReadOnly'
- $ref: '#/components/schemas/ExperienceChangeDefaultCodeDataBase'
- properties:
data:
required:
- js
- css
- custom_js
required:
- type
- data
ExperienceChangeCustomCodeData:
type: object
description: Represents a 'customCode' type change, including its system-assigned ID.
allOf:
- $ref: '#/components/schemas/ExperienceChangeIdReadOnly'
- $ref: '#/components/schemas/ExperienceChangeCustomCodeDataBase'
- type: object
properties:
concurrency_key:
$ref: '#/components/schemas/ConcurrencyKey'
ExperienceChangeDefaultCodeMultipageDataAdd:
type: object
description: Data for creating a new 'defaultCodeMultipage' type change.
allOf:
- $ref: '#/components/schemas/ExperienceChangeIdReadOnly'
- $ref: '#/components/schemas/ExperienceChangeDefaultCodeMultipageDataBase'
- properties:
data:
required:
- page_id
required:
- type
- data
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'
ExperienceChangeDefaultCodeMultipageDataBase:
type: object
description: Defines a standard code-based change that applies to a specific page within a Multi-page Funnel experiment. This allows different code (CSS, JS) to be applied to different steps of the funnel for the same variation.
allOf:
- $ref: '#/components/schemas/ExperienceChangeBase'
- type: object
properties:
type:
enum:
- defaultCodeMultipage
data:
type: object
description: Describes structure for "defaultCodeMultipage" type of experience change
additionalProperties: false
properties:
css:
type: string
nullable: true
description: CSS code to be applied by this change
js:
type: string
nullable: true
description: Javascript code generated by the visual editor or written in the same structure, to be applied by this experience change
custom_js:
type: string
description: Custom javascript code to be applied by this change
nullable: true
page_id:
description: The **id** of the page connected to this change.
type: string
UpdateExperienceChangeRequestData:
oneOf:
- $ref: '#/components/schemas/ExperienceChangeAdd'
ExperienceChangeRichStructureData:
type: object
description: Represents a 'richStructure' type change, including its system-assigned ID.
allOf:
- $ref: '#/components/schemas/ExperienceChangeIdReadOnly'
- $ref: '#/components/schemas/ExperienceChangeRichStructureDataBase'
- type: object
properties:
concurrency_key:
$ref: '#/components/schemas/ConcurrencyKey'
ExperienceChangeFullStackFeatureBase:
type: object
description: Defines a change for a Full Stack experiment that involves enabling or configuring a specific 'Feature' and its variables for this variation.
allOf:
- $ref: '#/components/schemas/ExperienceChangeBase'
- type: object
properties:
type:
enum:
- fullStackFeature
data:
type: object
description: Describes structure for "fullStackFeature" type of experience change
properties:
feature_id:
description: The **id** of the feature connected to this change
type: integer
variables_data:
type: object
description: A key-value object defined by user which describes the variables values. Where the key is variable name defined in connected feature and value is a variable's value with corresponding type
ExperienceChangeFullStackFeature:
type: object
description: Represents a 'fullStackFeature' type change, including its system-assigned ID.
allOf:
- $ref: '#/components/schemas/ExperienceChangeIdReadOnly'
- $ref: '#/components/schemas/ExperienceChangeFullStackFeatureBase'
- type: object
properties:
concurrency_key:
$ref: '#/components/schemas/ConcurrencyKey'
ExperienceChangeDefaultCodeDataBase:
type: object
description: Defines a standard code-based change, typically generated by the Visual Editor for modifications like text replacement, style changes, or element removal. It can include CSS, Convert's internal JS representation, and custom JS.
allOf:
- $ref: '#/components/schemas/ExperienceChangeBase'
- type: object
properties:
type:
enum:
- defaultCode
data:
type: object
description: Describes structure for "defaultCode" type of experience change
additionalProperties: false
properties:
css:
type: string
nullable: true
description: CSS code to be applied by this change
js:
type: string
nullable: true
description: Javascript code generated by the visual editor or written in the same structure, to be applied by this experience change
custom_js:
type: string
description: Custom javascript code to be applied by this change
nullable: true
ExperienceChange:
description: Represents a single, specific modification applied as part of an experience's variation. The exact structure and content depend on the `type` of change.
oneOf:
- $ref: '#/components/schemas/ExperienceChangeDefaultCodeData'
- $ref: '#/components/schemas/ExperienceChangeDefaultCodeMultipageData'
- $ref: '#/components/schemas/ExperienceChangeDefaultRedirectData'
- $ref: '#/components/schemas/ExperienceChangeCustomCodeData'
- $ref: '#/components/schemas/ExperienceChangeRichStructureData'
- $ref: '#/components/schemas/ExperienceChangeFullStackFeature'
discriminator:
propertyName: type
mapping:
richStructure: '#/components/schemas/ExperienceChangeRichStructureData'
customCode: '#/components/schemas/ExperienceChangeCustomCodeData'
defaultCode: '#/components/schemas/ExperienceChangeDefaultCodeData'
defaultCodeMultipage: '#/components/schemas/ExperienceChangeDefaultCodeMultipageData'
defaultRedirect: '#/components/schemas/ExperienceChangeDefaultRedirectData'
fullStackFeature: '#/components/schemas/ExperienceChangeFullStackFeature'
ExperienceChangeCustomCodeDataBase:
type: object
description: Defines a change applied purely through custom-written CSS and/or JavaScript code, bypassing the Visual Editor's generated code. This offers maximum flexibility for developers.
allOf:
- $ref: '#/components/schemas/ExperienceChangeBase'
- type: object
properties:
type:
enum:
- customCode
data:
type: object
description: Describes structure for "defaultCode" type of experience change
additionalProperties: false
properties:
css:
type: string
nullable: true
description: CSS code to be applied by this change
js:
type: string
description: Custom javascript code to be applied by this change
nullable: true
page_id:
description: The **id** of the page connected to this change, in case this is a **multi-page** experiment
type: string
ExperienceChangeDefaultCodeData:
type: object
description: Represents a 'defaultCode' type change, including its system-assigned ID.
allOf:
- $ref: '#/components/schemas/ExperienceChangeIdReadOnly'
- $ref: '#/components/schemas/ExperienceChangeDefaultCodeDataBase'
- type: object
properties:
concurrency_key:
$ref: '#/components/schemas/ConcurrencyKey'
ExperienceChangeCustomCodeDataAdd:
type: object
description: Data for creating a new 'customCode' type change.
allOf:
- $ref: '#/components/schemas/ExperienceChangeIdReadOnly'
- $ref: '#/components/schemas/ExperienceChangeCustomCodeDataBase'
- properties:
data:
required:
- css
- js
required:
- type
- data
ExperienceChangeRichStructureDataBase:
type: object
description: Defines a complex change, often involving multiple DOM manipulations or structured data, typically generated by advanced Visual Editor interactions or specific integrations. (Primarily for internal or advanced programmatic use).
allOf:
- $ref: '#/components/schemas/ExperienceChangeBase'
- type: object
properties:
type:
enum:
- richStructure
data:
type: object
description: Describes structure for "defaultCode" type of experience change
additionalProperties:
type: string
description: Various key - value data
properties:
js:
type: string
nullable: true
description: Javascript code generated by the visual editor or written in the same structure, to be applied by this experience change
selector:
type: string
description: CSS selector of the element to which the change refers to, if this is a change concerning one DOM element
page_id:
description: The **id** of the page connected to this change, in case this is a **multi-page** experiment
type: string
ErrorData:
type: object
properties:
code:
type: integer
format: int32
message:
oneOf:
- type: string
- type: array
items:
type: string
fields:
oneOf:
- type: string
- type: array
items:
type: string
ExperienceChangeRichStructureDataAdd:
type: object
description: Data for creating a new 'richStructure' type change.
allOf:
- $ref: '#/components/schemas/ExperienceChangeIdReadOnly'
- $ref: '#/components/schemas/ExperienceChangeRichStructureDataBase'
- properties:
data:
required:
- js
required:
- type
- data
ExperienceChangeFullStackFeatureAdd:
type: object
description: Data for creating a new 'fullStackFeature' type change.
allOf:
- $ref: '#/components/schemas/ExperienceChangeIdReadOnly'
- $ref: '#/components/schemas/ExperienceChangeFullStackFeatureBase'
- properties:
data:
required:
- feature_id
- variables_data
required:
- type
- data
ExperienceChangeDefaultRedirectDataBase:
type: object
description: Defines a URL redirect, typically used in Split URL experiments. It specifies how to match an original URL and construct the URL for the variation page.
allOf:
- $ref: '#/components/schemas/ExperienceChangeBase'
- type: object
properties:
type:
enum:
- defaultRedirect
data:
type: object
description: Describes structure for "defaultRedirect" type of experience change
additionalProperties: false
properties:
case_sensitive:
type: boolean
description: Defines whether the URL matching is case sensitive or not
original_pattern:
type: string
description: Pattern for matching the Original URL in order to construct the redirect URL
variation_pattern:
type: string
description: String used to construct the variation redirect URL. This string can contain matches from original_url or it can be a standard URL
ConcurrencyKey:
type: string
nullable: true
description: A server-generated hash that represents the object's state at the time of retrieval. When included in an update request, the operation will only succeed if the object hasn't been modified since this key was obtained. If another update has occurred in the meantime, the request will fail with a conflict error, requiring you to fetch the latest version and retry your update with the new concurrency_key. This implements optimistic concurrency control to prevent lost updates in concurrent scenarios.
ExperienceChangeIdReadOnly:
description: Represents the unique identifier of a change, typically when returned by the API after creation or in a list.
type: object
properties:
id:
description: The unique numerical identifier for this specific change.
type: integer
readOnly: true
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
ExperienceChangeAdd:
description: Data structure for adding a new change to an experience variation. The `id` field is omitted as it will be assigned upon creation.
oneOf:
- $ref: '#/components/schemas/ExperienceChangeDefaultCodeDataAdd'
- $ref: '#/components/schemas/ExperienceChangeDefaultCodeMultipageDataAdd'
- $ref: '#/components/schemas/ExperienceChangeDefaultRedirectDataAdd'
- $ref: '#/components/schemas/ExperienceChangeCustomCodeDataAdd'
- $ref: '#/components/schemas/ExperienceChangeRichStructureDataAdd'
- $ref: '#/components/schemas/ExperienceChangeFullStackFeatureAdd'
discriminator:
propertyName: type
mapping:
richStructure: '#/components/schemas/ExperienceChangeRichStructureDataAdd'
customCode: '#/components/schemas/ExperienceChangeCustomCodeDataAdd'
defaultCode: '#/components/schemas/ExperienceChangeDefaultCodeDataAdd'
defaultCodeMultipage: '#/components/schemas/ExperienceChangeDefaultCodeMultipageDataAdd'
defaultRedirect: '#/components/schemas/ExperienceChangeDefaultRedirectDataAdd'
fullStackFeature: '#/components/schemas/ExperienceChangeFullStackFeatureAdd'
ExperienceChangeDefaultCodeMultipageData:
type: object
description: Represents a 'defaultCodeMultipage' type change, including its system-assigned ID.
allOf:
- $ref: '#/components/schemas/ExperienceChangeIdReadOnly'
- $ref: '#/components/schemas/ExperienceChangeDefaultCodeMultipageDataBase'
- type: object
properties:
concurrency_key:
$ref: '#/components/schemas/ConcurrencyKey'
responses:
ExperienceChangeResponse:
description: Details of a single change within an experience variation, including its `id`, `type` (e.g., 'defaultCode', 'customCode'), and the specific `data` (e.g., JS/CSS code, redirect patterns) for that change.
content:
application/json:
schema:
$ref: '#/components/schemas/ExperienceChange'
ErrorResponse:
description: 'Indicates an error occurred while processing the request. The `code` provides an HTTP status code, `message` offers a human-readable explanation or an array of validation errors, and `fields` (if present) specifies which input fields were problematic.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorData'
requestBodies:
UpdateExperienceChangeRequest:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateExperienceChangeRequestData'
required: true
securitySchemes:
requestSigning:
type: apiKey
x-name-applicationId: Convert-Application-ID
x-name-expire: Expire
name: Authorization
in: header
description: 'See **[API Key Authentication](#tag/API-KEY-Authentication)** for more information.
'
secretKey:
type: http
scheme: bearer
description: 'See **[API Key Authentication](#tag/API-KEY-Authentication)** for more information.
'
cookieAuthentication:
type: apiKey
in: cookie
name: sid
description: Cookie authentication is used against Convert's own IdentityProvider or third party identity providers and is described more in the "[Cookie Authentication](#tag/Cookie-Authentication)" section
x-tagGroups:
- name: Client Authentication
tags:
- API KEY Authentication
- Cookie Authentication
- OAuth Authorization
- name: Common Parameters
tags:
- Optional Fields
- Expandable Fields
- name: Requests
tags:
- User
- Accounts
- AI content
- Collaborators
- API Keys
- Projects
- SDK Keys
- Experiences
- Experience Variations
- Experience Sections
- Section Versions
- Version Changes
- Experiences Reports
- Experiences Heatmaps
- Goals
- Hypotheses
- Knowledge Bases
- Observations
- Locations
- Audiences
- Domains
- Cdn Images
- Files
- Tags
- Features
- Visitor Insights
- Visitors Data
- Visitor Data Placeholders
- OAuth