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