openapi: 3.1.0 info: title: Convert 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 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 tags: - name: Cookie Authentication description: 'In order to use the Convert app, user has two options to authenticate requests: * Provide authorization token with each request works best for backend systems * Authenticate once using username/password/IDP provider and than send session token together with each request These endpoints will handle second case. **IMPORTANT:** currently this is available only for Convert.com''s own clients, all other third party clients need to authenticate using API KEY Authentication ' - name: API KEY Authentication description: "Convert API supports two methods of API key authentication:\n\n1. **Request Signing (HMAC)**\n\nWhen using\ \ request signing, Convert API uses the Hash-based message authorization code (HMAC). \nInstead of having passwords that\ \ need to be sent over, we actually use Signing Method for API request validation. \nWhen you send HTTP requests to Convert,\ \ you sign the requests so that Convert can identify who sent them. \nSo every request should contain Signature, calculated\ \ with the help of a Secret Key, Request URL, Request payload, Request Expiration time.\n\nThree headers have to be sent\ \ with each request in order for the request to be authenticated correctly by Convert API:\n* `Convert-Application-ID`:\ \ This is the ID you get from your account corresponding to the application created inside Convert App.\n* `Expires`:\ \ This is a UNIX timestamp after which the request signing expires. The closer in future the timestamp is, the sooner\ \ the request signature would be invalidated and the more secure would be\n* `Authorization`: The value of this one is\ \ as follows: `Convert-HMAC-SHA256 Signature=[generated_hash]`; The `[generated_hash]` is a request signature calculated\ \ applying sha256 hashing algorithm on ApplicationID, ExpiresTimestamp, RequestURL, RequestBody.\n\n### What could go\ \ wrong with request signing authorization? APP ID and APP Secret are right, but it is still UNAUTHORIZED!\n\n* Check\ \ your system time - the time of the system where signature is generated\n* Check the request duration between client\ \ and API and provide larger expiration time if it takes longer so that signature does not expire before reaching validation\ \ on Convert's servers\n* Make sure that stringified payload and Sign String are correct and do not contain additional\ \ spaces. For Javascript just use JSON.stringify(request) for request payload. For php use additional flags for json_encode:\ \ json_encode($request, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)).\n* Make sure you are using HMAC SHA256 to calculate\ \ the signature and provide this method (Convert-HMAC-SHA256) in the Authorization header value\n* Make sure that nothing\ \ changes the payload after signature generation but before sending it\n\n### Example of the request signing signature\ \ generation in Javascript:\n\n```\nvar SignString = ApplicationID + \"\\n\" + ExpiresTimestamp + \"\\n\" + RequestURL\ \ + \"\\n\" + RequestBody;\nvar hash = CryptoJS.HmacSHA256(SignString, ApplicationSecretKey);\nvar hashInHex = CryptoJS.enc.Hex.stringify(hash);\n\ var Authorization = \"Convert-HMAC-SHA256 Signature=\" + hashInHex;\n```\n\nFor the above example, the `Authorization`\ \ header would be `\"Authorization: Convert-HMAC-SHA256 Signature=${Authorization}\"`\n\n2. **Secret Key**\n\nA simpler\ \ authentication method using a shared secret key. This method requires only a single header:\n* `Authorization`: Include\ \ the key ID and key secret as a Bearer token in the format: `Bearer KEY_ID:KEY_SECRET`\n\nThe secret key method is easier\ \ to implement while still providing strong security. However, request signing provides additional security through request\ \ expiration and payload validation.\n" - name: OAuth Authorization description: "Delegated authorization endpoints for third-party OAuth clients.\n\nTypical flow:\n* OAuth client initiates\ \ GET request in browser (`/oauth/authorize`) with `client_id` + `response_type=code` + `scope` + `state` + `code_challenge`\ \ (PKCE)\n* While generating `code_challenge` \u2014 don't forget to store the `code_verifier` which will be used to obtain\ \ the access token\n* User authenticates in Convert and approves scope in consent UI\n* OAuth client exchanges one-time\ \ code (`/auth/oauth/token`) for a scoped bearer session token\n* User can list/revoke authorized OAuth sessions (`/auth/oauth/sessions*`)\n\ \nScopes: `selected_accounts_projects`\n\nExample:\n```\nhttps://app.convert.com/auth/oauth/authorize?client_id=1111111&state=randomstring&scope=selected_accounts_projects&response_type=code&code_challenge=generatedCodeChallenge\n\ ```\n" - name: Optional Fields description: "Each response returned by API endpoints can have fields that are not returned by default, for improved performance,\n\ in many use cases where those fields would not be needed.\n\n**Important:** Object returned as a response of a created/update\ \ operation would include also the optional fields of that object.\n\nThose requests which can return optional fields\ \ specify the list of\npossible values for those fields names in an **include** parameter, described either as part of\ \ the URL, either as part of the request body.\n\n### Format\nThe `include` parameter must be an array when present. In\ \ URL parameters, use the following format:\n```\ninclude[]=field1&include[]=field2\n```\n\n### Valid Examples\n- Including\ \ stats and variations in an experience response:\n```\ninclude[]=stats&include[]=variations\n```\n- Including rules and\ \ stats in an audience response:\n```\ninclude[]=rules&include[]=stats.experiences_usage\n```\n\n### Error Cases\n- Invalid\ \ format (string instead of array):\n```\ninclude=stats # \u274C Wrong\ninclude[]=stats # \u2705 Correct\n```\nResponse:\n\ ```json\n{\n \"code\": 422,\n \"message\": [\n \"The 'include' parameter must be a array.\"\n ],\n \ \ \"parameters\": [\n \"include\"\n ]\n}\n```\n\nFields mentioned in the **include** parameter can belong to\ \ [Expandable Fields](#tag/Expandable-Fields)\nin which case that respective field would be expanded by default.\nExample:\ \ `include[]=variations.changes` for a [getExperience](#operation/getExperience) operation, **variations.changes** is\ \ an expandable field of that response,\nwhich would then be expanded by default.\n" - name: Expandable Fields description: "Each response returned by API endpoints can have fields that reference other objects, which are not returned\ \ in full by default.\nFor example, [the getExperience](#operation/getExperience) operation returns and Experience object\ \ which contains a **project** field.\nBy default, this is a string and represents the ID of the referenced project object.\n\ \nIn some use cases, more data related to the respective object might be needed. The Convert API offers the ability to\ \ **expand** certain fields\ninto a more detailed object identified by the ID that would be sent by default.\n\nThe expanded\ \ object is the same object that the ***get[Object]*** operation would return, not having though any of the [Optional\ \ fields](#tag/Optional-Fields)\n\n### Format\nThe `expand` parameter must be an array when present. In URL parameters,\ \ use the following format:\n```\nexpand[]=field1&expand[]=field2\n```\n\n### Valid Examples\n- Expanding project and\ \ audiences in an experience response:\n```\nexpand[]=project&expand[]=audiences\n```\n- Expanding goals and variations\ \ in an experience response:\n```\nexpand[]=goals&expand[]=variations\n```\n\n### Error Cases\n- Invalid format (string\ \ instead of array):\n```\nexpand=project # \u274C Wrong\nexpand[]=project # \u2705 Correct\n```\nResponse:\n```json\n\ {\n \"code\": 422,\n \"message\": [\n \"The 'expand' parameter must be a array.\"\n ],\n \"parameters\"\ : [\n \"expand\"\n ]\n}\n```\n" - name: User description: Authenticated user related endpoints - name: Accounts description: 'Account is the entity that contains all data. An account is owned by an user and in which more other users can have different permissions, account wide or at project level ' - name: API Keys description: 'API Keys are used to authenticate requests from Server side applications that access this API ' - name: Collaborators description: 'Convert Experiences organizes customer data into Accounts(which are billable entities) and gives Users access to accounts under different roles. By default the **user that initially setups an account**, will get access to that account as the **owner** of it. Other users can be invited to get access to specific/all projects inside that account becoming this way **Collaborators** of that **Account** ' - name: Projects description: Once you start using Convert Experiences, you will have a growing number of experiences to manage. Projects help you keep everything organized across multiple sites. Each project has its own tracking code, set of experiences, and set of collaborators. For example, if you run experiences on multiple domains, you can assign a unique project for each domain. Read here some things you need to know about how a project behaves. - name: Cdn Images description: Various endpoints that allow Image Assets loaded through Convert's CDN to be managed - name: Files description: Various endpoints that allow File Assets loaded through Convert's to be managed - name: Experiences description: Convert Experiences provides a couple different experiences types. A/B, Split URL, Multivariate (MVT), Deploys, A/A and Multi-page (funnel) testing. To learn more, see Six experience types in Convert Experiences. - name: Experiences Reports description: Specification for different reports data that can be retrieved for experiences - name: Experiences Heatmaps description: "Endpoints to retrieve heatmap background and overlay images (Convert Signals\u2122). Filters such as device\ \ and interaction type are passed in the request body." - 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 ' - 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. ' - name: Experience Sections description: Convert Experience's Sections provides API to update Sections of an experience. - name: Section Versions description: Convert Experience's Versions provides API to update Versions inside an experience's Section - name: Goals description: Goals measure how well your site fulfills your target objectives. A goal represents a completed activity, called a conversion, that contributes to the success of your business. Examples of goals include making a purchase (for an ecommerce site), completing a game level (for a mobile gaming site), or submitting a contact information form (for a marketing or lead generation site). Read more information about Goals. - name: Hypotheses description: A hypothesis is an assumption that a proposed change in your website would lead to visitors taking the action that you want them to. Read more information about Hypotheses. - name: Locations description: Locations let you target your experiences in the ways that are important to your business. - name: Audiences description: Audiences let you segment your users in the ways that are important to your business. You can segment by event (e.g., session_start or level_up) and by user property (e.g., Browser/OS, Geo, Language), and combine events, parameters, and properties to include practically any subset of users. Read more information about Audiences. - name: Domains description: Domains define websites which will be used in experiences in your projects. - name: Tags description: Tags define tag labels for your project. - name: Features description: Features can be created only under **Fullstack** Projects - name: Visitor Insights description: Visitor Insights for the project - name: Visitor Data Placeholders description: 'Endpoints for managing visitor data placeholders personalization data. Visitor data placeholders define dynamic content that can be personalized for individual visitors or groups. ' - name: OAuth description: Manage OAuth clients and authorized sessions. paths: /auth: post: operationId: doAuth summary: Authenticate user session (Cookie Based) description: 'Initiates or continues a cookie-based authentication flow. Starts with username/password. If successful and MFA is not required, returns user data and sets a session cookie. If MFA is required, or a new password needs to be set, the response will indicate the next step and provide a sessionToken. This is primarily for UI interaction, LLMs should typically use API Key Authentication. ' tags: - Cookie Authentication requestBody: $ref: '#/components/requestBodies/AuthRequest' responses: '200': $ref: '#/components/responses/AuthResponse' default: $ref: '#/components/responses/ErrorResponse' /auth/forgotpassword: post: operationId: requestForgotPassword summary: Request password reset description: 'Sends an email with a password reset link to the user associated with the provided email address, if an account exists. This is part of the cookie-based authentication flow. ' tags: - Cookie Authentication requestBody: $ref: '#/components/requestBodies/ForgotPasswordRequest' responses: '200': $ref: '#/components/responses/SuccessResponse' /auth/confirmpasswordreset: post: operationId: confirmPasswordReset summary: Confirm new password after reset request description: 'Completes the password reset process. The user provides the new password and the confirmation code received via email. This is part of the cookie-based authentication flow. ' tags: - Cookie Authentication requestBody: $ref: '#/components/requestBodies/ResetPasswordConfirmRequest' responses: '200': $ref: '#/components/responses/AuthResponse' default: $ref: '#/components/responses/ErrorResponse' /auth/logout: post: operationId: doLogout summary: Log out user session description: 'Invalidates the current authenticated user session (cookie-based). Can also be used to log out other or all sessions for the user. ' tags: - Cookie Authentication requestBody: $ref: '#/components/requestBodies/LogoutRequest' responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /auth/status: get: operationId: getAuthStatus summary: Check authentication status description: 'Verifies if the current cookie-based session is still valid and authenticated. ' tags: - Cookie Authentication responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /auth/oauth/token: post: operationId: requestOauthToken summary: Exchange OAuth code for session token description: 'Public endpoint used by OAuth clients to exchange a one-time authorization code for a scoped bearer session token. Enforces PKCE binding. ' tags: - OAuth Authorization requestBody: $ref: '#/components/requestBodies/OAuthTokenRequest' responses: '200': $ref: '#/components/responses/OAuthTokenResponse' default: $ref: '#/components/responses/ErrorResponse' /auth/oauth/clients: get: operationId: listOauthClients summary: List OAuth clients description: 'Cookie-authenticated endpoint that lists OAuth clients for the current user. ' tags: - OAuth responses: '200': $ref: '#/components/responses/OAuthClientsListResponse' default: $ref: '#/components/responses/ErrorResponse' post: operationId: createOauthClient summary: Create an OAuth client description: 'Cookie-authenticated endpoint to register a new OAuth client. ' tags: - OAuth requestBody: $ref: '#/components/requestBodies/OAuthCreateClientRequest' responses: '200': $ref: '#/components/responses/OAuthClientResponse' default: $ref: '#/components/responses/ErrorResponse' /auth/oauth/clients/{id}/update: post: operationId: updateOauthClient summary: Update an OAuth client description: 'Cookie-authenticated endpoint to update an existing OAuth client. ' tags: - OAuth parameters: - name: id in: path required: true description: OAuth client id. schema: type: string requestBody: $ref: '#/components/requestBodies/OAuthUpdateClientRequest' responses: '200': $ref: '#/components/responses/OAuthClientResponse' default: $ref: '#/components/responses/ErrorResponse' /auth/oauth/clients/{client_id}: delete: operationId: deleteOauthClient summary: Delete an OAuth client description: 'Cookie-authenticated endpoint to delete an OAuth client and all its sessions. ' tags: - OAuth parameters: - name: client_id in: path required: true description: OAuth client id. schema: type: string responses: '200': $ref: '#/components/responses/OAuthDeleteClientResponse' default: $ref: '#/components/responses/ErrorResponse' /access-roles: get: operationId: getAccessRoles summary: List available user access roles description: 'Retrieves a list of all predefined access roles within the Convert system (e.g., Owner, Admin, Editor, Reviewer, Browse). Each role defines a set of permissions that dictate what actions a user can perform on accounts and projects. This is useful for understanding permission levels when managing collaborators. ' tags: - User responses: '200': $ref: '#/components/responses/AccessRolesListResponse' default: $ref: '#/components/responses/ErrorResponse' /user: get: operationId: getUserData summary: Get current authenticated user's details description: 'Retrieves the profile data, preferences, and settings for the currently authenticated user (via cookie). This includes information like email, name, and UI preferences. Note: This endpoint is for cookie-based authentication. For API key authentication, user context is tied to the key itself. ' tags: - User responses: '200': $ref: '#/components/responses/UserDataResponse' put: operationId: updateUserProfileData summary: Update current user's profile description: 'Allows the authenticated user (via cookie) to update their profile information, such as name, email, or password. Also used to manage Multi-Factor Authentication (MFA) settings. User preferences (like UI display settings) are managed via a separate endpoint. ' tags: - User requestBody: $ref: '#/components/requestBodies/UserUpdateProfileDataRequest' responses: '200': $ref: '#/components/responses/UserDataResponse' default: $ref: '#/components/responses/ErrorResponse' /user/confirm-email: post: operationId: confirmEmail summary: Confirm user email address change description: 'Finalizes an email address change request by submitting the confirmation code sent to the new email address. Used in cookie-based authentication flows. ' tags: - User requestBody: $ref: '#/components/requestBodies/ConfirmEmailRequest' responses: '200': $ref: '#/components/responses/UserDataResponse' default: $ref: '#/components/responses/ErrorResponse' /user/preferences: post: operationId: updateUserPreferences summary: Update user's UI preferences description: 'Allows the authenticated user (via cookie) to update their preferences for the Convert application UI, such as default column visibility in tables or editor settings. These settings do not affect experiment behavior. ' tags: - User requestBody: $ref: '#/components/requestBodies/UserUpdatePreferencesRequest' responses: '200': $ref: '#/components/responses/UserDataResponse' default: $ref: '#/components/responses/ErrorResponse' /user/mfa-secret: post: operationId: generateMfaSecret summary: Generate MFA secret for authenticator app description: 'Generates a new Multi-Factor Authentication (MFA) secret for the authenticated user (cookie-based). This secret is used to set up an authenticator app (like Google Authenticator) for generating time-based one-time passwords (TOTPs). ' tags: - User responses: '200': $ref: '#/components/responses/UserMfaSecretResponse' default: $ref: '#/components/responses/ErrorResponse' /user/accept-demo-project: post: operationId: acceptDemoProject summary: Accept and create a demo project for the user description: 'Allows a user to accept the creation of a pre-configured demo project in their account. This is typically used for onboarding or trial experiences to showcase Convert''s features. ' tags: - User responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /user/sessions: post: operationId: listUserSessions summary: List authorized sessions for the current user description: 'Cookie-authenticated endpoint that returns all active authorized sessions for the current user, including the current cookie-based session and any OAuth bearer-token sessions the user has approved. ' tags: - User responses: '200': $ref: '#/components/responses/UserSessionsListResponse' default: $ref: '#/components/responses/ErrorResponse' /user/sessions/revoke: post: operationId: revokeUserSession summary: Revoke User session description: 'Cookie-authenticated endpoint that revokes a single session (cookie-based or OAuth) for the current user, identified by its sid. ' tags: - User requestBody: $ref: '#/components/requestBodies/UserSessionRevokeRequest' responses: '200': $ref: '#/components/responses/UserSessionRevokeResponse' default: $ref: '#/components/responses/ErrorResponse' /user/sessions/revoke-all: post: operationId: revokeAllUserSessions summary: Revoke all User sessions description: 'Cookie-authenticated endpoint that revokes every active session (cookie-based and OAuth) for the current user. ' tags: - User responses: '200': $ref: '#/components/responses/UserSessionRevokeAllResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts: get: operationId: getAccountsList summary: List accounts accessible to the user description: 'Retrieves a list of all accounts the authenticated user has access to. If using API key authentication, this typically returns the single account associated with the API key. If using cookie-based authentication, it may return multiple accounts if the user is a collaborator on several. An account is the top-level container for projects, billing, and user management. ' tags: - Accounts responses: '200': $ref: '#/components/responses/AccountsListResponse' /billing-plans: get: operationId: getBillingPlans summary: List available billing plans description: 'Retrieves a list of all active billing plans that an account can subscribe to. Each plan defines usage limits (e.g., tested visitors, number of projects) and available features. ' tags: - Accounts responses: '200': $ref: '#/components/responses/BillingPlansListResponse' /accounts/{account_id}/livedata: post: operationId: getAccountLiveData summary: Get live tracking events for an account tags: - Accounts parameters: - name: account_id in: path required: true description: ID of the account to be retrieved schema: type: integer description: 'Retrieves the last 100 tracking events (e.g., experiment views, goal conversions) across all projects within the specified account. Useful for real-time monitoring of activity. Supports filtering by event types and specific projects. As per the Knowledge Base, "Live Logs in Convert track how end users are interacting with web pages and experiments...at a project and experiment level in real time." ' requestBody: $ref: '#/components/requestBodies/GetAccountLiveDataRequest' responses: '200': $ref: '#/components/responses/LiveDataEventsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/change-history: post: operationId: getAccountHistory summary: Get change history for an account tags: - Accounts parameters: - name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data schema: type: integer description: 'Retrieves a historical log of changes made within the specified account, such as modifications to account settings or billing. This provides an audit trail for account-level activities. The Knowledge Base states, "The Change History shows a record of user activity for each of your projects." This extends to account changes. ' requestBody: $ref: '#/components/requestBodies/GetAccountHistoryRequest' responses: '200': $ref: '#/components/responses/ChangeHistoryListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/experiences: post: operationId: getAccountActiveCompletedExperiencesList summary: List active and completed experiences for an account description: 'Retrieves a list of all active and completed experiences (A/B tests, personalizations, etc.) across all projects within the specified account. Allows filtering to narrow down results. Useful for an overview of ongoing and finished optimization activities at the account level. ' tags: - Accounts parameters: - name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data schema: type: integer requestBody: $ref: '#/components/requestBodies/GetAccountActiveCompletedExperiencesListRequest' responses: '200': $ref: '#/components/responses/ExperiencesListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/details: get: operationId: getAccountDetails summary: Get details for a specific account description: 'Retrieves detailed information about a specific account, including its settings, billing status, and usage limits. The `include` parameter can be used to fetch additional related data, like active project counts. ' tags: - Accounts parameters: - name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data schema: type: integer - name: include in: query required: false description: 'Specifies the list of fields to be included in the response, which otherwise would not be sent. Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' schema: type: array items: $ref: '#/components/schemas/AccountDetailsIncludeFields' responses: '200': $ref: '#/components/responses/AccountDetailsResponse' post: operationId: updateAccountDetails summary: Update details for a specific account description: 'Modifies the settings or billing information for a specific account. This can include updating company details, contact information, or billing preferences. ' tags: - Accounts parameters: - name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data schema: type: integer requestBody: $ref: '#/components/requestBodies/UpdateAccountDetailsRequest' responses: '200': $ref: '#/components/responses/AccountDetailsResponse' /accounts/{account_id}/sub-accounts/add: post: operationId: createSubAccount summary: Create a new sub-account description: 'Creates a new sub-account under the specified parent main account. Sub-accounts inherit certain properties and limits from the parent but can have their own users and projects. This is typically used by agencies or larger organizations to manage client accounts or departmental usage separately. ' tags: - Accounts parameters: - name: account_id in: path required: true description: ID of the parent account under which the sub-account is being created. schema: type: integer requestBody: $ref: '#/components/requestBodies/CreateSubAccountRequest' responses: '200': $ref: '#/components/responses/AccountDetailsResponse' /accounts/{account_id}/addons: post: operationId: requestAccountAddons summary: Request add-ons for an account description: 'Allows requesting specific add-on features or services for an account, such as premium support tiers or specialized training. ' tags: - Accounts parameters: - name: account_id in: path required: true description: ID of the account for which the addons will be requested schema: type: integer requestBody: $ref: '#/components/requestBodies/RequestAccountAddonsRequest' responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/payment-setup: post: operationId: startPaymentSetup summary: Initiate payment method setup description: 'Starts a secure session with the payment provider (e.g., Stripe) to set up or update an account''s payment method. Returns a client secret or token that the frontend UI uses to complete the payment setup process directly with the provider. ' tags: - Accounts parameters: - name: account_id in: path required: true description: ID of the account for which the payment setup will be started schema: type: integer requestBody: $ref: '#/components/requestBodies/StartPaymentSetupRequest' responses: '200': $ref: '#/components/responses/StartPaymentSetupResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/billing-portal: get: operationId: getAccountBillingPortal summary: Get billing portal URL description: 'Returns an authenticated Paddle billing portal URL for the given account. The URL takes the customer to the Paddle billing portal where they can check subscriptions, view or download invoices. ' tags: - Accounts parameters: - $ref: '#/components/parameters/AccountId' responses: '200': $ref: '#/components/responses/BillingPortalResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/plan_setup/users: get: operationId: BillingPlanSetupUsers summary: Get users for billing plan setup notification description: 'Retrieves a list of users associated with an account, typically for the purpose of notifying them about billing plan setup or changes. Used internally for account management workflows. ' tags: - Accounts parameters: - name: account_id in: path required: true description: ID of the account for which the plan setup users will be returned schema: type: integer responses: '200': $ref: '#/components/responses/PlanSetupUsersResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/ai/text: post: operationId: generateTextVariants summary: Generate text variations using AI tags: - AI content parameters: - name: account_id in: path required: true description: ID of the account under which the api call executes schema: type: integer description: 'Leverages Generative AI to create alternative text versions (variants) for a given piece of content. Users can specify the number of variations, the original content, an AI model framework (e.g., Cialdini, AIDA), and a specific principle within that framework. This helps in quickly generating creative options for A/B testing headlines, calls to action, or other textual elements. Optionally, an OpenAI Key can be provided for using more advanced models or larger context. ' requestBody: $ref: '#/components/requestBodies/GenerateTextVariantsRequest' responses: '200': $ref: '#/components/responses/GenerateTextVariantsResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/ai/code: post: operationId: generateCodeVariant summary: Generate code variation using AI tags: - AI content parameters: - name: account_id in: path required: true description: ID of the account under which the api call executes schema: type: integer description: 'Leverages Generative AI to improve provided code. ' requestBody: $ref: '#/components/requestBodies/GenerateCodeVariantRequest' responses: '200': $ref: '#/components/responses/GenerateCodeVariantResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/users-accesses: get: operationId: getAccountUsersAccessesList summary: List users and their access permissions for an account description: 'Retrieves a list of all users who have collaborator access to the specified account. For each user, it details the projects they can access and their role within those projects (e.g., Admin, Editor). The `expand` parameter can be used to get more details about the projects. As per the Knowledge Base, "Account owners can invite collaborators to projects and choose to give them varying privileges." ' tags: - Collaborators parameters: - name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data schema: type: integer - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/AccountUserAccessesExpandFields' responses: '200': $ref: '#/components/responses/AccountUsersAccessesListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/users-accesses/update: put: operationId: updateAccountUserAccesses summary: Update a user's access permissions for an account description: 'Modifies the access rights of an existing collaborator for the specified account. This can involve changing their role for specific projects or altering which projects they can access. Identifies the user by `user_id` (for active collaborators) or `email` (for pending invitations). ' tags: - Collaborators parameters: - name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data schema: type: integer requestBody: $ref: '#/components/requestBodies/UpdateAccountUserAccessesRequest' responses: '200': $ref: '#/components/responses/AccountUserAccesses' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/users-accesses/add: post: operationId: addAccountUserAccesses summary: Invite a new collaborator to an account description: 'Sends an invitation to a user (identified by email) to become a collaborator on the specified account. The request defines the initial set of projects and the role the user will have for those projects. The user will receive an email to accept the invitation. ' tags: - Collaborators parameters: - name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data schema: type: integer requestBody: $ref: '#/components/requestBodies/CreateAccountUserAccessesRequest' responses: '201': $ref: '#/components/responses/AccountUserAccesses' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/users-accesses/delete: post: operationId: deleteAccountUserAccesses summary: Remove a collaborator's access from an account description: 'Revokes a user''s collaborator access to specified projects within an account, or entirely from the account. Identifies the user by `user_id` or `email`. ' tags: - Collaborators parameters: - name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data schema: type: integer requestBody: $ref: '#/components/requestBodies/DeleteAccountUserAccessesRequest' responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /check-partner: post: operationId: checkPartner summary: Check partner status for extended API access description: 'Verifies if the provided email belongs to a registered partner, potentially enabling extended API functionalities. This is an internal mechanism. ' tags: - Collaborators requestBody: $ref: '#/components/requestBodies/CheckPartnerRequest' responses: '200': $ref: '#/components/responses/CheckPartnerResponse' default: $ref: '#/components/responses/ErrorResponse' /auth/accept-invitation: post: operationId: acceptInvitation summary: Accept a collaborator invitation description: 'Allows a user to accept an invitation to collaborate on an account using a unique hash token received via email. If the user is new to Convert, this will also trigger account creation. ' tags: - Collaborators requestBody: $ref: '#/components/requestBodies/AcceptInvitationRequest' responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/api-keys: get: operationId: getApiKeysList summary: List API keys for an account description: 'Retrieves a list of all API keys configured for the specified account. API keys are used for server-to-server authentication, allowing applications to interact with the Convert API programmatically. Each key can be scoped to specific projects. ' tags: - API Keys parameters: - name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data schema: type: integer responses: '200': $ref: '#/components/responses/ApiKeysListResponse' /accounts/{account_id}/api-keys/add: post: operationId: createApiKey summary: Create a new API key for an account description: 'Generates a new API key and secret for the specified account. The key can be named for easier identification and can be restricted to a list of project IDs. If no projects are specified, the key grants access to all projects in the account. The API secret is only shown at the time of creation and should be stored securely. ' tags: - API Keys parameters: - name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data schema: type: integer requestBody: $ref: '#/components/requestBodies/CreateApiKeyRequest' responses: '201': $ref: '#/components/responses/ApiKeyResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/api-keys/{key_id}/delete: delete: operationId: deleteApiKey summary: Delete an API key description: 'Permanently revokes an API key, identified by its `key_id`. Once deleted, the key can no longer be used to authenticate API requests. ' tags: - API Keys parameters: - name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data schema: type: integer - name: key_id in: path required: true description: ID of the API key to be deleted schema: type: string responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/sessions: post: operationId: getSessionsList summary: List recorded visitor sessions for a project tags: - Visitor Insights description: 'Retrieves a list of recorded visitor sessions for a specific project. This endpoint is typically used for integrations that require access to raw session data. Note: This is different from Convert Signals. For frustration and usability insights, see the Signal Sessions endpoint. ' 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 in: path required: true description: ID of the project to be retrieved schema: type: integer requestBody: $ref: '#/components/requestBodies/GetSessionsRequest' responses: '200': $ref: '#/components/responses/SessionsListResponse' /accounts/{account_id}/projects/{project_id}/signal_sessions: post: operationId: getSignalSessionsList summary: "List Convert Signals\u2122 (visitor frustration sessions)" description: "Retrieves a list of Convert Signals\u2122 sessions for a project.\nConvert Signals\u2122 \"is a special\ \ anonymous and privacy oriented session recording feature...It shows only really clear frustrations, errors and usability\ \ signals of real users\".\nUse this to identify sessions where visitors experienced issues like rage clicks, dead\ \ clicks, or scroll stalls.\nSupports filtering by date, experience, variation, location, country, device, browser,\ \ and more.\n" tags: - Visitor Insights 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 in: path required: true description: ID of the project to be retrieved schema: type: integer requestBody: $ref: '#/components/requestBodies/GetSignalSessionsRequest' responses: '200': $ref: '#/components/responses/SignalSessionsListResponse' /accounts/{account_id}/projects/{project_id}/signal_sessions/{signal_session_id}: delete: operationId: deleteSignalSession summary: "Delete a specific Convert Signals\u2122 session" description: "Permanently removes a recorded Convert Signals\u2122 session, identified by its `signal_session_id`.\n" tags: - Visitor Insights 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 in: path required: true description: ID of the project to be retrieved schema: type: integer - name: signal_session_id in: path required: true description: ID of the signal session to be deleted schema: type: string responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/sdk-keys: get: operationId: getSdkKeysList summary: List SDK keys for a project description: 'Retrieves a list of SDK keys associated with a specific project. SDK keys are used by Convert''s Full Stack SDKs (e.g., Node.js, JavaScript) to fetch experiment configurations and track events from server-side or client-side applications. Each key is tied to a specific environment within the project (e.g., production, staging). ' tags: - SDK Keys 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 in: path required: true description: ID of the project to be retrieved schema: type: integer responses: '200': $ref: '#/components/responses/SdkKeysListResponse' /accounts/{account_id}/projects/{project_id}/sdk-keys/create: post: operationId: createSdkKey summary: Create a new SDK key for a project description: 'Generates a new SDK key and, optionally, a secret for a specified project and environment. This key is then used by the Convert SDKs to authenticate and fetch project configurations. If `has_secret` is true and no `sdk_secret` is provided, a secret will be auto-generated. The SDK secret (if generated) is only shown at the time of creation. ' tags: - SDK Keys 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 in: path required: true description: ID of the project to be retrieved schema: type: integer requestBody: $ref: '#/components/requestBodies/CreateSdkKeyRequest' responses: '201': $ref: '#/components/responses/SdkKeyResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/sdk-keys/{sdk_key}/update: post: operationId: updateSdkKey summary: Update SDK Key description: 'Partially update an SDK key, modifying only the specific fields provided in the request. ' tags: - SDK Keys 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 in: path required: true description: ID of the project to be retrieved schema: type: integer - name: sdk_key in: path required: true description: ID of the SDK key to update schema: type: string requestBody: $ref: '#/components/requestBodies/UpdateSdkKeyRequest' responses: '200': $ref: '#/components/responses/SdkKeyResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/sdk-keys/{sdk_key}/delete: delete: operationId: deleteSdkKey summary: Delete an SDK key description: 'Permanently revokes an SDK key, identified by its `sdk_key` value. Once deleted, SDKs using this key will no longer be able to fetch configurations or track events for the associated project and environment. ' tags: - SDK Keys 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 in: path required: true description: ID of the project to be retrieved schema: type: integer - name: sdk_key in: path required: true description: ID of the SDK key to be deleted schema: type: string responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/visitors-data: post: operationId: getVisitorData summary: Get Visitors Data description: 'Get visitors data for a project ' tags: - Visitors Data parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/ProjectId' requestBody: $ref: '#/components/requestBodies/GetVisitorDataListRequest' responses: '200': $ref: '#/components/responses/VisitorsDataListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/visitors-data/add: post: operationId: createVisitorDataItem summary: Create Visitor Data Item description: Creates a new visitor data item. Fails if visitor_id already exists. tags: - Visitors Data parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/ProjectId' requestBody: $ref: '#/components/requestBodies/CreateVisitorDataItemRequest' responses: '201': $ref: '#/components/responses/VisitorDataItemResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/visitors-data/{visitor_id}: get: operationId: getVisitorDataItem summary: Get Visitor Data Item description: Returns a single visitor data item by visitor_id. tags: - Visitors Data parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/VisitorId' responses: '200': $ref: '#/components/responses/VisitorDataItemResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/visitors-data/{visitor_id}/update: post: operationId: updateVisitorDataItem summary: Update Visitor Data Item description: Updates an existing visitor data item by visitor_id. tags: - Visitors Data parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/VisitorId' requestBody: $ref: '#/components/requestBodies/UpdateVisitorDataItemRequest' responses: '200': $ref: '#/components/responses/VisitorDataItemResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/visitors-data/{visitor_id}/delete: delete: operationId: deleteVisitorDataItem summary: Delete Visitor Data Item description: Deletes a visitor data item identified by visitor_id. tags: - Visitors Data parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/VisitorId' responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/visitors-data/import: post: operationId: importVisitorsDataCsv summary: Import Visitors Data Csv description: 'Imports visitors data into the project from a CSV file ' tags: - Visitors Data parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/ProjectId' requestBody: $ref: '#/components/requestBodies/ImportVisitorsDataCsvRequest' responses: '201': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/visitors-data/push: post: operationId: pushVisitorsData summary: Import Visitors Data Push description: 'push endpoint for visitors data import from the third party service ' tags: - Visitors Data parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/ProjectId' requestBody: $ref: '#/components/requestBodies/ImportVisitorsDataPushRequest' responses: '201': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/visitors-data/placeholders: post: operationId: getVisitorsDataPlaceholdersList summary: List Placeholders description: Returns a list of visitors data placeholders defined in the project tags: - Visitor Data Placeholders parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/ProjectId' requestBody: $ref: '#/components/requestBodies/GetVisitorDataPlaceholdersListRequest' responses: '200': $ref: '#/components/responses/VisitorDataPlaceholdersListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/visitors-data/placeholders/add: post: operationId: createVisitorsDataPlaceholder summary: Create Placeholder description: Creates a new visitors data placeholder tags: - Visitor Data Placeholders parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/ProjectId' requestBody: $ref: '#/components/requestBodies/CreateVisitorDataPlaceholderRequest' responses: '201': $ref: '#/components/responses/VisitorDataPlaceholderResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/visitors-data/placeholders/{placeholderId}/update: post: operationId: updateVisitorsDataPlaceholder summary: Update Placeholder description: Updates an existing visitors data placeholder tags: - Visitor Data Placeholders parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/PlaceholderId' requestBody: $ref: '#/components/requestBodies/UpdateVisitorDataPlaceholderRequest' responses: '200': $ref: '#/components/responses/VisitorDataPlaceholderResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/visitors-data/placeholders/{placeholderId}/delete: delete: operationId: deleteVisitorsDataPlaceholder summary: Delete Placeholder description: Deletes a visitors data placeholder tags: - Visitor Data Placeholders parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/PlaceholderId' responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/visitors-data/placeholders/{placeholder_id}: get: operationId: getVisitorsDataPlaceholder summary: Get Placeholder description: Returns a single visitors data placeholder by ID. tags: - Visitor Data Placeholders parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/PlaceholderId' responses: '200': $ref: '#/components/responses/VisitorDataPlaceholderResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects: post: operationId: getProjectsList summary: List projects within an account description: 'Retrieves a list of all projects belonging to the specified account that the authenticated user has access to. Supports filtering by project status, name/description search, and pagination. A project in Convert is a container for organizing experiences (A/B tests, personalizations), goals, audiences, and associated domains. As per the Knowledge Base: "Each project has its own tracking code, set of experiences, and set of collaborators." ' tags: - Projects parameters: - name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data schema: type: integer requestBody: $ref: '#/components/requestBodies/GetProjectsListRequest' responses: '200': $ref: '#/components/responses/ProjectsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/change-history: post: operationId: getProjectHistory summary: Get change history for a specific project tags: - Projects 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 in: path required: true description: ID of the project to be retrieved schema: type: integer description: 'Retrieves a historical log of changes made within a specific project. This includes modifications to experiences, goals, audiences, locations, and project settings. Provides an audit trail for project-level activities, filterable by date, user, and event type. The Knowledge Base states: "Convert logs most actions that can be made in a Project; for example: creating an experiment, modifying a variation, adding and removing audiences, and more." ' requestBody: $ref: '#/components/requestBodies/GetProjectHistoryRequest' responses: '200': $ref: '#/components/responses/ChangeHistoryListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}: get: operationId: getProject summary: Get details for a specific project description: 'Retrieves comprehensive details for a single project, identified by its `project_id`. This includes its name, type (web or fullstack), global JavaScript, settings (like time zone, jQuery inclusion), integrations, and optionally, associated domains and usage statistics. The `include` parameter can fetch related data like `domains` or `stats.usage`. The `expand` parameter can provide full objects for linked entities. ' tags: - Projects 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 in: path required: true description: ID of the project to be retrieved schema: type: integer - name: include in: query required: false description: 'Specifies the list of fields to be included in the response, which otherwise would not be sent. Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' schema: type: array items: $ref: '#/components/schemas/ProjectIncludeFields' - name: expand in: query required: false description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' schema: type: array items: $ref: '#/components/schemas/ProjectExpandFields' responses: '200': $ref: '#/components/responses/ProjectResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/add: post: operationId: createProject summary: Create a new project parameters: - name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data schema: type: integer tags: - Projects requestBody: $ref: '#/components/requestBodies/CreateProjectRequest' responses: '201': $ref: '#/components/responses/ProjectResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/update: post: operationId: updateProject summary: Update an existing project description: 'Modifies the settings of an existing project. This can include changing its name, global JavaScript, time zone, active domains, integration settings, or GDPR compliance options. The list of domains provided in the request will replace the existing list. ' tags: - Projects 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 in: path required: true schema: type: integer requestBody: $ref: '#/components/requestBodies/UpdateProjectRequest' responses: '201': $ref: '#/components/responses/ProjectResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/delete: delete: operationId: deleteProject summary: Delete a project description: 'Permanently removes an existing project and all its associated data (experiences, goals, audiences, reports) from the specified account. This action is irreversible. The Knowledge Base warns: "When a project is deleted all data will be purged from our servers within 7 days and is unrecoverable after that time." ' tags: - Projects 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 in: path description: ID of the project to be deleted required: true schema: type: integer responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/livedata: post: operationId: getProjectLiveData summary: Get live tracking events for a specific project description: 'Retrieves the last 100 tracking events (e.g., experiment views, goal conversions) specifically for the given project. Useful for real-time monitoring of a single project''s activity. Supports filtering by event types, experiences, and goals. As per the Knowledge Base: "Live Logs in Convert track how end users are interacting with web pages and experiments...at a project and experiment level in real time." ' tags: - Projects 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 in: path required: true description: ID of the project for which live data is returned schema: type: integer requestBody: $ref: '#/components/requestBodies/GetProjectLiveDataRequest' responses: '200': $ref: '#/components/responses/LiveDataEventsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/bulk-update: post: operationId: bulkUpdateProjects summary: Update multiple projects at once description: 'Allows for updating settings (like tracking script version) for multiple projects simultaneously within an account. Requires a list of project IDs and the settings to apply. ' tags: - Projects - Bulk parameters: - name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data. schema: type: integer requestBody: $ref: '#/components/requestBodies/BulkUpdateProjectsRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/generate-debug-token: get: operationId: generateDebugToken summary: Generate a debug token for a project description: 'Creates a temporary debug token for a project. This token can be used with the Convert tracking script (e.g., via the `convert-debug-token` header or query parameter) to preview draft or paused experiences, or to force specific variations for QA purposes without affecting live experiment data. The token has a limited time-to-live (TTL). ' tags: - Projects 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 in: path required: true description: ID of the project schema: type: integer responses: '200': $ref: '#/components/responses/SuccessGeneratedDebugToken' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/export: post: operationId: exportProject summary: Export project data as JSON description: 'Generates a JSON file containing all configuration data for a specific project. This includes its experiences, goals, audiences, locations, hypotheses, and project settings. Useful for backing up project configurations or migrating them to another Convert account or instance. The Knowledge Base mentions this feature for "Save and Migrate Project Settings" and "Template Creation". ' tags: - Projects 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 in: path required: true description: ID of the project schema: type: integer requestBody: $ref: '#/components/requestBodies/ExportProjectRequest' responses: '201': $ref: '#/components/responses/ProjectExportResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/import-project: post: operationId: importProject summary: Import project data from a JSON file description: 'Creates a new project or updates an existing one by importing data from a JSON file (previously exported from Convert). This allows for restoring backups or replicating project setups. The Knowledge Base mentions this for "Save and Migrate Project Settings" and "Template Creation". ' tags: - Projects parameters: - name: account_id in: path required: true description: ID of the account where the project will be stored. schema: type: integer requestBody: $ref: '#/components/requestBodies/ImportProjectRequest' responses: '201': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/import-project-data: post: operationId: importProjectData summary: Import associated data into an existing project description: 'Imports associated data (like experiences, goals, audiences) from a JSON file into an already existing project. This is useful for selectively adding or updating components within a project from an export. The Knowledge Base mentions "Selective Import/Export: Choose to export/import entire projects or only selected goals, audiences, and locations." ' tags: - Projects parameters: - name: account_id in: path required: true description: ID of the account where the project is stored. schema: type: integer - name: project_id in: path required: true description: ID of the project to which details will be attached. schema: type: integer requestBody: $ref: '#/components/requestBodies/ImportProjectRequest' responses: '201': $ref: '#/components/responses/ImportProjectDataSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/domains: post: operationId: getDomainsList summary: List domains associated with a project description: 'Retrieves a list of all website domains configured for a specific project. The Convert tracking script will operate on these domains to run experiences and track visitors. Wildcard domains (e.g., `*.example.com`) are supported. As per the Knowledge Base: "Active Websites: The domains you would like to use inside the project. Make sure you always add new domains here..." ' tags: - Domains 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 in: path required: true description: ID of the project to which save/retrieved data is connected schema: type: integer requestBody: $ref: '#/components/requestBodies/GetDomainsListRequest' responses: '200': $ref: '#/components/responses/DomainsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/domains/{domain_id}: get: operationId: getDomain summary: Get details for a specific domain in a project description: 'Retrieves information about a single domain associated with a project, identified by its `domain_id`. This includes the domain URL and whether the Convert tracking code was detected on it. ' tags: - Domains 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 in: path required: true description: ID of the project into which the domain is stored schema: type: integer - name: domain_id in: path required: true description: ID of the domain to be retrieved schema: type: integer responses: '200': $ref: '#/components/responses/DomainResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/domains/by_url: post: operationId: getDomainByUrl summary: Get domain details by its URL description: 'Retrieves information about a domain by matching its URL (exact or wildcard) instead of its ID. Useful if you know the domain URL but not its internal Convert ID. ' tags: - Domains 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 in: path required: true description: ID of the project into which the domain is stored schema: type: integer requestBody: $ref: '#/components/requestBodies/GetDomainByUrlRequest' responses: '200': $ref: '#/components/responses/DomainResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/domains/{domain_id}/check_code: post: operationId: checkCodeDomain summary: Verify Convert tracking code installation on a domain description: 'Checks if the Convert tracking script for the specified project is correctly installed and detectable on the given URL (which must belong to the domain identified by `domain_id`). Updates the `code_installed` status of the domain object. The Knowledge Base article "Tracking Script Installation Verification" describes this UI feature. ' tags: - Domains 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 in: path required: true description: ID of the project into which the domain is stored schema: type: integer - name: domain_id in: path required: true description: ID of the domain to which the given URL belongs. An error would be returned if the URL is not under this domain. schema: type: integer requestBody: $ref: '#/components/requestBodies/CheckCodeDomainRequest' responses: '200': $ref: '#/components/responses/DomainResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/domains/add: post: operationId: createDomain summary: Add a new domain to a project description: 'Associates a new website domain (e.g., `https://www.example.com`) with the specified project. The Convert tracking script for this project should then be installed on this domain to enable experiments. Wildcards like `https://*.example.com` can be used to include all subdomains. ' tags: - Domains 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 in: path required: true description: ID of the project into which the domain is to be stored schema: type: integer requestBody: $ref: '#/components/requestBodies/CreateDomainRequest' responses: '201': $ref: '#/components/responses/DomainResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/domains/{domain_id}/update: post: operationId: updateDomain summary: Update an existing domain in a project description: 'Modifies the URL of an existing domain associated with a project. ' tags: - Domains 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 in: path required: true description: ID of the project into which the domain is to be stored schema: type: integer - name: domain_id in: path required: true description: ID of the domain to be updated schema: type: integer requestBody: $ref: '#/components/requestBodies/UpdateDomainRequestData' responses: '200': $ref: '#/components/responses/DomainResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/domains/{domain_id}/delete: delete: operationId: deleteDomain summary: Remove a domain from a project description: 'De-associates a domain from the specified project. After deletion, Convert experiences will no longer run on this domain for this project. ' tags: - Domains 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 in: path required: true description: ID of the project into which the domain is to be stored schema: type: integer - name: domain_id in: path required: true description: ID of the domain to be delete schema: type: integer responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/domains/bulk-delete: post: operationId: bulkDomainsDelete summary: Remove multiple domains from a project description: 'De-associates multiple domains from the specified project in a single operation. Requires a list of domain IDs to be removed. ' tags: - Domains - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkDeleteDomainsRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences: post: operationId: getExperiencesList summary: List experiences within a project description: 'Retrieves a list of all experiences (A/B tests, MVT, Split URL, Deployments, etc.) within a specific project. Supports filtering by status, type, tags, and other criteria. Pagination is also supported. The `include` parameter can fetch related data like `variations` or `goals`. The `expand` parameter can provide full objects for linked entities. The Knowledge Base article "The Experience Overview Screen" describes the UI equivalent. ' tags: - Experiences 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 requestBody: $ref: '#/components/requestBodies/GetExperiencesListRequest' responses: '200': $ref: '#/components/responses/ExperiencesListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}: get: operationId: getExperience summary: Get details for a specific experience description: 'Retrieves comprehensive details for a single experience, identified by its `experience_id`. This includes its configuration (name, type, URL, status), associated audiences, locations, goals, variations, and integration settings. The `include` and `expand` parameters allow fetching more detailed related data. The Knowledge Base article "Experience Summary" describes the UI equivalent of this data. ' tags: - Experiences 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 be retrieved in: path required: true schema: type: integer - name: report_token in: header required: false description: Token to access the experience report in read-only mode. schema: type: string - name: include description: 'Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceIncludeFields' - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceExpandFields' responses: '200': $ref: '#/components/responses/ExperienceResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_key}: get: operationId: getExperienceByKey summary: Get experience details by its unique key description: 'Retrieves comprehensive details for a single experience, identified by its user-defined `experience_key` instead of its numerical ID. This is useful when you have a human-readable key for an experience. Functionality and parameters are otherwise similar to getting an experience by ID. ' tags: - Experiences 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_key description: The key of the experience to be retrieved in: path required: true schema: type: string - name: include description: 'Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceIncludeFields' - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceExpandFields' responses: '200': $ref: '#/components/responses/ExperienceResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/add: post: operationId: createExperience summary: Create a new experience description: 'Creates a new experience (e.g., A/B test, Split URL test, MVT, Deploy, A/A test, Multi-page Funnel) within a project. Requires defining the experience name, type, status (usually ''draft''), and the URL for the Visual Editor or original page. Variations, audiences, locations, goals, and other settings can be specified during creation. The Knowledge Base article "Create a New Experience" outlines the UI process. ' tags: - Experiences 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: include description: 'Specifies the list of optional objects which would be included in the response. Read more in the section related to [Expanding Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceIncludeFields' - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceExpandFields' requestBody: $ref: '#/components/requestBodies/CreateExperienceRequest' responses: '201': $ref: '#/components/responses/ExperienceResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/clone: post: operationId: cloneExperience summary: Clone an existing experience description: 'Creates a new experience as an identical copy of an existing one (specified by `experience_id`). This is useful for iterating on a previous test or using an existing experience as a template. The cloned experience starts in ''draft'' status and does not copy historical report data. The Knowledge Base article "How to Clone an Experiment?" describes this. ' tags: - Experiences 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 be cloned in: path required: true schema: type: integer - name: include description: 'Specifies the list of optional objects which would be included in the response. Read more in the section related to [Expanding Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceIncludeFields' - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceExpandFields' requestBody: $ref: '#/components/requestBodies/CloneExperienceRequest' responses: '201': $ref: '#/components/responses/ExperienceResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/update: post: operationId: updateExperience summary: Update an existing experience description: 'Modifies the configuration of an existing experience. This can include changing its name, description, status (e.g., from ''draft'' to ''active'', or ''active'' to ''paused''), URL, traffic distribution, audiences, locations, goals, variations, and integration settings. The Knowledge Base article "How Can I Change Variations After Experiment Started?" notes that variations cannot be added/removed after start, but other settings can be updated. ' tags: - Experiences 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: include description: 'Specifies the list of optional objects which would be included in the response. Read more in the section related to [Expanding Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceIncludeFields' - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceExpandFields' requestBody: $ref: '#/components/requestBodies/UpdateExperienceRequest' responses: '200': $ref: '#/components/responses/ExperienceResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/delete: delete: operationId: deleteExperience summary: Delete an experience description: 'Permanently removes an existing experience and all its associated data from the project. This action is irreversible. It''s generally recommended to archive experiences instead of deleting them to preserve historical data. The Knowledge Base article "How Do I Archive / Delete an Experience?" highlights this. ' tags: - Experiences 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 to be delete schema: type: integer responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/report_token: post: operationId: getReportToken summary: Manage report access token for an experience description: 'Generates, regenerates, or deletes a unique token that allows read-only access to an experience''s report. This is useful for sharing report data with stakeholders who do not have a Convert account or full project access. The token has an expiration time. ' tags: - Experiences 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: ID of the Experience in: path required: true schema: type: integer requestBody: $ref: '#/components/requestBodies/ExperienceReportTokenRequest' responses: '200': $ref: '#/components/responses/ExperienceReportTokenResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/livedata: post: operationId: getExperienceLiveData summary: Get live tracking events for a specific experience description: 'Retrieves the last 100 tracking events (views, conversions, revenue) specifically for the given experience. Useful for real-time monitoring and QA of a single active experience. Supports filtering by event type and goals. The Knowledge Base article "Live Logs for Projects and Experiments in Convert" describes this feature. ' tags: - Experiences 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 in: path required: true description: ID of the project into which the experience is stored schema: type: integer - name: experience_id in: path required: true description: ID of the Experience schema: type: integer requestBody: $ref: '#/components/requestBodies/GetExperienceLiveDataRequest' responses: '200': $ref: '#/components/responses/LiveDataEventsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/change-history: post: operationId: getExperienceHistory summary: Get change history for a specific experience description: 'Retrieves a historical log of all changes made to a specific experience. This includes modifications to its settings, variations, audiences, goals, status, etc. Provides an audit trail for the lifecycle of an experience, filterable by date and user. The Knowledge Base article "Track User Changes with Change History" details this. ' tags: - Experiences 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 in: path required: true description: ID of the project to which save/retrieved data is connected schema: type: integer - name: experience_id in: path required: true description: ID of the Experience schema: type: integer requestBody: $ref: '#/components/requestBodies/GetExperienceHistoryRequest' responses: '200': $ref: '#/components/responses/ChangeHistoryListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/trigger-screenshots: post: operationId: triggerExperienceScreenshots summary: Trigger screenshot generation for experience variations description: 'Initiates the process of generating or regenerating screenshots for the variations of a specified experience. These screenshots are displayed in the Convert UI to help visualize the changes made in each variation. The Knowledge Base article "Whitelist IPs for Screenshot Previews" is related as it lists IPs our service uses. ' tags: - Experiences 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 in: path required: true description: ID of the project to which save/retrieved data is connected schema: type: integer - name: experience_id in: path required: true description: ID of the Experience schema: type: integer requestBody: $ref: '#/components/requestBodies/TriggerExperienceScreenshotsRequest' responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/bulk-update: post: operationId: bulkExperiencesUpdate summary: Update multiple experiences at once description: 'Allows for changing the status (e.g., activate, pause, archive) of multiple experiences within a project simultaneously. Requires a list of experience IDs and the target status. The Knowledge Base article "Bulk Actions on Experiences" describes this UI feature. ' tags: - Experiences - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkUpdateExperiencesRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/bulk-delete: post: operationId: bulkExperiencesDelete summary: Delete multiple experiences at once description: 'Permanently removes multiple experiences from a project in a single operation. Requires a list of experience IDs. This action is irreversible. The Knowledge Base article "Bulk Actions on Experiences" describes this UI feature. ' tags: - Experiences - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkDeleteExperiencesRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/report_settings: get: operationId: getExperienceReportSettings summary: Get report settings for an experience description: 'Retrieves the specific reporting settings for an experience. This includes configurations like confidence level, statistical methodology (Frequentist/Bayesian), MAB strategy, primary metric, and outlier detection rules. These settings govern how experiment results are calculated and displayed. The Knowledge Base article "Experiment Report" (Stats Settings section) covers these. ' tags: - Experiences Reports 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: report_token in: header required: false description: Token to access the experience report in read-only mode. schema: type: string responses: '200': $ref: '#/components/responses/ExperienceReportSettingsResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/aggregated_report: post: operationId: getExperienceAggregatedReport summary: Get aggregated performance report for an experience description: 'Retrieves the main performance report for a specific experience. This report shows aggregated data for each variation, including visitor counts, conversions, conversion rates, improvement percentages, and statistical confidence (or chance to win for Bayesian). Data is provided for all goals attached to the experience. Supports filtering by date range and segments. The Knowledge Base article "Experiment Report" details the metrics shown. ' tags: - Experiences Reports 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: report_token in: header required: false description: Token to access the experience report in read-only mode. schema: type: string requestBody: $ref: '#/components/requestBodies/GetExperienceAggregatedReportRequest' responses: '200': $ref: '#/components/responses/ExperienceAggregatedReportResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/daily_report: post: operationId: getExperienceDailyReport summary: Get daily performance report for an experience description: 'Retrieves a day-by-day breakdown of performance metrics (visitors, conversions, conversion rate, etc.) for a specific experience and goal. This allows trend analysis and observation of how an experiment performs over time. Supports filtering by date range and segments, and can show cumulative or non-cumulative data. The Knowledge Base article "Experiment Report" (Graphs section) visualizes this type of data. ' tags: - Experiences Reports 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: report_token in: header required: false description: Token to access the experience report in read-only mode. schema: type: string requestBody: $ref: '#/components/requestBodies/GetExperienceDailyReportRequest' responses: '200': $ref: '#/components/responses/ExperienceDailyReportResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/daily_traffic_allocation: post: operationId: getExperienceDailyTrafficAllocation summary: Get daily traffic allocation report for an MAB experience description: 'Retrieves the day-by-day traffic allocation percentages for each variation in an experience that uses Multi-Armed Bandit (MAB) or auto-allocation. This shows how Convert dynamically shifted traffic towards better-performing variations over time. The Knowledge Base article "Multi-Armed Bandit (MAB) & Auto-Allocation in Convert" explains this feature. ' tags: - Experiences Reports 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: report_token in: header required: false description: Token to access the experience report in read-only mode. schema: type: string requestBody: $ref: '#/components/requestBodies/GetExperienceDailyTrafficAllocationRequest' responses: '200': $ref: '#/components/responses/ExperienceDailyTrafficAllocationResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/reset_report: post: operationId: resetExperienceReport summary: Reset report data for an experience description: 'Clears all accumulated visitor and conversion data for an experience''s report, effectively resetting its statistics to zero. The start date of the experiment is also reset. This is useful if you want to restart data collection after making significant changes or for QA purposes. The Knowledge Base article "Reset Experiment Data" warns: "If you want to prevent [carry-over effects], it is suggested that you clone your experiment instead of resetting the report". ' tags: - Experiences Reports 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 responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/export_report: post: operationId: exportExperienceReport summary: Export an experience report (CSV/PDF) description: 'Generates an export of an experience''s performance report in either CSV (aggregated or daily) or PDF format. Returns a downloadable link for the generated file. Useful for offline analysis or sharing with stakeholders. The Knowledge Base article "Experiment Report" (Export & Download section) describes this. ' tags: - Experiences Reports 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 requestBody: $ref: '#/components/requestBodies/ExportExperienceReportRequest' responses: '200': $ref: '#/components/responses/ExportExperienceReportResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/export_raw_data: post: operationId: exportExperienceRawData summary: Export raw tracking data for an experience description: 'Initiates a job to export the raw, event-level tracking data for a specific experience. This data includes individual visitor bucketing events, conversions, and transactions. The export is typically delivered as a link via email due to potential size. Useful for in-depth custom analysis or importing into external data warehouses. The Knowledge Base article "Experiment Report" (Export & Download section) mentions this. ' tags: - Experiences Reports 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 requestBody: $ref: '#/components/requestBodies/ExportExperienceRawDataRequest' responses: '200': $ref: '#/components/responses/ExportExperienceRawDataResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/remove_report_data: post: operationId: removeExperienceReportData summary: Remove specific data from an experience report description: 'Allows for targeted deletion of report data for an experience based on date range and event type (view_experience, conversion, transaction). For conversion and transaction events, specific goals can be targeted. If `simulate` is true, returns a count of records that would be deleted without actual deletion. Otherwise, performs permanent deletion. The Knowledge Base article "Remove Report Data Feature" details this. ' tags: - Experiences Reports 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 requestBody: $ref: '#/components/requestBodies/RemoveExperienceReportRequest' responses: '200': $ref: '#/components/responses/RemoveExperienceReportResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/heatmaps/{heatmap_id}/background: post: operationId: getExperienceHeatmapBackground summary: Get heatmap background image description: 'Retrieves the background image for a specific heatmap and device. ' tags: - Experiences Heatmaps parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/ExperienceId' - $ref: '#/components/parameters/HeatmapId' requestBody: $ref: '#/components/requestBodies/GetExperienceHeatmapBackgroundRequest' responses: '200': $ref: '#/components/responses/ExperienceHeatmapBackgroundResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/heatmaps/{heatmap_id}/overlay: post: operationId: getExperienceHeatmapOverlay summary: Get heatmap overlay (interaction) image description: 'Retrieves the overlay image for a specific heatmap, device, and interaction type. ' tags: - Experiences Heatmaps parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/ExperienceId' - $ref: '#/components/parameters/HeatmapId' requestBody: $ref: '#/components/requestBodies/GetExperienceHeatmapOverlayRequest' responses: '200': $ref: '#/components/responses/ExperienceHeatmapOverlayResponse' default: $ref: '#/components/responses/ErrorResponse' /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' /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' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/sections: get: operationId: getSections summary: List sections of a multivariate (MVT) experience description: 'Retrieves the list of sections defined for a multivariate (MVT) experience. In MVT, a "section" is an element or area on the page where multiple alternatives (versions) are tested (e.g., a headline section with three different headline versions). Variations in an MVT are combinations of one version from each section. The Knowledge Base article "Creating a Multivariate Experiment" explains sections. ' tags: - Experience Sections 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 of which to return sections list in: path required: true schema: type: integer - name: include description: 'Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceSectionIncludeFields' - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceSectionIncludeFields' responses: '200': $ref: '#/components/responses/ExperienceSectionsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/sections/add: post: operationId: createSection tags: - Experience Sections summary: Add a new section to an MVT experience description: 'Creates a new section within a multivariate (MVT) experience. A section represents an element or area of the page to be tested with multiple alternatives (versions). Requires defining the section name and its initial versions with their respective changes. ' 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 where section will be created in: path required: true schema: type: integer - name: include description: 'Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceSectionIncludeFields' - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceSectionIncludeFields' requestBody: $ref: '#/components/requestBodies/CreateSectionRequest' responses: '201': $ref: '#/components/responses/ExperienceSectionsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/sections/{section_id}/update: post: operationId: updateSection tags: - Experience Sections summary: Update an existing section in an MVT experience description: 'Modifies an existing section within a multivariate (MVT) experience. This can include changing the section''s name or updating its versions and their associated changes. The entire list of versions for the section must be provided; versions not included will be removed. ' 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 given experience in: path required: true schema: type: integer - name: section_id description: The ID of the updated section in: path required: true schema: type: string - name: include description: 'Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceSectionIncludeFields' - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceSectionIncludeFields' requestBody: $ref: '#/components/requestBodies/UpdateSectionRequest' responses: '200': $ref: '#/components/responses/ExperienceSectionsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/sections/update: post: operationId: updateExperienceSections tags: - Experience Sections summary: Update all sections for an MVT experience description: 'Replaces all existing sections and their versions for a multivariate (MVT) experience with the provided list. If a section or version from the existing configuration is not included in the request, it will be removed. The order of sections, versions, and changes is important and will be preserved. This is a comprehensive update for the entire MVT structure. ' 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 exeprience for which to update sections in: path required: true schema: type: integer - name: include description: 'Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceSectionIncludeFields' - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceSectionIncludeFields' requestBody: $ref: '#/components/requestBodies/UpdateExperienceSectionsRequest' responses: '200': $ref: '#/components/responses/ExperienceSectionsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/sections/{section_id}/versions/add: post: operationId: addExperienceSectionVersion tags: - Section Versions summary: Add a new version to an MVT section description: 'Creates a new version (alternative) within a specific section of a multivariate (MVT) experience. Requires defining the version name and its associated changes (CSS, JS, etc.). ' 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 given experience in: path required: true schema: type: integer - name: section_id description: The ID of the section under which to create the version in: path required: true schema: type: string - name: include description: 'Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceSectionVersionIncludeFields' - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceSectionVersionExpandFields' requestBody: $ref: '#/components/requestBodies/CreateSectionVersionRequest' responses: '201': $ref: '#/components/responses/ExperienceSectionVersionResponse' default: $ref: '#/components/responses/ErrorResponse' ? /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/sections/{section_id}/versions/{version_id}/update : post: operationId: updateExperienceSectionVersion tags: - Section Versions summary: Update a version within an MVT section description: 'Modifies an existing version within a specific section of a multivariate (MVT) experience. This can include changing the version''s name or updating its associated changes. ' 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 given experience in: path required: true schema: type: integer - name: section_id description: The ID of the section under which the updated version exists in: path required: true schema: type: string - name: version_id description: The ID of the updated version in: path required: true schema: type: string - name: include description: 'Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceSectionVersionIncludeFields' - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ExperienceSectionVersionExpandFields' requestBody: $ref: '#/components/requestBodies/UpdateSectionVersionRequest' responses: '200': $ref: '#/components/responses/ExperienceSectionVersionResponse' default: $ref: '#/components/responses/ErrorResponse' ? /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/sections/{section_id}/versions/{version_id}/delete : delete: operationId: deleteExperienceSectionVersion tags: - Section Versions summary: Delete a version from an MVT section description: 'Permanently removes a version from a specific section of a multivariate (MVT) experience. Deleting versions can affect the combinations tested and the statistical validity of an active MVT. ' 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 given experience in: path required: true schema: type: integer - name: section_id description: The ID of the section under which the updated version exists in: path required: true schema: type: string - name: version_id description: The ID of the updated version in: path required: true schema: type: string responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/images: post: operationId: getCdnImagesList summary: List uploaded images for a project description: 'Retrieves a list of images that have been uploaded to the Convert CDN for a specific project. These images can be used in experience variations. Supports pagination. The Knowledge Base article "Image Upload Guidelines for Convert Visual Editor" mentions image upload limits. ' tags: - Cdn Images 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 in: path required: true description: ID of the project to be retrieved schema: type: integer requestBody: $ref: '#/components/requestBodies/GetCdnImagesListRequest' responses: '200': $ref: '#/components/responses/CdnImagesListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/images/add: post: operationId: uploadCdnImage summary: Upload an image to the project's CDN storage tags: - Cdn Images 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 in: path required: true description: ID of the project to be retrieved schema: type: integer requestBody: $ref: '#/components/requestBodies/UploadImageRequest' responses: '201': $ref: '#/components/responses/ImageCdnResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/images/{image_key}/delete: delete: operationId: deleteCdnImage summary: Delete an image from the project's CDN storage tags: - Cdn Images 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 in: path required: true description: ID of the project to be retrieved schema: type: integer - name: image_key in: path required: true description: The key of the image file to be deleted schema: type: string responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/files/add: post: operationId: uploadFile summary: Upload a generic file to project storage tags: - Files 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 in: path required: true description: ID of the project to be retrieved schema: type: integer requestBody: $ref: '#/components/requestBodies/UploadFileRequest' responses: '201': $ref: '#/components/responses/FileResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/files/{file_key}: get: operationId: getFile summary: Get content of an uploaded file description: 'Retrieves the content of a previously uploaded file, identified by its `file_key`. The file content is returned base64 encoded. ' tags: - Files 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 in: path required: true description: ID of the project to be retrieved schema: type: integer - name: file_key in: path required: true description: The key of the file to retrieve schema: type: string responses: '200': $ref: '#/components/responses/FileDataResponse' '404': $ref: '#/components/responses/ErrorResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/files/{file_key}/delete: delete: operationId: deleteFile summary: Delete an uploaded file from project storage tags: - Files 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 in: path required: true description: ID of the project to be retrieved schema: type: integer - name: file_key in: path required: true description: The key of the file to be deleted schema: type: string responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/goals: post: operationId: getGoalsList summary: List goals within a project description: 'Retrieves a list of all conversion goals defined for a specific project. Goals are used to measure the success of experiences (e.g., purchases, sign-ups, page views). Supports filtering by status, type, name, and pagination. The Knowledge Base article "Goals" describes various goal types like ''Visit a specific page'', ''Revenue goal'', ''Click on a link'', etc. ' tags: - Goals 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 requestBody: $ref: '#/components/requestBodies/GetGoalsRequest' responses: '200': $ref: '#/components/responses/GoalsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/goals/{goal_id}: get: operationId: getGoal summary: Get details for a specific goal description: 'Retrieves detailed information about a single conversion goal, identified by its `goal_id`. This includes its name, type (e.g., ''visits_page'', ''revenue'', ''clicks_link''), configuration settings (like URL for page visit goals, or CSS selector for click goals), and triggering rules. The `include` parameter can fetch additional data like usage statistics. ' tags: - Goals 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: goal_id in: path required: true description: ID of the goal to be retrieved schema: type: integer - name: include description: 'Specifies the list of optional fields which would be included in the response. Otherwise, the fields that can be passed through this parameter would not be included in the response. Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/GoalOptionalFields' responses: '200': $ref: '#/components/responses/GoalResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/goals/{goal_key}: get: operationId: getGoalByKey summary: Get goal details by its unique key description: 'Retrieves detailed information about a single conversion goal, identified by its user-defined `goal_key`. Useful if you have a human-readable key for a goal. Otherwise, similar to getting a goal by ID. ' tags: - Goals 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: goal_key in: path required: true description: Key of the goal to be retrieved schema: type: string - name: include description: 'Specifies the list of optional fields which would be included in the response. Otherwise, the fields that can be passed through this parameter would not be included in the response. Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/GoalOptionalFields' responses: '200': $ref: '#/components/responses/GoalResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/goals/add: post: operationId: createGoal summary: Create a new conversion goal description: 'Defines a new conversion goal within a project. Requires specifying the goal name and type (e.g., ''visits_page'', ''revenue'', ''clicks_link'', ''submits_form'', ''code_trigger''). Depending on the type, additional settings are needed, such as the target URL for a page visit goal, or the CSS selector for a click goal. The Knowledge Base article "Goals" (Use a goal template section) lists various types. ' tags: - Goals 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 in: path required: true description: ID of the project into which the goal is to be stored schema: type: integer requestBody: $ref: '#/components/requestBodies/CreateGoalRequest' responses: '201': $ref: '#/components/responses/GoalResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/goals/{goal_id}/update: post: operationId: updateGoal summary: Update an existing conversion goal description: 'Modifies the configuration of an existing conversion goal. This can include changing its name, type, status (active/archived), or specific settings like the target URL or triggering rules. ' tags: - Goals 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 in: path required: true description: ID of the project to which save/retrieved data is connected schema: type: integer - name: goal_id in: path required: true description: ID of the goal to be updated schema: type: integer requestBody: $ref: '#/components/requestBodies/UpdateGoalRequest' responses: '200': $ref: '#/components/responses/GoalResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/goals/{goal_id}/delete: delete: operationId: deleteGoal summary: Delete a conversion goal description: 'Permanently removes a conversion goal from a project. This action is irreversible. If the goal is in use by active experiences, consider archiving it instead. ' tags: - Goals 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: goal_id in: path required: true description: ID of the goal to be deleted schema: type: integer responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/goals/bulk-update: post: operationId: bulkGoalsUpdate summary: Update multiple goals at once description: 'Allows for changing the status (e.g., active, archived) of multiple goals within a project simultaneously. Requires a list of goal IDs and the target status. ' tags: - Goals - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkUpdateGoalsRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/goals/bulk-delete: post: operationId: bulkGoalsDelete summary: Delete multiple goals at once description: 'Permanently removes multiple goals from a project in a single operation. Requires a list of goal IDs. This action is irreversible. ' tags: - Goals - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkDeleteGoalsRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/goals/{goal_id}/clone: post: operationId: cloneGoal summary: Clone an existing conversion goal description: 'Creates a new goal as an identical copy of an existing one (specified by `goal_id`). Useful for creating a similar goal with minor modifications or for templating. ' tags: - Goals 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: goal_id in: path required: true description: ID of the goal to be deleted schema: type: integer - name: include description: 'Specifies the list of optional fields which would be included in the response. Otherwise, the fields that can be passed through this parameter would not be included in the response. Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/GoalOptionalFields' responses: '201': $ref: '#/components/responses/GoalResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/tags: post: operationId: getTagsList summary: List tags within a project description: 'Retrieves a list of all tags defined for a specific project. Tags are keywords used to categorize and organize experiences, goals, audiences, etc., for easier management and filtering. The Knowledge Base article "Adding tags to your Experiences" explains their use. ' tags: - Tags 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 requestBody: $ref: '#/components/requestBodies/GetTagsRequest' responses: '200': $ref: '#/components/responses/TagsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/tags/{tag_id}: get: operationId: getTag summary: Get details for a specific tag description: 'Retrieves information about a single tag, identified by its `tag_id`. This includes its name and description. ' tags: - Tags 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 in: path required: true description: ID of the project into which the tag is stored schema: type: integer - name: tag_id in: path required: true description: ID of the tag to be retrieve schema: type: integer responses: '200': $ref: '#/components/responses/TagResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/tags/add: post: operationId: createTag summary: Create a new tag description: 'Defines a new tag within a project. Requires a tag name and an optional description. Tags can then be applied to experiences, goals, etc., to help organize them. ' tags: - Tags 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 in: path required: true description: ID of the project into which the tag is to be stored schema: type: integer requestBody: $ref: '#/components/requestBodies/CreateTagRequest' responses: '201': $ref: '#/components/responses/TagResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/tags/{tag_id}/update: post: operationId: updateTag summary: Update an existing tag description: 'Modifies the name or description of an existing tag. ' tags: - Tags 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 in: path required: true description: ID of the project into which the tag is to be stored schema: type: integer - name: tag_id in: path required: true description: ID of the tag to be updated schema: type: integer requestBody: $ref: '#/components/requestBodies/UpdateTagRequest' responses: '200': $ref: '#/components/responses/TagResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/tags/{tag_id}/delete: delete: operationId: deleteTag summary: Delete a tag description: 'Permanently removes a tag from a project. This does not delete the items (experiences, goals, etc.) that were associated with the tag, but simply removes the tag association. ' tags: - Tags 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 in: path required: true description: ID of the project from which the tag is to be deleted schema: type: integer - name: tag_id in: path required: true description: ID of the tag to be deleted schema: type: integer responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/tags/bulk-delete: post: operationId: bulkTagsDelete summary: Delete multiple tags at once description: 'Permanently removes multiple tags from a project in a single operation. Requires a list of tag IDs. ' tags: - Tags - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkDeleteTagsRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/hypotheses: post: operationId: getHypothesesList summary: List hypotheses within a project description: 'Retrieves a list of all hypotheses defined for a specific project. A hypothesis is an assumption about a proposed change and its expected impact, forming the basis for an experiment. Supports filtering by status, score, name, and pagination. The Knowledge Base article "Hypotheses (Compass)" explains: "A hypothesis is an assumption that a proposed change in your website would lead to visitors taking the action that you want them to." ' tags: - Hypotheses 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 requestBody: $ref: '#/components/requestBodies/GetHypothesesRequest' responses: '200': $ref: '#/components/responses/HypothesesListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/hypotheses/{hypothesis_id}: get: operationId: getHypothesis summary: Get details for a specific hypothesis description: 'Retrieves detailed information about a single hypothesis, identified by its `hypothesis_id`. This includes its name, objective, prioritization score (PIE or ICE), status, associated experiences, and tags. ' tags: - Hypotheses 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 in: path required: true description: ID of the project into which the hypothesis is stored schema: type: integer - name: hypothesis_id in: path required: true description: ID of the hypothesis to be retrieve schema: type: integer - name: expand in: query description: 'Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' schema: type: array items: $ref: '#/components/schemas/HypothesisExpandFields' responses: '200': $ref: '#/components/responses/HypothesisResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/hypotheses/add: post: operationId: createHypothesis summary: Create a new hypothesis description: 'Defines a new hypothesis within a project. Requires a name, objective (problem and proposed solution), prioritization model (PIE or ICE) and its scores, status, and optionally, start/end dates, summary, associated experiences, and tags. The Knowledge Base article "Hypotheses (Compass)" details the PIE (Potential, Importance, Ease) and ICE (Impact, Confidence, Ease) models. ' tags: - Hypotheses 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 in: path required: true description: ID of the project into which the hypothesis is to be stored schema: type: integer - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/HypothesisExpandFields' requestBody: $ref: '#/components/requestBodies/CreateHypothesisRequest' responses: '201': $ref: '#/components/responses/HypothesisResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/hypotheses/{hypothesis_id}/update: post: operationId: updateHypothesis summary: Update an existing hypothesis description: 'Modifies the details of an existing hypothesis, such as its name, objective, prioritization scores, status, or associated experiences and tags. ' tags: - Hypotheses 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 in: path required: true description: ID of the project into which the hypothesis is to be updated schema: type: integer - name: hypothesis_id in: path required: true description: ID of the hypothesis to be updated schema: type: integer - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/HypothesisExpandFields' requestBody: $ref: '#/components/requestBodies/UpdateHypothesisRequest' responses: '200': $ref: '#/components/responses/HypothesisResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/hypotheses/{hypothesis_id}/update-status: post: operationId: updateHypothesisStatus summary: Update the status of a hypothesis description: 'Changes the status of an existing hypothesis (e.g., from ''draft'' to ''completed'', ''applied'', ''proven'', ''disproven'', or ''archived''). This helps track the lifecycle of a hypothesis from idea to tested outcome. ' tags: - Hypotheses 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 in: path required: true description: ID of the project into which the hypothesis is stored schema: type: integer - name: hypothesis_id in: path required: true description: ID of the hypothesis to be updated schema: type: integer - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/HypothesisExpandFields' requestBody: $ref: '#/components/requestBodies/UpdateHypothesisStatusRequest' responses: '200': $ref: '#/components/responses/HypothesisResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/hypotheses/{hypothesis_id}/convert: post: operationId: convertHypothesis summary: Convert a proven/disproven hypothesis to a Knowledge Base entry description: 'Moves a hypothesis (typically one that is ''proven'' or ''disproven'' after testing) into the Knowledge Base. This archives the learnings from the hypothesis for future reference and organizational learning. The Knowledge Base article "Hypotheses (Compass)" mentions: "Proven hypotheses can then be moved to the Knowledge Base". ' tags: - Hypotheses 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 in: path required: true description: ID of the project into which the hypothesis is going to be converted schema: type: integer - name: hypothesis_id in: path required: true description: ID of the hypothesis to be converted schema: type: integer responses: '200': $ref: '#/components/responses/KnowledgeBaseResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/hypotheses/{hypothesis_id}/delete: delete: operationId: deleteHypothesis summary: Delete a hypothesis description: 'Permanently removes a hypothesis from a project. This action is irreversible. ' tags: - Hypotheses 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 in: path required: true description: ID of the project from which the hypothesis is to be deleted schema: type: integer - name: hypothesis_id in: path required: true description: ID of the hypothesis to be deleted schema: type: integer responses: '200': $ref: '#/components/responses/HypothesisResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/hypotheses/bulk-update: post: operationId: bulkHypothesesUpdate summary: Update multiple hypotheses at once description: 'Allows for changing the status of multiple hypotheses within a project simultaneously. Requires a list of hypothesis IDs and the target status. ' tags: - Hypotheses - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkUpdateHypothesesRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/hypotheses/bulk-delete: post: operationId: bulkHypothesesDelete summary: Delete multiple hypotheses at once description: 'Permanently removes multiple hypotheses from a project in a single operation. Requires a list of hypothesis IDs. This action is irreversible. ' tags: - Hypotheses - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkDeleteHypothesesRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/knowledge-bases: post: operationId: getKnowledgeBasesList summary: List Knowledge Base entries within a project description: 'Retrieves a list of all Knowledge Base entries for a specific project. The Knowledge Base stores proven or disproven hypotheses and their outcomes, serving as a repository of experimental learnings. Supports filtering by status, name, and pagination. The Knowledge Base article "Observations Feature Guide" explains: "Knowledge Base - Convert proven hypotheses to serve as a historical record and knowledge resource." ' tags: - Knowledge Bases 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 requestBody: $ref: '#/components/requestBodies/GetKnowledgeBasesRequest' responses: '200': $ref: '#/components/responses/KnowledgeBasesListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/knowledge-bases/{knowledge_base_id}: get: operationId: getKnowledgeBase summary: Get details for a specific Knowledge Base entry description: 'Retrieves detailed information about a single Knowledge Base entry, identified by its `knowledge_base_id`. This includes the original hypothesis name, summary of findings, status, and associated tags. ' tags: - Knowledge Bases 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 in: path required: true description: ID of the project into which the knowledge base is stored schema: type: integer - name: knowledge_base_id in: path required: true description: ID of the knowledge base to be retrieve schema: type: integer - name: expand in: query description: 'Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' schema: type: array items: $ref: '#/components/schemas/KnowledgeBasesExpandFields' responses: '200': $ref: '#/components/responses/KnowledgeBaseResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/knowledge-bases/add: post: operationId: createKnowledgeBase summary: Create a new Knowledge Base entry description: 'Adds a new entry to the Knowledge Base. This is typically done by converting a ''proven'' or ''disproven'' hypothesis, but can also be used to manually add other experimental learnings. Requires a name, summary, and status. ' tags: - Knowledge Bases 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 in: path required: true description: ID of the project into which the knowledge base is to be stored schema: type: integer - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/KnowledgeBasesExpandFields' requestBody: $ref: '#/components/requestBodies/CreateKnowledgeBasesRequest' responses: '201': $ref: '#/components/responses/KnowledgeBaseResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/knowledge-bases/{knowledge_base_id}/update-status: post: operationId: updateKnowledgeBase summary: Update the status of a Knowledge Base entry description: 'Changes the status of an existing Knowledge Base entry (e.g., from ''active'' to ''archived''). ' tags: - Knowledge Bases 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 in: path required: true description: ID of the project into which the knowledge base is to be updated schema: type: integer - name: knowledge_base_id in: path required: true description: ID of the knowledge base to be updated schema: type: integer - name: expand in: query description: 'Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' schema: type: array items: $ref: '#/components/schemas/KnowledgeBasesExpandFields' requestBody: $ref: '#/components/requestBodies/UpdateKnowledgeBasesStatusRequest' responses: '200': $ref: '#/components/responses/KnowledgeBaseResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/knowledge-bases/{knowledge_base_id}/delete: delete: operationId: deleteKnowledgeBase summary: Delete a Knowledge Base entry description: 'Permanently removes a Knowledge Base entry from a project. This action is irreversible. ' tags: - Knowledge Bases 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 in: path required: true description: ID of the project from which the knowledge base is to be deleted schema: type: integer - name: knowledge_base_id in: path required: true description: ID of the knowledge base to be deleted schema: type: integer responses: '200': $ref: '#/components/responses/KnowledgeBaseResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/knowledge-bases/bulk-update: post: operationId: bulkKnowledgeBasesUpdate summary: Update multiple Knowledge Base entries at once description: 'Allows for changing the status (e.g., active, archived) of multiple Knowledge Base entries within a project simultaneously. Requires a list of Knowledge Base entry IDs and the target status. ' tags: - Knowledge Bases - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkUpdateKnowledgeBasesRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/knowledge-bases/bulk-delete: post: operationId: bulkKnowledgeBasesDelete summary: Delete multiple Knowledge Base entries at once description: 'Permanently removes multiple Knowledge Base entries from a project in a single operation. Requires a list of Knowledge Base entry IDs. This action is irreversible. ' tags: - Knowledge Bases - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkDeleteKnowledgeBasesRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/observations: post: operationId: getObservationsList summary: List observations within a project description: 'Retrieves a list of all observations recorded for a specific project. Observations are initial insights, ideas, or user behaviors noted by the team, which can later be developed into hypotheses. Supports filtering by status, name, tags, and pagination. The Knowledge Base article "Observations Feature Guide" explains: "Observations - Document initial insights directly." ' tags: - Observations 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 requestBody: $ref: '#/components/requestBodies/GetObservationsRequest' responses: '200': $ref: '#/components/responses/ObservationsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/observations/{observation_id}: get: operationId: getObservation summary: Get details for a specific observation description: 'Retrieves detailed information about a single observation, identified by its `observation_id`. This includes its name, description, reference URL, status, associated tags, and any attachments (images/files). ' tags: - Observations 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 in: path required: true description: ID of the project into which the observation is stored schema: type: integer - name: observation_id in: path required: true description: ID of the observation to be retrieve schema: type: integer - name: expand in: query description: 'Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' schema: type: array items: $ref: '#/components/schemas/ObservationsExpandFields' responses: '200': $ref: '#/components/responses/ObservationResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/observations/add: post: operationId: createObservation summary: Create a new observation description: 'Records a new observation within a project. Requires a name, and can include a description, reference URL, status, tags, and attachments (images/files). Observations are the first step in the ideation process, leading to hypotheses. The Knowledge Base article "Observations Feature Guide" details this: "Observations serve as the starting point in documenting insights." ' tags: - Observations 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 in: path required: true description: ID of the project into which the observation is to be stored schema: type: integer - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ObservationsExpandFields' requestBody: $ref: '#/components/requestBodies/CreateObservationRequest' responses: '201': $ref: '#/components/responses/ObservationResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/observations/{observation_id}/update: post: operationId: updateObservation summary: Update an existing observation description: 'Modifies the details of an existing observation, such as its name, description, URL, status, tags, or attachments. ' tags: - Observations 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 in: path required: true description: ID of the project into which the observation is to be updated schema: type: integer - name: observation_id in: path required: true description: ID of the observation to be updated schema: type: integer - name: expand description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/ObservationsExpandFields' requestBody: $ref: '#/components/requestBodies/UpdateObservationRequest' responses: '200': $ref: '#/components/responses/ObservationResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/observations/{observation_id}/delete: delete: operationId: deleteObservation summary: Delete an observation description: 'Permanently removes an observation from a project. This action is irreversible. ' tags: - Observations 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 in: path required: true description: ID of the project from which the observation is to be deleted schema: type: integer - name: observation_id in: path required: true description: ID of the observation to be deleted schema: type: integer responses: '200': $ref: '#/components/responses/ObservationResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/observations/bulk-update: post: operationId: bulkObservationsUpdate summary: Update multiple observations at once description: 'Allows for changing the status (e.g., active, archived) of multiple observations within a project simultaneously. Requires a list of observation IDs and the target status. ' tags: - Observations - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkUpdateObservationsRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/observations/bulk-delete: post: operationId: bulkObservationsDelete summary: Delete multiple observations at once description: 'Permanently removes multiple observations from a project in a single operation. Requires a list of observation IDs. This action is irreversible. ' tags: - Observations - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkDeleteObservationsRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/locations: post: operationId: getLocationsList summary: List locations within a project description: 'Retrieves a list of all locations defined for a specific project. Locations define *where* on a website an experience will run, based on URL patterns, page tags, or JavaScript conditions. Supports filtering by status, name, and pagination. The Knowledge Base article "Locations" explains: "Locations conditions include the pages on which the experiment will run." ' tags: - Locations 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 requestBody: $ref: '#/components/requestBodies/GetLocationsListRequest' responses: '200': $ref: '#/components/responses/LocationsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/locations/{location_id}: get: operationId: getLocation summary: Get details for a specific location description: 'Retrieves detailed information about a single location, identified by its `location_id`. This includes its name, status, triggering rules (e.g., URL matches, JS conditions), and the type of trigger (e.g., upon_run, manual, dom_element). The `include` parameter can fetch additional data like usage statistics. ' tags: - Locations 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 in: path required: true description: ID of the project into which the Location is stored schema: type: integer - name: location_id in: path required: true description: ID of the Location to be retrieved schema: type: integer - name: include in: query required: false description: 'Specifies the list of fields to be included in the response, which otherwise would not be sent. Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' schema: type: array items: $ref: '#/components/schemas/LocationIncludeFields' responses: '200': $ref: '#/components/responses/LocationResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/locations/add: post: operationId: createLocation summary: Create a new location description: 'Defines a new location within a project. Requires a name and a set of rules (e.g., URL contains ''product/'', JS condition `window.userType === ''premium''`). Also requires specifying the trigger type (e.g., ''upon_run'' to activate when rules match on page load, or ''manual'' to activate via JavaScript call). The Knowledge Base article "Creating Effective Experiences: A Guide to Location Setup" describes different trigger options. ' tags: - Locations 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 in: path required: true description: ID of the project into which the location is to be stored schema: type: integer requestBody: $ref: '#/components/requestBodies/CreateLocationRequest' responses: '201': $ref: '#/components/responses/LocationResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/locations/{location_id}/update: post: operationId: updateLocation summary: Update an existing location description: 'Modifies the configuration of an existing location. This can include changing its name, status (active/archived), triggering rules, or trigger type. ' tags: - Locations 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 in: path required: true description: ID of the project into which the location is stored schema: type: integer - name: location_id in: path required: true description: ID of the location to be updated schema: type: integer requestBody: $ref: '#/components/requestBodies/UpdateLocationRequest' responses: '200': $ref: '#/components/responses/LocationResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/locations/{location_id}/delete: delete: operationId: deleteLocation summary: Delete a location description: 'Permanently removes a location from a project. This action is irreversible. If the location is in use by active experiences, consider archiving it instead or unlinking it from experiences first. ' tags: - Locations 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: location_id in: path required: true description: ID of the location to be deleted schema: type: integer responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/locations/bulk-update: post: operationId: bulkLocationsUpdate summary: Update multiple locations at once description: 'Allows for changing the status (e.g., active, archived) of multiple locations within a project simultaneously. Requires a list of location IDs and the target status. ' tags: - Locations - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkUpdateLocationsRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/locations/bulk-delete: post: operationId: bulkLocationsDelete summary: Delete multiple locations at once description: 'Permanently removes multiple locations from a project in a single operation. Requires a list of location IDs. This action is irreversible. ' tags: - Locations - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkDeleteLocationsRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/locations-presets: get: operationId: getLocationsPresets summary: List predefined location templates (presets) description: 'Retrieves a list of predefined location templates (presets) available for use. These presets offer common targeting configurations (e.g., "All Pages", "Homepage") to speed up location setup. The Knowledge Base article "Creating Effective Experiences: A Guide to Location Setup" mentions "Saved Locations" which are user-created, these are system presets. ' tags: - Locations 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 responses: '200': $ref: '#/components/responses/LocationsPresetsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/locations/{location_id}/clone: post: operationId: cloneLocation summary: Clone an existing location description: 'Creates a new location as an identical copy of an existing one (specified by `location_id`). Useful for creating a similar location with minor modifications or for templating. ' tags: - Locations 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: location_id in: path required: true description: ID of the location to be deleted schema: type: integer - name: include in: query required: false description: 'Specifies the list of fields to be included in the response, which otherwise would not be sent. Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' schema: type: array items: $ref: '#/components/schemas/LocationIncludeFields' responses: '201': $ref: '#/components/responses/LocationResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/audiences: post: operationId: getAudiencesList summary: List audiences within a project description: 'Retrieves a list of all audiences defined for a specific project. Audiences segment visitors based on criteria like behavior, demographics, traffic source, or custom data, to target experiences. Supports filtering by status, type, name, and pagination. The Knowledge Base article "Define Audiences for your Experience" explains: "An ''Audience'' is a group of visitors that you want to be included in your experience". ' tags: - Audiences 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 requestBody: $ref: '#/components/requestBodies/GetAudiencesListRequest' responses: '200': $ref: '#/components/responses/AudiencesListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/audiences/{audience_id}: get: operationId: getAudience summary: Get details for a specific audience description: 'Retrieves detailed information about a single audience, identified by its `audience_id`. This includes its name, type (permanent, transient, segmentation), status, and the rules defining the audience criteria (e.g., browser is Chrome, country is USA, visited specific page). The `include` parameter can fetch additional data like usage statistics. ' tags: - Audiences 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 in: path required: true description: ID of the project into which the audience is stored schema: type: integer - name: audience_id in: path required: true description: ID of the audience to be retrieved schema: type: integer - name: include in: query required: false description: 'Specifies the list of fields to be included in the response, which otherwise would not be sent. Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' schema: type: array items: $ref: '#/components/schemas/AudienceIncludeFields' responses: '200': $ref: '#/components/responses/AudienceResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/audiences/add: post: operationId: createAudience summary: Create a new audience description: 'Defines a new audience within a project. Requires a name, type (permanent, transient, segmentation), and a set of rules defining the audience criteria. Rules can be based on visitor data (browser, device, geo-location, language, visit count, cookie values), traffic sources (UTM parameters, referrer), page tags, or JavaScript conditions. The Knowledge Base article "Define an Advanced Audience" lists many available conditions. ' tags: - Audiences 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 in: path required: true description: ID of the project into which the audience is to be stored schema: type: integer requestBody: $ref: '#/components/requestBodies/CreateAudienceRequest' responses: '201': $ref: '#/components/responses/AudienceResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/audiences/{audience_id}/update: post: operationId: updateAudience summary: Update an existing audience description: 'Modifies the configuration of an existing audience. This can include changing its name, type, status (active/archived), or the rules defining its criteria. ' tags: - Audiences 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 in: path required: true description: ID of the project into which the audience is stored schema: type: integer - name: audience_id in: path required: true description: ID of the audience to be updated schema: type: integer requestBody: $ref: '#/components/requestBodies/UpdateAudienceRequest' responses: '200': $ref: '#/components/responses/AudienceResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/audiences/{audience_id}/delete: delete: operationId: deleteAudience summary: Delete an audience description: 'Permanently removes an audience from a project. This action is irreversible. If the audience is in use by active experiences, consider archiving it instead or unlinking it from experiences first. ' tags: - Audiences 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: audience_id in: path required: true description: ID of the audience to be deleted schema: type: integer responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/audiences/bulk-update: post: operationId: bulkAudiencesUpdate summary: Update multiple audiences at once description: 'Allows for changing the status (e.g., active, archived) of multiple audiences within a project simultaneously. Requires a list of audience IDs and the target status. ' tags: - Audiences - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkUpdateAudiencesRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/audiences/bulk-delete: post: operationId: bulkAudiencesDelete summary: Delete multiple audiences at once description: 'Permanently removes multiple audiences from a project in a single operation. Requires a list of audience IDs. This action is irreversible. ' tags: - Audiences - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkDeleteAudiencesRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/audiences-presets: get: operationId: getAudiencesPresets summary: List predefined audience templates (presets) description: 'Retrieves a list of predefined audience templates (presets) available for use. These presets offer common targeting configurations (e.g., "New Visitors", "Mobile Users", "Visitors from Google") to speed up audience setup. The Knowledge Base article "Define an Audience from the Templates" describes this. ' tags: - Audiences 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 responses: '200': $ref: '#/components/responses/AudiencesPresetsListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/audiences/{audience_id}/clone: post: operationId: cloneAudience summary: Clone an existing audience description: 'Creates a new audience as an identical copy of an existing one (specified by `audience_id`). Useful for creating a similar audience with minor modifications or for templating. ' tags: - Audiences 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: audience_id in: path required: true description: ID of the audience to be deleted schema: type: integer - name: include in: query required: false description: 'Specifies the list of fields to be included in the response, which otherwise would not be sent. Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' schema: type: array items: $ref: '#/components/schemas/AudienceIncludeFields' responses: '201': $ref: '#/components/responses/AudienceResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/features: post: operationId: getFeaturesList summary: List features within a Full Stack project description: 'Retrieves a list of all features defined for a specific Full Stack project. Features are used for feature flagging and server-side experimentation, allowing control over functionality and variables. Supports filtering by name, key, status, and pagination. The Knowledge Base article "Full Stack Experiments on Convert" provides context. ' tags: - Features 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 requestBody: $ref: '#/components/requestBodies/GetFeaturesListRequest' responses: '200': $ref: '#/components/responses/FeaturesListResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/features/{feature_id}: get: operationId: getFeature summary: Get details for a specific feature description: 'Retrieves detailed information about a single feature within a Full Stack project, identified by its `feature_id`. This includes its name, key, status, description, and defined variables (with their types and default values). ' tags: - Features 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: feature_id in: path required: true description: ID of the feature to be retrieved schema: type: integer - name: include description: 'Specifies the list of optional fields which would be included in the response. Otherwise, the fields that can be passed through this parameter would not be included in the response. Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/FeatureOptionalFields' responses: '200': $ref: '#/components/responses/FeatureResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/features/{feature_key}: get: operationId: getFeatureByKey summary: Get feature details by its unique key description: 'Retrieves detailed information about a single feature, identified by its user-defined `feature_key`. Useful if you have a human-readable key for a feature. Otherwise, similar to getting a feature by ID. ' tags: - Features 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: feature_key in: path required: true description: Key of the feature to be retrieved schema: type: string - name: include description: 'Specifies the list of optional fields which would be included in the response. Otherwise, the fields that can be passed through this parameter would not be included in the response. Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' in: query required: false schema: type: array items: $ref: '#/components/schemas/FeatureOptionalFields' responses: '200': $ref: '#/components/responses/FeatureResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/features/add: post: operationId: createFeature summary: Create a new feature for a Full Stack project description: 'Defines a new feature within a Full Stack project. Requires a name, a unique key, and a list of variables associated with the feature. Each variable has a key, type (string, boolean, integer, float, json), and a default value. Features are used in Full Stack experiments to control different code paths or configurations. ' tags: - Features 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 in: path required: true description: ID of the project into which the feature is to be stored schema: type: integer requestBody: $ref: '#/components/requestBodies/CreateFeatureRequest' responses: '201': $ref: '#/components/responses/FeatureResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/features/{feature_id}/update: post: operationId: updateFeature summary: Update an existing feature description: 'Modifies the configuration of an existing feature in a Full Stack project. This can include changing its name, description, status (active/archived), or its associated variables (adding, removing, or modifying variables and their default values). ' tags: - Features 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 in: path required: true description: ID of the project to which save/retrieved data is connected schema: type: integer - name: feature_id in: path required: true description: ID of the feature to be updated schema: type: integer requestBody: $ref: '#/components/requestBodies/UpdateFeatureRequest' responses: '200': $ref: '#/components/responses/FeatureResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/features/{feature_id}/delete: delete: operationId: deleteFeature summary: Delete a feature description: 'Permanently removes a feature from a Full Stack project. This action is irreversible. If the feature is in use by active experiments, consider its impact before deletion. ' tags: - Features 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: feature_id in: path required: true description: ID of the feature to be deleted schema: type: integer responses: '200': $ref: '#/components/responses/SuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/features/bulk-update: post: operationId: bulkFeaturesUpdate summary: Update multiple features at once description: 'Allows for changing the status (e.g., active, archived) of multiple features within a Full Stack project simultaneously. Requires a list of feature IDs and the target status. ' tags: - Features - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkUpdateFeaturesRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' /accounts/{account_id}/projects/{project_id}/features/bulk-delete: post: operationId: bulkFeaturesDelete summary: Delete multiple features at once description: 'Permanently removes multiple features from a Full Stack project in a single operation. Requires a list of feature IDs. This action is irreversible. ' tags: - Features - Bulk 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 requestBody: $ref: '#/components/requestBodies/BulkDeleteFeaturesRequest' responses: '200': $ref: '#/components/responses/BulkSuccessResponse' default: $ref: '#/components/responses/ErrorResponse' 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 components: parameters: CSRF_nonce: name: x-convert-nonce in: header required: false description: token provided to prevent CSRF attacks when authenticated from frontend systems schema: type: string AccountId: name: account_id in: path required: true description: ID of the account that owns the retrieved/saved data schema: type: integer ProjectId: name: project_id in: path required: true description: ID of the project to be retrieved schema: type: integer ExperienceId: name: experience_id in: path required: true description: ID of the experience schema: type: integer HeatmapId: name: heatmap_id in: path required: true description: ID of the heatmap. schema: type: string PlaceholderId: name: placeholder_id in: path required: true description: ID of the placeholder to be retrieved/updated/deleted schema: type: integer VisitorId: name: visitor_id in: path required: true description: The visitor identifier for visitor data operations schema: type: string PlanId: name: planId in: path required: true description: ID of the billing plan schema: type: string FeatureId: name: featureId in: path required: true description: ID of the plan feature schema: type: string LimitKey: name: limitKey in: path required: true description: Key of the plan limit (e.g., "pv", "tv", "pers") schema: type: string 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 requestBodies: AuthRequest: required: true description: Contains the necessary credentials or tokens for a user to authenticate their session, typically including username and password or MFA codes for cookie-based authentication. content: application/json: schema: $ref: '#/components/schemas/AuthRequestData' LogoutRequest: required: true description: Specifies which user sessions to invalidate (e.g., current, other, or all sessions for the authenticated user) for cookie-based authentication. content: application/json: schema: $ref: '#/components/schemas/LogoutRequestData' ForgotPasswordRequest: required: true description: Contains the username (typically email) of the user who has forgotten their password and is requesting a reset link for cookie-based authentication. content: application/json: schema: $ref: '#/components/schemas/ForgotPasswordRequestData' ResetPasswordConfirmRequest: required: true description: Includes the new password, confirmation of the new password, and the reset code received by the user to finalize the password reset process for cookie-based authentication. content: application/json: schema: $ref: '#/components/schemas/ResetPasswordConfirmRequestData' OAuthInitiateAuthorizationRequest: required: true description: Creates a pending OAuth authorization request and returns the Convert consent URL. content: application/json: schema: $ref: '#/components/schemas/OAuthInitiateAuthorizationRequestData' OAuthApproveAuthorizationRequest: required: true description: Approves a pending OAuth authorization request with a selected scope and issues a one-time exchange code. content: application/json: schema: $ref: '#/components/schemas/OAuthApproveAuthorizationRequestData' OAuthTokenRequest: required: true description: Exchanges a one-time authorization code for an OAuth bearer session token. content: application/json: schema: $ref: '#/components/schemas/OAuthTokenRequestData' OAuthCreateClientRequest: required: true description: Creates a new OAuth client application. content: application/json: schema: $ref: '#/components/schemas/OAuthCreateClientRequestData' OAuthUpdateClientRequest: required: true description: Updates an existing OAuth client application. content: application/json: schema: $ref: '#/components/schemas/OAuthUpdateClientRequestData' AcceptInvitationRequest: required: true description: Contains the unique hash token that a user received in an email invitation to collaborate on an account, used to accept the invitation. content: application/json: schema: $ref: '#/components/schemas/AcceptInvitationRequestData' CheckPartnerRequest: required: true description: Contains the email address to check if it belongs to a registered Convert partner, for potential extended API access (internal use). content: application/json: schema: $ref: '#/components/schemas/CheckPartnerRequestData' UserUpdateProfileDataRequest: required: true description: Contains user profile fields to be updated for cookie-based authenticated users, such as first name, last name, email, current password (for verification), new password, or MFA settings. content: application/json: schema: $ref: '#/components/schemas/UserProfileDataUpdate' ConfirmEmailRequest: required: true description: Contains the confirmation code sent to the user's new email address to verify and complete an email change request for cookie-based authenticated users. content: application/json: schema: $ref: '#/components/schemas/ConfirmEmailRequestData' UserUpdatePreferencesRequest: required: true description: A JSON object specifying the user's UI preferences to be updated for cookie-based authenticated users, such as editor settings or default display options for lists. These do not affect experiment execution. content: application/json: schema: $ref: '#/components/schemas/UserPreferences' UpdateTrialRequest: required: true description: Request body for creating or extending a Paddle trial subscription content: application/json: schema: $ref: '#/components/schemas/UpdateTrialRequest' CreatePaddleSubscriptionRequest: required: true description: Request body for creating a Paddle subscription with optional custom pricing and billing period content: application/json: schema: $ref: '#/components/schemas/CreatePaddleSubscriptionRequest' UpdatePaddleSubscriptionRequest: required: true description: Request body for updating an existing Paddle subscription content: application/json: schema: $ref: '#/components/schemas/CreatePaddleSubscriptionRequest' ChargePaddleCustomerRequest: required: true description: Request body for charging a Paddle customer directly (not tied to a Convert account) content: application/json: schema: $ref: '#/components/schemas/ChargePaddleCustomerRequest' OneTimeChargeRequest: required: true description: Request body for creating a one-time charge on a Paddle subscription content: application/json: schema: $ref: '#/components/schemas/OneTimeChargeRequest' UpdateAccountDataRequest: required: true description: Request body for updating account data (customizations and/or contract). Send only the fields you want to change. content: application/json: schema: $ref: '#/components/schemas/UpdateAccountDataRequest' InternalUpdateAccountDetailsRequest: required: true description: A JSON object containing the account details to be updated. content: application/json: schema: $ref: '#/components/schemas/InternalAccountDetailsUpdate' GetAccountLiveDataRequest: content: application/json: schema: $ref: '#/components/schemas/AccountLiveDataRequestData' description: Optional filters for retrieving live tracking events for an entire account. You can specify particular project IDs or event types (e.g., 'view_experience', 'conversion') to narrow down the results. Useful for a real-time overview of all activities. GetAccountHistoryRequest: content: application/json: schema: $ref: '#/components/schemas/AccountHistoryRequestData' description: Filters for retrieving the change history log for an account. Allows specifying date ranges, the user who made changes, types of objects changed (e.g., 'project', 'billing'), and methods of change (API or app UI). GetProjectHistoryRequest: content: application/json: schema: $ref: '#/components/schemas/ProjectHistoryRequestData' description: Filters for retrieving the change history log for a specific project. Allows specifying date ranges, users, types of project entities changed (e.g., 'experience', 'goal', 'audience'), and methods of change. TriggerExperienceScreenshotsRequest: content: application/json: schema: $ref: '#/components/schemas/TriggerExperienceScreenshotsRequestData' GetAccountActiveCompletedExperiencesListRequest: content: application/json: schema: $ref: '#/components/schemas/AccountExperiencesListRequestData' UpdateAccountDetailsRequest: required: true description: A JSON object containing the account details to be updated, such as company name, address, tax information, billing contact emails, or settings like allowing over-quota charges. content: application/json: schema: $ref: '#/components/schemas/AccountDetailsUpdate' CreateSubAccountRequest: required: true description: A JSON object with details for the new sub-account, including its name, the initial owner's name and email, and specific billing plan configurations and usage limits. content: application/json: schema: $ref: '#/components/schemas/SubAccountCreate' RequestAccountAddonsRequest: required: true description: A JSON object specifying the `addon` being requested (e.g., 'one_time_convert_launch' for a managed service) and, if applicable, collaborator details for whom the add-on is intended. content: application/json: schema: $ref: '#/components/schemas/RequestAccountAddonsData' StartPaymentSetupRequest: required: true description: An optional JSON object, though typically empty for this request. The primary action is to initiate a secure session with the payment provider for adding or updating payment methods. content: application/json: schema: $ref: '#/components/schemas/StartPaymentSetupRequestData' UpdateAccountUserAccessesRequest: required: true description: Contains the user identifier (either `email` for pending invitations or `user_id` for active collaborators) and the updated list of project accesses and their corresponding roles (e.g., 'admin', 'editor') for that user within the account. content: application/json: schema: $ref: '#/components/schemas/AccountUserAccessesUpdateRequestData' DeleteAccountUserAccessesRequest: required: true description: Contains the user identifier (email or user_id) and a list of project accesses to be revoked for that user. If the list of accesses is empty, it might imply removing the user from all projects or the account entirely, depending on implementation. content: application/json: schema: $ref: '#/components/schemas/AccountUserAccessesDelete' CreateAccountUserAccessesRequest: required: true description: Contains the invitee's email, first name, last name, and the initial list of project accesses and their roles. A custom message can be included in the invitation email. content: application/json: schema: $ref: '#/components/schemas/AccountUserAccessesCreateRequestData' CreateApiKeyRequest: content: application/json: schema: $ref: '#/components/schemas/CreateApiKeyRequestData' description: Contains the `name` for the new API key for easy identification, and an optional list of `projects` (by ID) to which this key will grant access. If `projects` is omitted, the key typically grants access to all projects in the account. required: true CreateSdkKeyRequest: content: application/json: schema: $ref: '#/components/schemas/CreateSdkKeyRequestData' description: Contains the `name` for the new SDK key, the target `environment` (e.g., 'production', 'staging') it applies to, and a boolean `has_secret` indicating if an SDK secret should be generated for secure SDK authentication. required: true UpdateSdkKeyRequest: description: Payload to update an existing SDK key required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSdkKeyRequestData' ImportVisitorsDataCsvRequest: content: multipart/form-data: schema: $ref: '#/components/schemas/ImportVisitorsDataCsvRequestData' description: Import Visitors Data Csv required: true ImportVisitorsDataPushRequest: content: application/json: schema: $ref: '#/components/schemas/ImportVisitorsDataPushRequestData' description: Import Visitor Data Push Request required: true GetVisitorDataListRequest: content: application/json: schema: $ref: '#/components/schemas/GetVisitorDataListRequestData' description: Optional filters for listing visitor data. You can search by visitor_id, or general search term. Also supports pagination (page, results_per_page) and sorting (sort_by, sort_direction). required: false UpdateVisitorDataItemRequest: required: true content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BaseDataItem' CreateVisitorDataItemRequest: required: true content: application/json: schema: type: object properties: visitor_id: type: string source: type: string data: $ref: '#/components/schemas/BaseDataItem' GetProjectsListRequest: content: application/json: schema: $ref: '#/components/schemas/GetProjectsListRequestData' description: Optional filters for listing projects. You can search by `name` or `description`, filter by `status` (active/inactive), `project_type` (web/fullstack), `tracking_script_release_type`, specific `tracking_script_version`, or use pagination (`page`, `results_per_page`). Also supports `only` and `except` for specific project IDs. required: false ExportProjectRequest: content: application/json: schema: $ref: '#/components/schemas/ExportProjectRequestData' description: Specifies which components of the project to include in the JSON export. You can choose to include/exclude the main project settings, and lists of specific experiences, audiences, locations, goals, or hypotheses by their IDs. Useful for backups or migrations. required: true ImportProjectRequest: content: multipart/form-data: schema: $ref: '#/components/schemas/ImportProjectRequestData' description: Contains the JSON `file` (previously exported from Convert) with the project data to be imported. This is used for creating a new project from an export or updating an existing one. required: true CreateProjectRequest: content: application/json: schema: $ref: '#/components/schemas/CreateProjectRequestData' description: Contains all necessary information to define a new project. This includes its `name`, `project_type` ('web' or 'fullstack'), initial `domains` (for web projects), and various `settings` like `time_zone`, `global_javascript`, `reporting_settings` (e.g. currency, outlier rules), and `integrations_settings`. required: true UpdateProjectRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateProjectRequestData' description: Contains the fields of the project to be updated. Any `domains` provided will replace the existing list. Other modifiable fields include `name`, `global_javascript`, `reporting_settings`, `settings` (like time zone, jQuery inclusion, GDPR options), and `integrations_settings`. required: true GetProjectLiveDataRequest: content: application/json: schema: $ref: '#/components/schemas/GetProjectLiveDataRequestData' description: Optional filters for project-specific live data. You can specify `experiences` (by ID), `event_types` (view_experience, conversion, transaction), `goals` (by ID), or `segments` to narrow down the real-time event feed. required: false BulkUpdateProjectsRequest: content: application/json: schema: $ref: '#/components/schemas/BulkUpdateProjectsRequestData' description: Contains a list of project `id`s and the `settings` (specifically `tracking_script.current_version`) to be applied to all specified projects. Useful for rolling out tracking script updates. required: true GetCdnImagesListRequest: content: application/json: schema: $ref: '#/components/schemas/GetCdnImagesListRequestData' description: Optional parameters to control pagination for the list of CDN images. Use `start_from` with an image key (filename) to list images after that specific one, and `max_results` to limit the number of images returned per request. required: false UploadImageRequest: content: multipart/form-data: schema: $ref: '#/components/schemas/UploadCdnImageRequestData' UploadImageNoNameRequest: content: multipart/form-data: schema: $ref: '#/components/schemas/UploadImageNoNameRequestData' UploadFileRequest: content: multipart/form-data: schema: $ref: '#/components/schemas/UploadFileRequestData' GetDomainsListRequest: content: application/json: schema: $ref: '#/components/schemas/GetDomainsListRequestData' description: Optional filters for listing domains within a project, primarily pagination parameters (`page`, `results_per_page`). GetDomainByUrlRequest: content: application/json: schema: $ref: '#/components/schemas/GetDomainByUrlRequestData' description: Contains the `url` (which can be an exact match or include wildcards like `*.example.com`) to search for among the project's associated domains. CheckCodeDomainRequest: content: application/json: schema: $ref: '#/components/schemas/CheckCodeDomainRequestData' description: Contains the specific `url` (which must fall under the path-parameter `domain_id`) on which to check for the presence and correct installation of the Convert tracking script. UpdateDomainRequestData: content: application/json: schema: $ref: '#/components/schemas/UpdateDomainRequestData' required: true CreateDomainRequest: content: application/json: schema: $ref: '#/components/schemas/CreateDomainRequestData' required: true BulkDeleteDomainsRequest: content: application/json: schema: $ref: '#/components/schemas/BulkDeleteDomainRequestData' GetExperiencesListRequest: content: application/json: schema: $ref: '#/components/schemas/GetExperiencesListRequestData' CreateExperienceRequest: content: application/json: schema: $ref: '#/components/schemas/CreateExperienceRequestData' CloneExperienceRequest: content: application/json: schema: $ref: '#/components/schemas/CloneExperienceRequestData' UpdateExperienceRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateExperienceRequestData' required: true BulkUpdateExperiencesRequest: content: application/json: schema: $ref: '#/components/schemas/BulkUpdateExperiencesRequestData' description: Contains a list of experience `id`s and the target `status` (e.g., 'active', 'paused', 'archived') to apply to all of them. Useful for managing multiple experiments efficiently. required: true BulkDeleteExperiencesRequest: content: application/json: schema: $ref: '#/components/schemas/BulkDeleteExperiencesRequestData' required: true UpdateExperienceChangeRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateExperienceChangeRequestData' required: true ExperienceReportTokenRequest: content: application/json: schema: $ref: '#/components/schemas/ExperienceReportTokenRequestData' GetExperienceLiveDataRequest: content: application/json: schema: $ref: '#/components/schemas/GetExperienceLiveDataRequestData' description: Optional filters for experience live data, such as specific goal IDs or event types to include in the feed. GetExperienceHistoryRequest: content: application/json: schema: $ref: '#/components/schemas/GetExperienceHistoryRequestData' description: Filters for retrieving the change history of a specific experience. Allows specifying date ranges, users, types of experience components changed (e.g., 'variation', 'goal', 'audience_linkage'), and methods of change. ConvertExperienceVariationRequest: content: application/json: schema: $ref: '#/components/schemas/ConvertExperienceVariationRequestData' UpdateExperienceVariationRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateExperienceVariationRequestData' GetExperienceAggregatedReportRequest: content: application/json: schema: $ref: '#/components/schemas/GetExperienceAggregatedReportRequestData' description: 'Parameters to customize the aggregated performance report for an experience. Key parameters include: - `start_time`, `end_time`, `utc_offset`: Define the reporting period. - `segments`: Apply filters based on visitor characteristics (e.g., device, browser, country, custom segments). - `stats_engine_processing`: Configure statistical settings like confidence level, test type (one-tail/two-tails), MAB strategy, and MDE for Frequentist; or decision/risk thresholds for Bayesian. - `goals`: (Optional) List of specific goal IDs to include in the report. If omitted, all goals attached to the experience are reported. - `metrics`: (Optional) List of specific metrics (e.g., ''conversion_rate'', ''avg_revenue_visitor'') to calculate and display. ' GetExperienceDailyReportRequest: content: application/json: schema: $ref: '#/components/schemas/GetExperienceDailyReportRequestData' description: 'Parameters to customize the daily performance report. Requires: - `goal`: The ID of the specific goal for which daily data is requested. - `report_type`: ''cumulative'' or ''non_cumulative'' data. - `metric`: The primary metric for the daily report (e.g., ''conversion_rate'', ''avg_revenue_per_visitor''). Also supports `start_time`, `end_time`, `utc_offset`, and `segments` for filtering. ' GetExperienceDailyTrafficAllocationRequest: content: application/json: schema: $ref: '#/components/schemas/GetExperienceDailyTrafficAllocationRequestData' description: 'Parameters to specify the date range (`start_time`, `end_time`, `utc_offset`) for retrieving the daily traffic allocation data, typically for experiences using Multi-Armed Bandit (MAB) strategies. ' ExportExperienceReportRequest: content: application/json: schema: $ref: '#/components/schemas/ExportExperienceReportRequestData' description: 'Parameters for exporting an experience report. Requires: - `report_type`: ''csv_aggregated'' (summary data per variation) or ''csv_daily'' (day-by-day data). - `data_type`: (For csv_daily only) ''cumulative'' or ''non_cumulative''. - `goals`: (Optional) List of goal IDs to include. Also supports `start_time`, `end_time`, `utc_offset`, `segments`, and `stats_engine_processing` settings to match the online report. ' RemoveExperienceReportRequest: content: application/json: schema: $ref: '#/components/schemas/RemoveExperienceReportRequestData' description: 'Parameters for removing specific data from an experience''s report. Requires: - `start_time`, `end_time`: Defines the period for data deletion. - `events`: An array specifying the types of events to delete (e.g., ''view_experience'', ''conversion'', ''transaction''). For ''conversion'' and ''transaction'', specific `goals` can be targeted. For ''transaction'', `revenue_start_value` and `revenue_end_value` can filter by revenue amount. - `simulate`: If `true` (default), returns a count of records that *would be* deleted. If `false`, performs permanent deletion. Also supports `utc_offset` and `segments`. ' ExportExperienceRawDataRequest: content: application/json: schema: $ref: '#/components/schemas/ExportExperienceRawDataRequestData' description: 'Parameters for requesting an export of raw, event-level tracking data. Requires: - `events`: List of event types to include (e.g., ''view_experience'', ''conversion'', ''transaction''). - `goals`: (Optional) List of goal IDs to filter conversion/transaction events. Also supports `start_time`, `end_time`, `utc_offset`, and `segments`. The export is typically delivered via an emailed link. ' GetExperienceHeatmapBackgroundRequest: description: Optional filters for the heatmap background image (e.g. device). Passed in body for extensibility. content: application/json: schema: $ref: '#/components/schemas/GetExperienceHeatmapBackgroundRequestData' required: false GetExperienceHeatmapOverlayRequest: description: Optional filters for the heatmap overlay image (e.g. device, interaction type). Passed in body for extensibility. content: application/json: schema: $ref: '#/components/schemas/GetExperienceHeatmapOverlayRequestData' required: false CreateSectionRequest: description: 'Defines a new section for a Multivariate (MVT) experience. Requires: - `id`: A unique 1-2 character ID for the section within this experience. - `name`: A descriptive name for the section (e.g., "Headline Area", "CTA Button Style"). - `versions`: An array defining the initial alternatives (versions) for this section, each with its own set of `changes`. **IMPORTANT:** Adding or removing sections impacts MVT variation combinations and can invalidate running tests. ' content: application/json: schema: $ref: '#/components/schemas/CreateSectionRequestData' required: true UpdateSectionRequest: description: 'Updates an existing section in an MVT experience. Requires the section''s `id` and `name`. The `versions` array provided will replace all existing versions for this section. Each version object should include its `id`, `name`, and `changes`. If a version ID is new, it will be created. Existing versions not in the list will be removed. **IMPORTANT:** Modifying sections impacts MVT variation combinations. ' content: application/json: schema: $ref: '#/components/schemas/UpdateSectionRequestData' required: true UpdateExperienceSectionsRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateExperienceSectionsRequestData' required: true CreateSectionVersionRequest: description: 'Adds a new version (alternative) to an existing section within an MVT experience. Requires: - `id`: A unique 1-2 character ID for this version within its section. - `name`: A descriptive name for the version (e.g., "Red Button", "Short Headline"). - `changes`: An array defining the modifications (JS, CSS) for this specific version. **IMPORTANT:** Adding versions changes the MVT combinations. ' content: application/json: schema: $ref: '#/components/schemas/CreateSectionVersionRequestData' required: true UpdateSectionVersionRequest: description: 'Updates an existing version within an MVT section. Allows changing the `name` or the `changes` (JS, CSS modifications) associated with this version. The `id` of the version must be provided. ' content: application/json: schema: $ref: '#/components/schemas/UpdateSectionVersionRequestData' required: true GetGoalsRequest: content: application/json: schema: $ref: '#/components/schemas/GetGoalsRequestData' CreateGoalRequest: content: application/json: schema: $ref: '#/components/schemas/CreateGoalRequestData' description: Goal request object to create goal data. required: true UpdateGoalRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateGoalRequestData' description: 'Contains the fields of the goal to be updated. This can include `name`, `description`, `status`, `type`, `settings` (specific to goal type), or `triggering_rule`. ' required: true BulkUpdateGoalsRequest: content: application/json: schema: $ref: '#/components/schemas/BulkUpdateGoalRequestData' description: Contains a list of goal `id`s and the target `status` (e.g., 'active', 'archived') to apply to all of them. required: true BulkDeleteGoalsRequest: content: application/json: schema: $ref: '#/components/schemas/BulkDeleteGoalRequestData' GetTagsRequest: content: application/json: schema: $ref: '#/components/schemas/GetTagsListRequestData' description: Optional filters for listing tags, primarily `search` for tag names and pagination parameters (`page`, `results_per_page`). Also supports `only`/`except` for specific tag IDs. CreateTagRequest: content: application/json: schema: $ref: '#/components/schemas/CreateTagRequestData' required: true UpdateTagRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateTagRequestData' required: true BulkDeleteTagsRequest: content: application/json: schema: $ref: '#/components/schemas/BulkDeleteTagRequestData' GetHypothesesRequest: content: application/json: schema: $ref: '#/components/schemas/GetHypothesesListRequestData' CreateHypothesisRequest: content: application/json: schema: $ref: '#/components/schemas/CreateHypothesisRequestData' required: true UpdateHypothesisRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateHypothesisRequestData' required: true UpdateHypothesisStatusRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateHypothesisStatusRequestData' required: true BulkUpdateHypothesesRequest: content: application/json: schema: $ref: '#/components/schemas/BulkUpdateHypothesesRequestData' description: Contains a list of hypothesis `id`s and the target `status` to apply to all of them. required: true BulkDeleteHypothesesRequest: content: application/json: schema: $ref: '#/components/schemas/BulkDeleteHypothesesRequestData' required: true GetSessionsRequest: content: application/json: schema: $ref: '#/components/schemas/GetSessionsListRequestData' GetSignalSessionsRequest: content: application/json: schema: $ref: '#/components/schemas/GetSignalSessionsListRequestData' GetKnowledgeBasesRequest: content: application/json: schema: $ref: '#/components/schemas/GetKnowledgeBasesListRequestData' CreateKnowledgeBasesRequest: content: application/json: schema: $ref: '#/components/schemas/CreateKnowledgeBaseRequestData' UpdateKnowledgeBasesStatusRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateKnowledgeBasesStatusRequestData' required: true BulkUpdateKnowledgeBasesRequest: content: application/json: schema: $ref: '#/components/schemas/BulkUpdateKnowledgeBasesRequestData' description: Contains a list of Knowledge Base entry `id`s and the target `status` to apply to all of them. required: true BulkDeleteKnowledgeBasesRequest: content: application/json: schema: $ref: '#/components/schemas/BulkDeleteKnowledgeBasesRequestData' required: true CreateObservationRequest: content: application/json: schema: $ref: '#/components/schemas/CreateObservationRequestData' required: true UpdateObservationRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateObservationRequestData' required: true GetObservationsRequest: content: application/json: schema: $ref: '#/components/schemas/GetObservationsListRequestData' BulkUpdateObservationsRequest: content: application/json: schema: $ref: '#/components/schemas/BulkUpdateObservationsRequestData' description: Contains a list of observation `id`s and the target `status` (e.g., 'active', 'archived') to apply to all of them. required: true BulkDeleteObservationsRequest: content: application/json: schema: $ref: '#/components/schemas/BulkDeleteObservationsRequestData' required: true GetLocationsListRequest: content: application/json: schema: $ref: '#/components/schemas/GetLocationsListRequestData' CreateLocationRequest: content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateLocationRequestData' required: true UpdateLocationRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateLocationRequestData' required: true BulkUpdateLocationsRequest: content: application/json: schema: $ref: '#/components/schemas/BulkUpdateLocationsRequestData' description: Contains a list of location `id`s and the target `status` (e.g., 'active', 'archived') to apply to all of them. required: true BulkDeleteLocationsRequest: content: application/json: schema: $ref: '#/components/schemas/BulkDeleteLocationsRequestData' GetAudiencesListRequest: content: application/json: schema: $ref: '#/components/schemas/GetAudiencesListRequestData' CreateAudienceRequest: content: application/json: schema: allOf: - $ref: '#/components/schemas/CreateAudienceRequestData' required: true UpdateAudienceRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateAudienceRequestData' required: true BulkUpdateAudiencesRequest: content: application/json: schema: $ref: '#/components/schemas/BulkUpdateAudienceRequestData' description: Contains a list of audience `id`s and the target `status` (e.g., 'active', 'archived') to apply to all of them. required: true BulkDeleteAudiencesRequest: content: application/json: schema: $ref: '#/components/schemas/BulkDeleteAudienceRequestData' GetFeaturesListRequest: content: application/json: schema: $ref: '#/components/schemas/GetFeaturesListRequestData' CreateFeatureRequest: content: application/json: schema: $ref: '#/components/schemas/CreateFeatureRequestData' required: true UpdateFeatureRequest: content: application/json: schema: $ref: '#/components/schemas/UpdateFeatureRequestData' required: true BulkUpdateFeaturesRequest: content: application/json: schema: $ref: '#/components/schemas/BulkUpdateFeatureRequestData' description: Contains a list of feature `id`s and the target `status` (e.g., 'active', 'archived') to apply to all of them. required: true BulkDeleteFeaturesRequest: content: application/json: schema: $ref: '#/components/schemas/BulkDeleteFeatureRequestData' GenerateTextVariantsRequest: content: application/json: schema: $ref: '#/components/schemas/GenerateTextVariantsRequestData' required: true GenerateCodeVariantRequest: content: application/json: schema: $ref: '#/components/schemas/GenerateCodeVariantRequestData' required: true GetVisitorDataPlaceholdersListRequest: content: application/json: schema: $ref: '#/components/schemas/GetPlaceholdersListRequestData' description: Filter visitor data placeholders list required: false CreateVisitorDataPlaceholderRequest: content: application/json: schema: $ref: '#/components/schemas/CreatePlaceholderRequestData' description: Create visitor data placeholder schema required: true UpdateVisitorDataPlaceholderRequest: content: application/json: schema: $ref: '#/components/schemas/UpdatePlaceholderRequestData' description: Update visitor data placeholder schema required: true CreatePlanRequest: required: true description: Request body for creating a new billing plan content: application/json: schema: $ref: '#/components/schemas/CreatePlanRequest' UpdatePlanRequest: required: true description: Request body for updating a billing plan content: application/json: schema: $ref: '#/components/schemas/UpdatePlanRequest' CreatePlanFeatureRequest: required: true description: Request body for creating a new plan feature content: application/json: schema: $ref: '#/components/schemas/CreatePlanFeatureRequest' UpdatePlanFeatureRequest: required: true description: Request body for updating a plan feature content: application/json: schema: $ref: '#/components/schemas/UpdatePlanFeatureRequest' CreatePlanLimitRequest: required: true description: Request body for creating a new plan limit content: application/json: schema: $ref: '#/components/schemas/CreatePlanLimitRequest' UpdatePlanLimitRequest: required: true description: Request body for updating a plan limit content: application/json: schema: $ref: '#/components/schemas/UpdatePlanLimitRequest' UserSessionRevokeRequest: required: true description: Identifies a single user session to revoke, using the session id returned by /user/sessions. content: application/json: schema: $ref: '#/components/schemas/UserSessionRevokeRequestData' responses: AuthResponse: description: 'If cookie-based authentication is successful, the session token is returned in a cookie named `sid` and the response body contains the authenticated user''s data. If further steps are needed (e.g., MFA code, new password), the response indicates this and provides a `sessionToken` for the next step. If authentication fails, no cookie is set and the body contains error details. ' content: application/json: schema: $ref: '#/components/schemas/AuthResponse' OAuthInitiateAuthorizationResponse: description: OAuth authorization request created successfully. content: application/json: schema: $ref: '#/components/schemas/OAuthInitiateAuthorizationResponseData' OAuthAuthorizationRequestDetailsResponse: description: Pending OAuth authorization request details for consent screens. content: application/json: schema: $ref: '#/components/schemas/OAuthAuthorizationRequestDetailsResponseData' OAuthApproveAuthorizationResponse: description: OAuth authorization request approved; includes callback redirect URL with one-time code. content: application/json: schema: $ref: '#/components/schemas/OAuthApproveAuthorizationResponseData' OAuthTokenResponse: description: One-time code exchanged for a scoped OAuth bearer session token. content: application/json: schema: $ref: '#/components/schemas/OAuthTokenResponseData' OAuthClientsListResponse: description: List of OAuth clients for the current user. content: application/json: schema: $ref: '#/components/schemas/OAuthClientsListResponseData' OAuthClientResponse: description: Single OAuth client. content: application/json: schema: $ref: '#/components/schemas/OAuthClientResponseData' OAuthDeleteClientResponse: description: OAuth client deletion confirmation. content: application/json: schema: $ref: '#/components/schemas/OAuthDeleteClientResponseData' AccessRolesListResponse: description: A list of all available user access roles in the Convert system (e.g., Owner, Admin, Editor), detailing the permissions associated with each role. content: application/json: schema: $ref: '#/components/schemas/AccessRolesListResponseData' UserDataResponse: description: Contains the profile data, UI preferences, and settings for the authenticated user (typically for cookie-based sessions). content: application/json: schema: $ref: '#/components/schemas/UserData' UserSessionsListResponse: description: List of authorized sessions (cookie-based and OAuth) for the current user. content: application/json: schema: $ref: '#/components/schemas/UserSessionsListResponseData' UserSessionRevokeResponse: description: User session revoked successfully. content: application/json: schema: $ref: '#/components/schemas/UserSessionRevokeResponseData' UserSessionRevokeAllResponse: description: All active user sessions were revoked. content: application/json: schema: $ref: '#/components/schemas/UserSessionRevokeAllResponseData' UserMfaSecretResponse: description: Contains the Multi-Factor Authentication (MFA) secret for the authenticated user. This secret is used to set up an authenticator app (like Google Authenticator) to generate time-based one-time passwords (TOTPs). content: application/json: schema: $ref: '#/components/schemas/UserMfaSecret' ManagementAccountListResponse: description: List of accounts with subscription info content: application/json: schema: $ref: '#/components/schemas/ManagementAccountListResponse' UpdateTrialResponse: description: Trial creation or extension result content: application/json: schema: $ref: '#/components/schemas/UpdateTrialResponse' CreatePaddleSubscriptionResponse: description: Result of creating a Paddle subscription content: application/json: schema: $ref: '#/components/schemas/CreatePaddleSubscriptionResponse' UpdatePaddleSubscriptionResponse: description: Result of updating a Paddle subscription content: application/json: schema: $ref: '#/components/schemas/CreatePaddleSubscriptionResponse' OneTimeChargeResponse: description: One-time charge result content: application/json: schema: $ref: '#/components/schemas/OneTimeChargeResponse' ChargePaddleCustomerResponse: description: Paddle customer charge result content: application/json: schema: $ref: '#/components/schemas/ChargePaddleCustomerResponse' GetAccountDataResponse: description: Current account data including customizations and contract content: application/json: schema: $ref: '#/components/schemas/GetAccountDataResponse' UpdateAccountDataResponse: description: Updated account data (customizations and/or contract) content: application/json: schema: $ref: '#/components/schemas/UpdateAccountDataResponse' CancelPaddleSubscriptionResponse: description: Result of canceling the Paddle subscription content: application/json: schema: $ref: '#/components/schemas/CancelPaddleSubscriptionResponse' GetPaddleSubscriptionResponse: description: Paddle subscription details content: application/json: schema: $ref: '#/components/schemas/GetPaddleSubscriptionResponse' AccountsListResponse: description: A list of accounts that the authenticated user has access to. Each account object includes basic details like ID, name, and the user's access role for that account. content: application/json: schema: $ref: '#/components/schemas/AccountsListResponseData' BillingPlansListResponse: description: A list of all active billing plans offered by Convert, detailing features, usage limits (e.g., tested visitors, projects), and pricing for each plan. content: application/json: schema: $ref: '#/components/schemas/BillingPlansListResponseData' AccountDetailsResponse: description: Detailed information for a specific account, including its name, type (main/sub), billing information, usage limits, subscribed products (Experiences, Deploy), and general settings. content: application/json: schema: $ref: '#/components/schemas/AccountDetailsResponseData' StartPaymentSetupResponse: description: Contains a `client_secret` (e.g., from Stripe) required by the frontend UI to securely complete the process of adding or updating an account's payment method. content: application/json: schema: $ref: '#/components/schemas/StartPaymentSetupResponseData' BillingPortalResponse: description: Authenticated Paddle billing portal URL for the given account. content: application/json: schema: $ref: '#/components/schemas/BillingPortalResponseData' PlanSetupUsersResponse: description: A list of users associated with an account, typically retrieved for notifying them about billing plan setup or changes. Includes user ID, email, and name. content: application/json: schema: $ref: '#/components/schemas/PlanSetupUsersResponseData' GenerateTextVariantsResponse: description: A list of AI-generated text variations based on the provided input content, model framework, and principle. Each variant is a string. content: application/json: schema: $ref: '#/components/schemas/GenerateTextVariantsResponseData' GenerateCodeVariantResponse: description: A list of AI-generated code variation based on the provided input code. content: application/json: schema: $ref: '#/components/schemas/GenerateCodeVariantResponseData' text/event-stream: schema: $ref: '#/components/schemas/GenerateCodeVariantResponseStreamData' AccountUsersAccessesListResponse: description: A list of users who are collaborators on the specified account, detailing their names, emails, and the specific projects/roles they have access to. content: application/json: schema: $ref: '#/components/schemas/AccountUsersAccessesListResponse' AccountUserAccesses: description: Details the access permissions for a single user within a specific account, including their roles for various projects. content: application/json: schema: $ref: '#/components/schemas/AccountUserAccessesResponse' ApiKeysListResponse: description: A list of API keys configured for the account. Each entry includes the key's name, its ID (part of the key itself), and the projects it's scoped to. The secret is masked for existing keys. content: application/json: schema: $ref: '#/components/schemas/ApiKeysListResponse' ApiKeyResponse: description: Details of a single API key, including its name, ID, associated projects, and the API secret (only shown in full upon creation). content: application/json: schema: $ref: '#/components/schemas/ApiKey' SessionsListResponse: description: A list of recorded raw visitor sessions for a project, typically used for deep-dive analytics or integrations requiring session-level data. content: application/json: schema: $ref: '#/components/schemas/SessionsListResponseData' SignalSessionsListResponse: description: "A list of Convert Signals\u2122 sessions, highlighting visitor interactions that indicate potential frustration\ \ or usability issues (e.g., rage clicks, dead clicks). Includes session duration, visited pages, location, and other\ \ metadata." content: application/json: schema: $ref: '#/components/schemas/SignalSessionsListResponseData' SdkKeysListResponse: description: A list of SDK keys defined for a project. Each key is associated with an environment (e.g., production, staging) and is used by Convert's Full Stack SDKs for authentication and configuration fetching. content: application/json: schema: $ref: '#/components/schemas/SdkKeysListResponseData' SdkKeyResponse: description: Details of a single SDK key, including its name, the key string itself, the environment it's for, and whether it uses a secret for authentication. The secret is only shown in full upon creation if auto-generated. content: application/json: schema: $ref: '#/components/schemas/SdkKey' ProjectsListResponse: description: A list of projects accessible to the user within an account. Each project entry includes its ID, name, type (web/fullstack), status, and potentially other summary information depending on `include` parameters. content: application/json: schema: $ref: '#/components/schemas/ProjectsListResponseData' ProjectExportResponse: description: A JSON file containing the exported data for a project, including its settings, experiences, goals, audiences, etc. This file can be used for backup or migration. content: download/json: schema: $ref: '#/components/schemas/ProjectsExportResponseFile' ProjectResponse: description: Detailed information for a single project, including its settings, associated domains, default goals/audiences/locations, integrations, and usage statistics (if requested via `include`). content: application/json: schema: $ref: '#/components/schemas/Project' CdnImagesListResponse: description: A list of images uploaded to the Convert CDN for a project. Each entry provides the `cdn_url` for accessing the image and its `key` (filename). content: application/json: schema: $ref: '#/components/schemas/CdnImagesListResponseData' ImageCdnResponse: description: Details of a single image uploaded to the CDN, including its `cdn_url` and `key`. content: application/json: schema: $ref: '#/components/schemas/CdnImage' FileResponse: description: Details of a single uploaded file, including its access `url`, storage `key`, original `file_name`, `file_size`, and `mime_type`. content: application/json: schema: $ref: '#/components/schemas/UploadedFile' FileDataResponse: description: Contains the base64 encoded `content` of a requested file, along with its metadata like `key`, `file_name`, and `mime_type`. content: application/json: schema: $ref: '#/components/schemas/FileData' DomainsListResponse: description: A list of website domains associated with a project. Each entry includes the domain `id`, `url`, and a flag `code_installed` indicating if the Convert tracking script was detected. content: application/json: schema: $ref: '#/components/schemas/DomainsListResponseData' DomainResponse: description: Details for a single domain associated with a project, including its `id`, `url`, and `code_installed` status. content: application/json: schema: $ref: '#/components/schemas/Domain' ExperiencesListResponse: description: A list of experiences (A/B tests, personalizations, etc.) within a project. Each entry includes summary information like ID, name, type, status, and potentially high-level stats depending on `include` parameters. content: application/json: schema: $ref: '#/components/schemas/ExperiencesListResponseData' ExperienceResponse: description: Comprehensive details for a single experience, including its configuration, variations, associated audiences, locations, goals, integrations, and settings. content: application/json: schema: $ref: '#/components/schemas/Experience' ExperienceReportTokenResponse: description: Contains the generated `token` for read-only access to an experience's report and its `expiration` timestamp. content: application/json: schema: $ref: '#/components/schemas/ExperienceReportToken' ExperienceSectionsListResponse: description: A list of sections defined for a multivariate (MVT) experience. Each section includes its `id`, `name`, and an array of its `versions` (alternatives). content: application/json: schema: $ref: '#/components/schemas/ExperienceSectionsListResponseData' ExperienceSectionVersionResponse: description: Details for a single version within an MVT experience section, including its `id`, `name`, and the `changes` (CSS, JS modifications) it applies. content: application/json: schema: $ref: '#/components/schemas/ExperienceSectionVersionResponseData' ExperienceVariationResponse: description: Detailed information for a single experience variation, including its `id`, `name`, `description`, `is_baseline` status, `traffic_distribution`, `status` (running/stopped), and an array of `changes` it implements. content: application/json: schema: $ref: '#/components/schemas/ExpandedExperienceVariationData' ExperienceReportSettingsResponse: description: The current reporting settings for an experience, such as `confidence_level`, `stats_methodology` (Frequentist/Bayesian), MAB strategy, `primary_metric`, and `outlier` detection rules. content: application/json: schema: $ref: '#/components/schemas/ExperienceReportSettingsData' ExperienceAggregatedReportResponse: description: The main performance report for an experience, showing aggregated data (visitors, conversions, conversion rate, improvement, confidence/chance to win) for each variation, broken down by all attached goals. content: application/json: schema: $ref: '#/components/schemas/ExperienceAggregatedReportResponseData' ExperienceDailyReportResponse: description: A day-by-day breakdown of performance metrics for an experience, specific to a single goal and metric (e.g., daily conversion rate for "Purchases"). Includes data for each variation. content: application/json: schema: $ref: '#/components/schemas/ExperienceDailyReportResponseData' ExperienceDailyTrafficAllocationResponse: description: For experiences using Multi-Armed Bandit (MAB), this shows the daily percentage of traffic allocated to each variation over time, illustrating how the MAB strategy adapted. content: application/json: schema: $ref: '#/components/schemas/ExperienceDailyTrafficAllocationResponseData' ExportExperienceReportResponse: description: Contains a `download_url` for the generated experience report (CSV or PDF) and an `expire_at` timestamp for the URL. content: application/json: schema: $ref: '#/components/schemas/ExperienceReportExportResponseData' RemoveExperienceReportResponse: description: If `simulate=true` was used in the request, this returns a count of data records per event type that *would have been* deleted. If `simulate=false`, confirms successful deletion (often via a general SuccessResponse). content: application/json: schema: $ref: '#/components/schemas/RemoveExperienceReportResponseData' ExperienceHeatmapBackgroundResponse: description: Heatmap background image for the given heatmap id and device. content: application/json: schema: $ref: '#/components/schemas/ExperienceHeatmapBackgroundResponseData' ExperienceHeatmapOverlayResponse: description: Heatmap overlay (interaction) image for the given heatmap id, device, and interaction type. content: application/json: schema: $ref: '#/components/schemas/ExperienceHeatmapOverlayResponseData' ExportExperienceRawDataResponse: description: Contains a `jobId` for the asynchronous raw data export process. The actual data link is typically sent via email upon job completion. content: application/json: schema: $ref: '#/components/schemas/ExportExperienceRawDataResponseData' 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' GoalsListResponse: description: A list of conversion goals defined within a project. Each goal entry includes its ID, name, type, status, and potentially usage statistics if requested. content: application/json: schema: $ref: '#/components/schemas/GoalsListResponseData' GoalResponse: description: Detailed information for a single conversion goal, including its name, type (e.g., 'visits_page', 'revenue'), configuration settings (like target URL or CSS selector), and triggering rules for advanced goals. content: application/json: schema: $ref: '#/components/schemas/Goal' LiveDataEventsListResponse: description: A list of recent live tracking events, each detailing the event type (view_experience, conversion, transaction), associated experience/variation, visitor segments (device, browser, country), and timestamp. content: application/json: schema: $ref: '#/components/schemas/LiveDataEventsListResponseData' ChangeHistoryListResponse: description: A log of changes made within an account or project. Each entry details the `event` (e.g., 'create', 'update', 'delete'), the `object` changed (e.g., 'experience', 'goal'), `object_id`, `user` who made the change, `timestamp`, and `changes` (old and new values). content: application/json: schema: $ref: '#/components/schemas/ChangeHistoryListResponseData' TagsListResponse: description: A list of tags defined within a project. Each tag has an `id`, `name`, and `description`. Tags are used for organizing entities like experiences or goals. content: application/json: schema: $ref: '#/components/schemas/TagsListResponseData' TagResponse: description: Details for a single tag, including its `id`, `name`, and `description`. content: application/json: schema: $ref: '#/components/schemas/Tag' HypothesesListResponse: description: A list of hypotheses defined within a project. Each entry includes the hypothesis ID, name, objective, prioritization score, status, and associated experiences/tags. content: application/json: schema: $ref: '#/components/schemas/HypothesesListResponseData' HypothesisResponse: description: Detailed information for a single hypothesis, including its name, objective, prioritization model (PIE/ICE) and scores, status, start/end dates, summary, and links to associated experiences and tags. content: application/json: schema: $ref: '#/components/schemas/Hypothesis' KnowledgeBasesListResponse: description: A list of Knowledge Base entries within a project. Each entry represents a learning or outcome from a tested hypothesis, including its name, summary, status, and creator. content: application/json: schema: $ref: '#/components/schemas/KnowledgeBasesListResponseData' VisitorDataItemResponse: description: Single visitor data item. content: application/json: schema: $ref: '#/components/schemas/VisitorDataItem' KnowledgeBaseResponse: description: Detailed information for a single Knowledge Base entry, including its name, summary of findings, status (active/archived), creator, and associated tags. content: application/json: schema: $ref: '#/components/schemas/KnowledgeBase' ObservationsListResponse: description: A list of observations recorded within a project. Each observation includes its name, description, reference URL, status, creator, attachments, and associated tags. content: application/json: schema: $ref: '#/components/schemas/ObservationsListResponseData' ObservationResponse: description: Detailed information for a single observation, including its name, description, URL, status, creator, attachments (images/files), and associated tags. content: application/json: schema: $ref: '#/components/schemas/Observation' LocationsListResponse: description: A list of locations defined within a project. Each location entry includes its ID, name, status, and potentially usage statistics if requested. Locations define where experiences run. content: application/json: schema: $ref: '#/components/schemas/LocationsListResponseData' LocationResponse: description: Detailed information for a single location, including its name, status, the `rules` (URL patterns, JS conditions) that define it, and the `trigger` type (e.g., 'upon_run', 'manual'). content: application/json: schema: $ref: '#/components/schemas/Location' LocationsPresetsListResponse: description: A list of predefined location templates (presets) provided by Convert, such as "All Pages" or "Homepage," which can be used as a starting point for creating custom locations. content: application/json: schema: $ref: '#/components/schemas/LocationsPresetsListResponseData' AudiencesListResponse: description: A list of audiences defined within a project. Each audience entry includes its ID, name, type (permanent, transient, segmentation), status, and potentially usage statistics. Audiences define who sees an experience. content: application/json: schema: $ref: '#/components/schemas/AudiencesListResponseData' AudienceResponse: description: Detailed information for a single audience, including its name, type, status, and the `rules` (visitor data, traffic source, cookie values, JS conditions) that define its criteria. content: application/json: schema: $ref: '#/components/schemas/Audience' AudiencesPresetsListResponse: description: A list of predefined audience templates (presets) provided by Convert, such as "New Visitors" or "Mobile Users," which can be used as a starting point for creating custom audiences. content: application/json: schema: $ref: '#/components/schemas/AudiencesPresetsListResponseData' 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' SuccessResponse: description: 'A generic success response, typically used for operations that don''t return specific data (like deletions or some updates). The `code` is usually 200, and `message` confirms the successful action. ' content: application/json: schema: $ref: '#/components/schemas/SuccessData' ImportProjectDataSuccessResponse: description: 'Confirms successful import of project data. Includes a list of `imported` entities (experiences, audiences, locations, goals, hypotheses) with their newly assigned IDs in the target project. ' content: application/json: schema: $ref: '#/components/schemas/ImportProjectDataSuccess' BulkSuccessResponse: description: 'Indicates the outcome of a bulk operation (e.g., bulk update or delete). Provides a general success `message` and an `errors` array listing any entities that could not be processed, along with the reason for failure for each. ' content: application/json: schema: $ref: '#/components/schemas/BulkSuccessData' ImageResponse: description: 'The raw binary image data (e.g., PNG, JPEG) for a requested screenshot or uploaded image. The `Content-Type` header will specify the image format. ' content: image/png: schema: type: string format: binary ImageResponseBase64: description: 'A JSON object containing the `data` field, which holds the base64 encoded string of an image. Useful for transferring image data within JSON payloads. ' content: application/json: schema: $ref: '#/components/schemas/Base64Image' FeaturesListResponse: description: A list of features defined within a Full Stack project. Each feature entry includes its ID, name, key, status, and potentially usage statistics if requested. content: application/json: schema: $ref: '#/components/schemas/FeaturesListResponseData' FeatureResponse: description: Detailed information for a single feature in a Full Stack project, including its name, key, status, description, and an array of its `variables` (each with a key, type, and default value). content: application/json: schema: $ref: '#/components/schemas/Feature' CheckPartnerResponse: description: 'Indicates whether the queried email `allowed` for extended partner API access and if this access was `alreadyGranted`. ' content: application/json: schema: $ref: '#/components/schemas/CheckPartnerData' SuccessSDKKey: description: 'A response containing the generated `sdk_key` string for a Full Stack project environment. ' content: application/json: schema: $ref: '#/components/schemas/SDKKeyData' SuccessGeneratedDebugToken: description: 'A response containing the generated `value` (the debug token itself) and its `ttl` (time-to-live as a Unix timestamp) for previewing and QAing experiences. ' content: application/json: schema: $ref: '#/components/schemas/GeneratedDebugTokenDataResponse' VisitorDataPlaceholdersListResponse: description: Response object containing the list of visitor data placeholders defined in the project content: application/json: schema: $ref: '#/components/schemas/PlaceholdersListResponseData' VisitorDataPlaceholderResponse: description: Response object containing a single visitor data placeholder content: application/json: schema: $ref: '#/components/schemas/VisitorDataPlaceholder' VisitorsDataListResponse: description: A list of visitors data for a project content: application/json: schema: $ref: '#/components/schemas/VisitorDataListResponseData' PlanManagementResponse: description: Response containing a billing plan content: application/json: schema: $ref: '#/components/schemas/PlanManagementResponse' PlanManagementListResponse: description: Response containing a list of billing plans content: application/json: schema: $ref: '#/components/schemas/PlanManagementListResponse' PlanFeatureResponse: description: Response containing a plan feature content: application/json: schema: $ref: '#/components/schemas/PlanFeatureResponse' PlanFeatureListResponse: description: Response containing a list of plan features content: application/json: schema: $ref: '#/components/schemas/PlanFeatureListResponse' PlanLimitResponse: description: Response containing a plan limit content: application/json: schema: $ref: '#/components/schemas/PlanLimitResponse' PlanLimitListResponse: description: Response containing a list of plan limits content: application/json: schema: $ref: '#/components/schemas/PlanLimitListResponse' schemas: UpdateTrialAction: type: string enum: - created - extended CreatePaddleSubscriptionRequest: type: object required: - plan_ids properties: plan_ids: type: array description: IDs of the billing plans (must share the same billing cycle). items: type: string minItems: 1 prices: type: object description: Custom price overrides keyed by plan_id. Values are price amounts in cents (e.g. "2900" for $29.00). Omit a plan_id to use catalog price. additionalProperties: type: string trial_days: type: integer description: Number of trial days. Mutually exclusive with start_date/end_date. minimum: 1 start_date: type: string format: date-time description: Subscription billing period start (RFC 3339). Mutually exclusive with trial_days. end_date: type: string format: date-time description: Subscription billing period end (RFC 3339). Mutually exclusive with trial_days. collection_mode: type: string enum: - automatic - manual default: manual description: 'Billing method: automatic = Payment Method on File, manual = Invoice' proration_billing_mode: type: string enum: - prorated_immediately - do_not_bill default: prorated_immediately description: Pro-rata handling when updating a subscription (ignored on create) purchase_order_number: type: string description: Purchase order number for invoice (manual) billing. Passed to Paddle billing_details. price_names: type: object description: Custom price display names keyed by plan_id. Overrides the default "Per Month"/"Per Year" label. additionalProperties: type: string payment_terms: $ref: '#/components/schemas/PaymentTerms' CreatePaddleSubscriptionResponse: type: object properties: data: type: object properties: success: type: boolean subscription_id: type: string description: Paddle subscription ID (if subscription was created immediately) transaction_id: type: string description: Paddle transaction ID (for paid automatic-mode subs requiring customer checkout) payment_link: type: string description: Payment link URL for the customer to complete subscription setup message: type: string ManagementAccountListItem: type: object properties: id: type: string name: type: string plan_status: $ref: '#/components/schemas/PlanStatus' billing_cycle_start: type: integer nullable: true billing_cycle_end: type: integer nullable: true plan_ids: type: array items: type: string billing_provider: type: string nullable: true stripe_customer_id: type: string nullable: true paddle_customer_id: type: string nullable: true paddle_subscription_id: type: string nullable: true has_customizations: type: boolean description: Whether the account has extra_features customizations (limit overrides, capability overrides) has_contract: type: boolean description: Whether the account has an active contract plan_settings: type: object nullable: true description: Per-plan custom pricing and Paddle price IDs. Keyed by plan_id. additionalProperties: type: object properties: live_price_id: type: string description: Paddle price ID (production/live) staging_price_id: type: string description: Paddle price ID (sandbox/staging) price: type: number description: Custom price in dollars (e.g. 336.50 for $336.50) plan_duration: type: string description: Billing cycle duration (e.g. "1M" for monthly, "1Y" for yearly) ManagementAccountListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/ManagementAccountListItem' last_key: type: string nullable: true page_size: type: integer UpdateTrialRequest: type: object required: - trial_days properties: plan_ids: type: array description: IDs of the billing plans to use for the trial (must share the same billing cycle). Required when creating a new trial. items: type: string minItems: 1 trial_days: type: integer description: Number of trial days (for new trial) or days to extend by (for existing trial) minimum: 1 UpdateTrialResponse: type: object properties: data: type: object properties: action: $ref: '#/components/schemas/UpdateTrialAction' success: type: boolean transaction_id: type: string subscription_id: type: string new_trial_end: type: integer message: type: string OneTimeChargeItem: type: object required: - plan_id - description - price properties: plan_id: type: string description: The billing plan ID to associate with this charge item description: type: string description: Payment description for this charge item maxLength: 50 price: type: string description: Price amount in USD (e.g. "29.99") quantity: type: integer description: Number of units for this charge item minimum: 1 default: 1 PaymentTerms: type: object description: Payment terms for invoice billing (Paddle billing_details.payment_terms) properties: interval: type: string enum: - day - week - month - year default: day description: Time interval for payment terms frequency: type: integer minimum: 1 default: 30 description: Number of intervals (e.g. 30 days, 2 weeks) OneTimeChargeRequest: type: object required: - items properties: items: type: array description: One or more charge items, each representing a line item in the invoice items: $ref: '#/components/schemas/OneTimeChargeItem' minItems: 1 collection_mode: type: string enum: - subscription - manual default: subscription description: '''subscription'' charges on active Paddle subscription, ''manual'' creates a standalone invoice' payment_terms: $ref: '#/components/schemas/PaymentTerms' purchase_order_number: type: string description: Purchase order number for invoice (manual) billing. OneTimeChargeResponse: type: object properties: data: type: object properties: success: type: boolean subscription_id: type: string transaction_id: type: string message: type: string ChargePaddleCustomerRequest: type: object required: - paddle_customer_id - items properties: paddle_customer_id: type: string description: Paddle customer ID (e.g. "ctm_...") items: type: array description: One or more charge items items: $ref: '#/components/schemas/OneTimeChargeItem' minItems: 1 payment_terms: $ref: '#/components/schemas/PaymentTerms' ChargePaddleCustomerResponse: type: object properties: data: type: object properties: success: type: boolean transaction_id: type: string message: type: string AccountCustomizationLimitEntry: type: object description: A single limit override entry with a developer-friendly name matching the limitsAndCapabilities response. required: - value properties: value: type: integer description: The limit value (replaces or adds to plan limit depending on section) expiration: type: integer description: Optional expiration as unix timestamp. After this time, this override is ignored. nullable: true unit_overusage: type: number description: Optional overusage unit cost nullable: true unit_count: type: number description: Optional unit count nullable: true AccountCustomizationCapability: type: object description: A capability/feature override entry required: - name - id properties: name: type: string description: 'The feature nice name, matching `availableFeaturesNiceNames` in account details (e.g. "advanced_segmentation", "api", "fullstack", "bayesian_stats"). ' id: type: integer description: The numeric feature ID expiration: type: integer description: Optional expiration as unix timestamp. After this time, this capability override is ignored. nullable: true AccountCustomizations: type: object description: 'Per-account customizations that override or extend billing plan limits and capabilities. Uses the same developer-friendly names as `limitsAndCapabilities` in account details: limit keys are camelCase (e.g. "testedUsers", "goals", "projects", "experiments"), and capabilities use nice names (e.g. "advanced_segmentation", "api"). ' properties: expiration: type: integer description: Global expiration as unix timestamp. If set, ALL customizations below are ignored after this time. nullable: true limits: type: object description: 'Limit overrides keyed by camelCase limit name (e.g. "testedUsers", "goals", "projects", "experiments", "customDomains"). These **replace** the aggregated plan limits entirely. ' additionalProperties: $ref: '#/components/schemas/AccountCustomizationLimitEntry' capabilities: type: array description: 'Capability/feature overrides. Each entry grants the account a capability that its plan may not include, with an optional per-capability expiration. ' items: $ref: '#/components/schemas/AccountCustomizationCapability' AccountContract: type: object description: Account contract date range. Dates are stored as unix timestamps. properties: start_date: type: integer nullable: true description: Contract start as unix timestamp (midnight UTC of the start date) end_date: type: integer nullable: true description: Contract end as unix timestamp (23:59:59 UTC of the end date) GetAccountDataResponse: type: object properties: data: type: object properties: customizations: $ref: '#/components/schemas/AccountCustomizations' contract: $ref: '#/components/schemas/AccountContract' limitsAndCapabilities: description: The account's aggregated limits and capabilities from all plans (with extra_features already applied). allOf: - readOnly: true - $ref: '#/components/schemas/BillingPlanLimitsAndCapabilities' UpdateAccountDataRequest: type: object description: "Unitary update \u2014 send only the fields you want to change.\nOmitted top-level fields are left unchanged.\n" properties: customizations: $ref: '#/components/schemas/AccountCustomizations' contract: $ref: '#/components/schemas/AccountContract' UpdateAccountDataResponse: type: object properties: data: type: object properties: customizations: $ref: '#/components/schemas/AccountCustomizations' contract: $ref: '#/components/schemas/AccountContract' CancelPaddleSubscriptionResponse: type: object properties: data: type: object properties: success: type: boolean subscription_id: type: string description: The Paddle subscription ID that was canceled message: type: string PaddleSubscriptionItem: type: object properties: price: type: object properties: id: type: string description: Paddle price ID name: type: string description: Price display name (e.g. "Per Month") description: type: string unit_price: type: object properties: amount: type: string description: Price amount in cents currency_code: type: string billing_cycle: type: object properties: interval: type: string enum: - day - week - month - year frequency: type: integer custom_data: type: object properties: plan_id: type: string quantity: type: integer status: type: string GetPaddleSubscriptionResponse: type: object properties: data: type: object properties: id: type: string description: Paddle subscription ID status: type: string description: Subscription status (active, trialing, past_due, canceled, paused) collection_mode: type: string enum: - automatic - manual current_billing_period: type: object nullable: true properties: starts_at: type: string format: date-time ends_at: type: string format: date-time purchase_order_number: type: string nullable: true description: Purchase order number from billing_details (if set) payment_terms: nullable: true description: Payment terms from billing_details (if set) allOf: - $ref: '#/components/schemas/PaymentTerms' items: type: array items: $ref: '#/components/schemas/PaddleSubscriptionItem' AccountsListResponseData: type: object description: Response containing a list of accounts accessible to the authenticated user. For paginated results, refer to specific endpoint documentation if applicable. properties: data: $ref: '#/components/schemas/AccountsList' AccountsList: type: array description: List of accounts items: $ref: '#/components/schemas/Account' AccountTypes: type: string description: 'Defines the type of the account: - `main`: A primary account that can have sub-accounts and manages its own billing. - `sub`: A secondary account existing under a `main` account, often used by agencies to manage client activities. Sub-accounts share quotas from the parent. ' enum: - main - sub SubAccountBase: type: object description: Base properties common to both main and sub-accounts. properties: id: description: The unique numerical identifier for the account. type: integer readOnly: true accountType: $ref: '#/components/schemas/AccountTypes' name: type: string description: The user-defined, friendly name for the account (e.g., "Client X Marketing", "My Company Inc."). maxLength: 200 accessRole: allOf: - readOnly: true - $ref: '#/components/schemas/AccessRoleNames' access_all_projects: type: boolean description: Indicates if the authenticated user has access to all projects within this account by default, or if access is granted on a per-project basis. readOnly: true MainAccountBase: allOf: - $ref: '#/components/schemas/SubAccountBase' - type: object description: Base account object properties: accountType: type: string enum: - main id: readOnly: true billing: type: object description: Billing related data and settings properties: id: type: string nullable: true readOnly: true description: id of the account into the billing system details: description: Account billing details type: object properties: isPausedByQuota: type: boolean readOnly: true description: 'Flag indicating whether this account is marked as paused by the system due to usage quota being reached and settings.overQuota_charges == false ' nextBillingCycleStart: type: integer readOnly: true description: Unix timestamp for the time when current billing cycle ends and next one starts, in UTC time currentBillingCycleStart: type: integer readOnly: true description: Unix timestamp for the time when current billing cycle started, in UTC time pending_cancellation: type: boolean readOnly: true default: false description: Flag indicating whether subscription is in cancellation state cancellation_request_timestamp: type: integer readOnly: true nullable: true description: Unix timestamp indicating date and time when cancellation was requested, in UTC time billingType: allOf: - $ref: '#/components/schemas/PlanStatus' - readOnly: true description: Describes current billing's type, whether this is a free trial, paid, canceled etc - paid - Active paid account - trial - Free trial account - trialExpired - Free trial account which expired - canceled - account canceled, data will be deleted 30 days after current billing end time - paused - account paused on user request until "pausedUntil" contract: type: object nullable: true readOnly: true description: Services contract related properties properties: start_time: type: integer description: Unix timestamp for the contract start time end_time: type: integer description: Unix timestamp for the contract start time settings: description: Various settings that the user can tweak to control billing type: object properties: overQuota_charges: description: Flag indicating whether Convert can allow account's usage to go over the included quota and charge extra type: boolean subscription_paused_until: description: Unix timestamp representing the time until which the subscription is paused, in UTC time, null if subscription not in paused mode nullable: true type: number limitsAndCapabilities: allOf: - readOnly: true - $ref: '#/components/schemas/BillingPlanLimitsAndCapabilities' MainAccount: description: Represents a main Convert account, which can own projects and sub-accounts, and manages its own billing. allOf: - $ref: '#/components/schemas/MainAccountBase' - $ref: '#/components/schemas/AccountProducts' SubAccount: description: Represents a sub-account, typically managed under a main (often agency) account. It has its own projects but its usage quotas are often derived from the parent account. allOf: - $ref: '#/components/schemas/SubAccountBase' - type: object properties: accountType: type: string enum: - sub parentAccountId: description: Parent account ID, if this is a sub-account. nullable: true type: integer readOnly: true id: readOnly: true limitsAndCapabilities: allOf: - readOnly: true - $ref: '#/components/schemas/SubAccountBillingPlanLimitsAndCapabilities' - $ref: '#/components/schemas/SubAccountProducts' Account: oneOf: - $ref: '#/components/schemas/MainAccount' - $ref: '#/components/schemas/SubAccount' discriminator: propertyName: accountType mapping: main: '#/components/schemas/MainAccount' sub: '#/components/schemas/SubAccount' Products: description: 'The Convert product line this billing plan pertains to. - `experiences`: Relates to A/B testing, MVT, Split URL, and personalization features. - `deploy`: Relates to the "Deploy" feature for rolling out changes to specific audiences without A/B testing reports. Knowledge Base: "Deployments have the potential to contain small segments...and this could be interpreted by Privacy Authorities in Europe as identification of data subjects." - `addons`: Relates to add-on products that extend the core platform capabilities. ' type: string enum: - experiences - deploy - addons BillingPlanLimitsAndCapabilitiesBase: type: object properties: usage_limit_by: allOf: - readOnly: true - $ref: '#/components/schemas/BillingPlanBillByEnum' availableFeaturesNiceNames: description: A list of human-readable names for features enabled by this plan (e.g., 'advanced_segmentation', 'api_access', 'multivariate_testing'). readOnly: true type: array items: type: string enum: - advanced_segmentation - api - basic_segmentation - change_history - chat support - custom_domains - cookie_targeting - csv_export - experience_raw_export - dmp_profiling - email_support - geo_targeting - kissmetrics_integration - live_data - multipage_experience - multivariate_testing - phone_support - scroll_goal - single_sign_on - triggered_goal_targeting - weather_targeting - experience_report_predictions - collaborators - forum_access - fullstack - bayesian_stats - ve_ai_text - create_subaccounts - sequential_testing - other_goals_test_progress - export_project - import_project - experience_collaborators - bulk_actions - dynamic_web_triggers - advanced_tracking_script_release - remove_report_data - mab - composed_audience - visitor_insights - visitor_data - ui_widgets - ve_version_history BillingPlanLimitsAndCapabilities: allOf: - $ref: '#/components/schemas/BillingPlanLimitsAndCapabilitiesBase' - type: object properties: usageLimits: type: object properties: visitorData: type: object description: Visitor Data related usage limits properties: visitorProfiles: allOf: - $ref: '#/components/schemas/BillingUsageLimit' description: Maximum number of visitor profiles that can be created per project. visitorProfilesFields: allOf: - $ref: '#/components/schemas/BillingUsageLimit' description: Maximum number of visitor data placeholders that can be created per project. activePersonalisedExperiences: allOf: - $ref: '#/components/schemas/BillingUsageLimit' description: Maximum number of active experiences that use visitor data placeholders per project. domains: allOf: - $ref: '#/components/schemas/BillingUsageLimit' description: This limits the number of domains that can be created **inside all the projects that belong to the account** goals: allOf: - $ref: '#/components/schemas/BillingUsageLimit' description: This limits the number of active goals that can be created **inside one single project** deploys: allOf: - $ref: '#/components/schemas/BillingUsageLimit' description: This limits the number of active deploys that can be created **inside all the projects that belong to the account** projects: allOf: - $ref: '#/components/schemas/BillingUsageLimit' description: This limits the number of projects that can be created **inside the account** environments: allOf: - $ref: '#/components/schemas/BillingUsageLimit' description: Maximum number of environments allowed to be created under one **individual project.** segments: allOf: - $ref: '#/components/schemas/BillingUsageLimit' description: This limits the number of segments that can be created **inside one single project** experiments: allOf: - $ref: '#/components/schemas/BillingUsageLimit' description: The number of active experiments inside the project. customDomains: allOf: - $ref: '#/components/schemas/BillingUsageLimit' description: The number of custom domains allowed for the account. pageViews: allOf: - $ref: '#/components/schemas/BillingUsageLimit' description: This limits the number of pageViews that can be tracked **inside the account** deprecated: true testedVisitors: allOf: - $ref: '#/components/schemas/BillingUsageLimit' description: This limits the number of tested visitors that can be tracked **inside the account** testedUsers: allOf: - $ref: '#/components/schemas/BillingUsageLimit' description: This limits the number of tested users that can be tracked **inside the account** SubAccountBillingPlanLimitsAndCapabilities: allOf: - $ref: '#/components/schemas/BillingPlanLimitsAndCapabilitiesBase' - type: object properties: usageLimits: type: object required: - domains - goals - deploys - projects - segments - testedUsers properties: domains: required: - limitValue allOf: - $ref: '#/components/schemas/BillingUsageLimitBase' description: This limits the number of domains that can be created **inside all the projects that belong to the account** goals: required: - limitValue allOf: - $ref: '#/components/schemas/BillingUsageLimitBase' description: This limits the number of active goals that can be created **inside one single project** deploys: required: - limitValue allOf: - $ref: '#/components/schemas/BillingUsageLimitBase' description: This limits the number of active deploys that can be created **inside all the projects that belong to the account** projects: required: - limitValue allOf: - $ref: '#/components/schemas/BillingUsageLimitBase' description: This limits the number of projects that can be created **inside the account** segments: required: - limitValue allOf: - $ref: '#/components/schemas/BillingUsageLimitBase' description: This limits the number of segments that can be created **inside one single project** pageViews: allOf: - $ref: '#/components/schemas/BillingUsageLimitBase' description: This limits the number of pageViews that can be tracked **inside the account** deprecated: true testedVisitors: required: - limitValue allOf: - $ref: '#/components/schemas/BillingUsageLimitBase' description: This limits the number of tested visitors that can be tracked **inside the account** testedUsers: required: - limitValue allOf: - $ref: '#/components/schemas/BillingUsageLimitBase' description: This limits the number of tested users that can be tracked **inside the account** BillingPlanBillByEnum: type: string description: 'Indicates the primary metric used for billing and quota calculation for the plan: - `testedUsers`: Billing is based on the number of unique identified users participating in experiments (common in Full Stack). - `testedVisitors`: Billing is based on the number of unique anonymous or identified visitors participating in experiments (common for web A/B testing). ' enum: - testedUsers - testedVisitors BillingPlanDataBase: allOf: - type: object properties: product: $ref: '#/components/schemas/Products' availableFeaturesIds: type: array description: List of feature IDs the current account has access to items: type: integer minimum: 1 deprecated: true readOnly: true BillingPlanData: allOf: - type: object properties: id: type: integer name: description: Plan's name type: string price: description: Subscription price type: number billingCycleDuration: type: string description: billing cycle duration in the form of XM or XY where X is a number. Eg. 1M means billing cycle's duration is one month. 2Y would mean billing cycle duration is two years contract: type: string description: The type of the contract needed for this plan. enum: - pay_as_you_go - year - $ref: '#/components/schemas/BillingPlanDataBase' - $ref: '#/components/schemas/BillingPlanLimitsAndCapabilities' SubAccountBillingPlanData: allOf: - $ref: '#/components/schemas/BillingPlanDataBase' - $ref: '#/components/schemas/SubAccountBillingPlanLimitsAndCapabilities' BillingUsageLimitBase: type: object properties: limitValue: oneOf: - type: integer description: 'What is the limits value, "how many" could be used at max Describes how system deal with charging upon reaching the usage quota limits Eg. limitValue = 500000, overLimitCostPerUnit=199, unitSize=100000 translates into - - Max usage that is included in the current plan is 500000 - after reaching the 500000 included, every additional 100000 will be charged with 199 ' - type: string enum: - unlimited BillingUsageLimit: allOf: - $ref: '#/components/schemas/BillingUsageLimitBase' - type: object properties: overLimitCostPerUnit: type: integer readOnly: true description: If this is filled, if user allows overQuota charges, system will charge them automatically for every etra unit used unitSize: type: integer readOnly: true description: How many usage items are gonna be included in one billable unit. BillingPlansListResponseData: type: object description: Contains a list of all active billing plans that an account can subscribe to. properties: data: type: array items: $ref: '#/components/schemas/BillingPlanData' SubAccountDetailsBase: allOf: - $ref: '#/components/schemas/SubAccountBase' - type: object description: Account details data properties: settings: description: Various Account level settings that can be controlled by the user type: object properties: blocked_ips: description: List of IPs and IP ranges that are blocked from reporting type: object properties: range: description: List of IP ranges that are blocked from reporting type: array items: type: object minProperties: 1 properties: start: description: Start of the blocked IP range type: string format: ip-address end: description: End of the blocked IP range type: string format: ip-address name: type: string nullable: true maxLength: 64 required: - start - end single: description: List of single IPs blocked from the reporting type: array items: type: object minProperties: 1 properties: value: type: string format: ip-address name: type: string nullable: true maxLength: 64 required: - value setup_plan: type: object description: Setup plan settings. Only avaialable if current plan is Trial nullable: true additionalProperties: false properties: settings: type: object nullable: true description: Setup plan details additionalProperties: false properties: initiator: type: object description: Details of the user who initiated setup plan nullable: true additionalProperties: false required: - user_id properties: user_id: type: string description: User's unique ID in Convert's system consumer: type: object description: Details of the user who setup plan additionalProperties: false nullable: true required: - user_id properties: user_id: type: string description: User's unique ID in Convert's system timestamp: type: integer nullable: true description: The timestamp of the moment when setup plan has been requested, in UTC time remind_in: type: integer nullable: true description: The timestamp of the moment when the onboard popup will be displayed again, in UTC time tracking_script: type: object description: Tracking script version related data nullable: true additionalProperties: false properties: available_versions: $ref: '#/components/schemas/TrackingScriptAvailableVersions' release: $ref: '#/components/schemas/TrackingScriptRelease' MainAccountDetailsBase: allOf: - $ref: '#/components/schemas/SubAccountDetailsBase' - $ref: '#/components/schemas/MainAccountBase' - type: object description: Account details data properties: billing: description: Billing related data and settings type: object properties: id: type: string nullable: true readOnly: true description: id of the account into the billing system details: description: Account billing details type: object properties: company: description: Business name type: string nullable: true maxLength: 200 tax_code: description: Unique code that identifies business for tax reasons type: string nullable: true maxLength: 200 phone: description: Contact phone number type: string nullable: true maxLength: 15 address_street: description: Address street name type: string nullable: true maxLength: 200 address_city: description: Address city name type: string nullable: true maxLength: 50 address_zip: description: Address zip code type: string nullable: true maxLength: 15 address_state: description: Address state type: string nullable: true maxLength: 100 address_country: description: Address country type: string nullable: true maxLength: 50 emails: description: 'List of email addresses that will get billing related notifications(eg: invoices) ' type: array items: type: string maxLength: 100 settings: description: Various settings that the user can tweak to control billing type: object properties: overQuota_charges: description: Flag indicating whether Convert can allow account's usage to go over the included quota and charge extra type: boolean subscription_paused_until: description: Unix timestamp representing the time until which the subscription is paused, in UTC time, null if subscription not in paused mode nullable: true type: number payment: allOf: - $ref: '#/components/schemas/PaymentMethod' - nullable: true settings: type: object properties: single_sign_on_status: type: string description: The status of Single Sign On for this account. enum: - disabled - pending-disable - pending-enable - enabled SubAccountProducts: type: object properties: billing: type: object properties: products: type: object description: Object detailing subscribed plans for each Convert product. properties: experiences: type: object description: Billing plan data for the 'Experiences' product (A/B testing, MVT, etc.). properties: plan: allOf: - $ref: '#/components/schemas/SubAccountBillingPlanData' nullable: true deploy: type: object description: Billing plan data for the 'Deploy' product. properties: plan: allOf: - $ref: '#/components/schemas/SubAccountBillingPlanData' nullable: true SubAccountProductsCreate: type: object properties: billing: type: object required: - products properties: products: type: object description: Specifies initial plan subscriptions for Convert products. required: - experiences properties: experiences: type: object description: Initial plan for the 'Experiences' product. required: - plan properties: plan: required: - product - usageLimits allOf: - $ref: '#/components/schemas/SubAccountBillingPlanData' AccountProducts: type: object properties: billing: type: object properties: products: type: object description: Object detailing subscribed plans for each Convert product. properties: experiences: type: object description: Billing plan data for the 'Experiences' product. properties: plan: allOf: - $ref: '#/components/schemas/BillingPlanData' nullable: true deploy: type: object description: Billing plan data for the 'Deploy' product. properties: plan: allOf: - $ref: '#/components/schemas/BillingPlanData' nullable: true addons: type: array description: List of subscribed add-on plans with their quantities. items: type: object properties: plan: allOf: - $ref: '#/components/schemas/BillingPlanData' nullable: true quantity: type: integer minimum: 1 description: Number of units subscribed for this add-on plan. AccountGeneralStats: type: object description: General usage statistics for the account, typically for the current billing period. This is an optional field in API responses, included via `include[]=stats`. readOnly: true nullable: true properties: active_projects_count: type: number description: The number of currently active projects within this account. active_domains_count: type: number description: The total number of unique domains associated with active projects in this account. active_deploys_count: type: number description: The number of currently active "Deploy" type experiences across all projects in this account. usage: type: object description: Current usage metrics for the account against its plan quotas. properties: used_tested_users: type: integer description: The number of unique identified users who have participated in Full Stack experiments or specific web tests within the current billing cycle. used_tested_visitors: type: integer description: The number of unique visitors (anonymous or identified) who have participated in any web experiment or deploy within the current billing cycle. This is a primary quota metric. experiences_count: type: integer description: 'The total number of experiences (all statuses: draft, active, paused, completed, archived) within this account. ' active_experiences_count: type: integer description: The number of experiences currently in 'active' status across all projects in this account. SubAccountStats: type: object properties: stats: $ref: '#/components/schemas/AccountGeneralStats' MainAccountStats: type: object properties: stats: allOf: - $ref: '#/components/schemas/AccountGeneralStats' - type: object properties: subAccounts_usage: type: object description: Sub-accounts Usage metrics for the current billing period. Omitted when account doesn't have Sub Accounts properties: used_tested_users: type: integer description: The number of tested users counted for all the sub-accounts in the current billing interval. This counter is used towards account's usage quota for certain billing plans. used_tested_visitors: type: integer description: The number of tested visitors counted for all the sub-accounts in the current billing interval. This counter is used towards account's usage quota for certain billing plans. StartPaymentSetupRequestData: type: object nullable: true description: 'Options that could be used for initiating payment setup. Currently only the billing plans can be passed. ' properties: billingPlans: type: array items: type: integer description: "The IDs of the billing plans to be used for the payment setup, only if no subscription is already\ \ active. \nFor an active subscription, to only change plans, use the `updateAccountDetails()` endpoint.\nIf\ \ missing, the ones on the account will be used. If passed, all the plans need to have the same billing period.\n\ **Note:** Passing different plans then the ones on the account will result in the subscription to be changed\ \ in case the account already has a subscription(trial or paid).\n" StartPaymentSetupStripeResponseData: type: object description: Stripe payment setup response. properties: provider: type: string enum: - stripe description: Billing provider identifier. Always `stripe` for this schema. client_secret: type: string description: Stripe SetupIntent client secret used by Stripe.js to complete payment setup. required: - provider - client_secret StartPaymentSetupPaddleResponseData: type: object description: Paddle payment setup response. properties: provider: type: string enum: - paddle description: Billing provider identifier. Always `paddle` for this schema. transaction_id: type: string description: Paddle transaction ID to be used with Paddle Checkout. required: - provider - transaction_id StartPaymentSetupResponseData: oneOf: - $ref: '#/components/schemas/StartPaymentSetupStripeResponseData' - $ref: '#/components/schemas/StartPaymentSetupPaddleResponseData' discriminator: propertyName: provider mapping: stripe: '#/components/schemas/StartPaymentSetupStripeResponseData' paddle: '#/components/schemas/StartPaymentSetupPaddleResponseData' PlanSetupUsersResponseData: type: object description: A list of users associated with an account, intended for notification during billing plan setup or changes. properties: data: description: Array of user details. type: array items: type: object properties: user_id: type: string description: The user's unique identifier within the Convert system. email: type: string description: The user's email address. name: type: string description: The user's full name. AccountDetailsResponseData: type: object description: Contains the full details of a requested account, which could be a main account or a sub-account. properties: data: $ref: '#/components/schemas/AccountDetails' Invoice: type: object description: Invoice data for the given account. properties: invoice_url: type: string nullable: true format: uri description: Authenticated Paddle customer portal URL for viewing invoices and payment history. BillingPortal: type: object description: Authenticated Paddle billing portal URL for the given account. properties: url: type: string nullable: true format: uri description: Authenticated Paddle billing portal URL for to check subscriptions, view or download invoices. BillingPortalResponseData: type: object description: Wrapper object for the billing portal response. properties: data: $ref: '#/components/schemas/BillingPortal' MainAccountDetails: allOf: - $ref: '#/components/schemas/MainAccountDetailsBase' - $ref: '#/components/schemas/AccountProducts' - $ref: '#/components/schemas/MainAccountStats' SubAccountDetails: allOf: - $ref: '#/components/schemas/SubAccountDetailsBase' - $ref: '#/components/schemas/SubAccountProducts' - $ref: '#/components/schemas/SubAccountStats' - type: object properties: limitsAndCapabilities: allOf: - readOnly: true - $ref: '#/components/schemas/SubAccountBillingPlanLimitsAndCapabilities' AccountDetails: oneOf: - $ref: '#/components/schemas/MainAccountDetails' - $ref: '#/components/schemas/SubAccountDetails' discriminator: propertyName: accountType mapping: main: '#/components/schemas/MainAccountDetails' sub: '#/components/schemas/SubAccountDetails' MainAccountDetailsUpdate: allOf: - $ref: '#/components/schemas/MainAccountDetailsBase' - type: object properties: billing: type: object properties: payment: $ref: '#/components/schemas/PaymentMethod' products: type: object description: 'Object containing products that would get the plan updated inside the subscription. Possible products are **experiences**, **deploy**, and **addons**. An account can have a subscription to maximum one plan of each product. ' properties: experiences: $ref: '#/components/schemas/PlanUpdateBody' deploy: $ref: '#/components/schemas/PlanUpdateBody' addons: type: array description: List of add-on plan subscriptions to update with quantities. items: $ref: '#/components/schemas/AddonPlanUpdateBody' cancellation_reason: type: string maxLength: 200 description: 'Use this field to provide a cancellation reason. ' SubAccountDetailsUpdate: allOf: - type: object properties: accountType: type: string enum: - sub - $ref: '#/components/schemas/SubAccountDetailsBase' AccountDetailsUpdate: oneOf: - $ref: '#/components/schemas/MainAccountDetailsUpdate' - $ref: '#/components/schemas/SubAccountDetailsUpdate' discriminator: propertyName: accountType mapping: main: '#/components/schemas/MainAccountDetailsUpdate' sub: '#/components/schemas/SubAccountDetailsUpdate' SubAccountCreate: allOf: - $ref: '#/components/schemas/SubAccountDetailsBase' - $ref: '#/components/schemas/SubAccountProductsCreate' - type: object properties: accountType: readOnly: true userName: type: string description: Name of the user that would own this account. userEmail: type: string description: 'Email of the user that would own this account. If the an user exists with that email, the respective user would be used. Otherwise, a new user would get created. ' sendUserEmail: type: boolean default: false description: 'Flag indicating whether an email to be sent or not to the user, notifying them that an account was created for them by main account. *An email with a complete sign-up link would be sent regardless if the user does not exist into the system and gets created.* ' customEmailText: type: string description: Custom text to be appended to the email that gets sent to the user if `sendUserEmail = true` maxLength: 1024 required: - name - billing - userName - userEmail PlanUpdateBody: type: object properties: plan_id: description: 'The ID of the new billing plan to subscribe to. If the account is in trial, the new plan activates after the trial. If already on a paid plan, this may result in pro-rata charges or credits. Providing `null` typically cancels the existing subscription for this product. ' type: number nullable: true AddonPlanUpdateBody: type: object properties: plan_id: description: 'The ID of the add-on billing plan to subscribe to. Providing `null` cancels the existing subscription for this add-on. ' type: number nullable: true quantity: description: Number of units to subscribe to for this add-on plan. type: integer minimum: 1 AccountExperiencesListRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/AccountExperiencesListFilteringOptions' - $ref: '#/components/schemas/PageNumber' - type: object properties: include: description: 'Specifies the list of fields to be included in the response, which otherwise would not be sent. Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' type: array items: $ref: '#/components/schemas/ExperienceIncludeFields' expand: description: 'Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields)' type: array items: $ref: '#/components/schemas/ExperienceExpandFields' AccountExperiencesListFilteringOptions: type: object allOf: - $ref: '#/components/schemas/ResultsPerPage' - $ref: '#/components/schemas/SortDirection' - type: object properties: projects: type: array nullable: true description: 'Project IDs list to be used to filter experiences ' items: type: integer sort_by: type: string nullable: true default: id description: 'A value used to sort experiences by specific field Defaults to **id** if not provided ' enum: - id - conversions - improvement - name - start_time - end_time - status - project_id - primary_goal search: type: string nullable: true description: A search string that would be used to search against Experience's name and description type: type: array nullable: true description: The type of the experiences to be returned; either of the below can be provided items: $ref: '#/components/schemas/ExperienceTypes' AccountExperiencesListPersistentOptions: allOf: - $ref: '#/components/schemas/AccountExperiencesListFilteringOptions' - type: object properties: columns: nullable: true type: array description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/AccountExperiencesListColumnNames' AccountExperiencesListColumnNames: type: string description: Available columns for the account-wide experiences list in the UI. enum: - name - id - project_id - improvement - conversions - primary_goal - start_time - end_time - status - key - running_days - traffic_allocation AccountLiveDataRequestData: allOf: - $ref: '#/components/schemas/AccountLiveDataFilteringOptions' AccountLiveDataFilteringOptions: allOf: - type: object properties: event_types: type: array nullable: true items: $ref: '#/components/schemas/LiveDataEventTypes' projects: type: array nullable: true description: List of projects id to get data by items: type: integer segments: nullable: true allOf: - $ref: '#/components/schemas/ReportingSegmentsFilters' - $ref: '#/components/schemas/LiveDataExpandParameter' AccountLiveDataPersistentOptions: allOf: - $ref: '#/components/schemas/AccountLiveDataFilteringOptions' - $ref: '#/components/schemas/LiveDataAutoRefreshSettings' - type: object properties: columns: type: array description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/AccountLiveDataColumnNames' AccountLiveDataColumnNames: type: string description: Available columns for the account-level live data feed in the UI. enum: - time - project_id - event - experience - variation - more_info AccountHistoryRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/PageNumber' - $ref: '#/components/schemas/AccountHistoryFilteringOptions' AccountHistoryFilteringOptions: allOf: - $ref: '#/components/schemas/SortDirection' - $ref: '#/components/schemas/ResultsPerPage' - type: object properties: methods: type: array nullable: true items: $ref: '#/components/schemas/ChangeHistoryMethods' projects: type: array nullable: true description: List of projects id to get data by items: type: integer objects: type: array nullable: true description: List of objects to get data by items: $ref: '#/components/schemas/ChangeHistoryObjectTypes' sort_by: type: string nullable: true default: timestamp description: "A value to sort history list by specific field(s)\n\n Defaults to **timestamp** if not provided\n" enum: - timestamp - project_id - event - object - $ref: '#/components/schemas/ChangeHistoryExpandParameter' AccountHistoryPersistentOptions: allOf: - $ref: '#/components/schemas/AccountHistoryFilteringOptions' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/AccountHistoryColumnNames' AccountHistoryColumnNames: type: string description: Available columns for the account change history log in the UI. enum: - timestamp - project_id - event - object - method - more_info AccountDetailsIncludeFields: type: string enum: - stats - settings.tracking_script.available_versions ChangeHistoryObjectTypes: type: string enum: - account - audience - feature - collaborator - domain - goal - hypothesis - experience - report - change - variation - project - tag RequestAccountAddonsData: type: object description: Specifies the add-on to request and optionally, collaborator details if it's for a specific user. required: - addon properties: addon: $ref: '#/components/schemas/AccountAddonsTypes' collaborator_email: type: string description: Email of the collaborator for whom the add-on is being requested (if applicable). maxLength: 100 collaborator_name: type: string description: Name of the collaborator for whom the add-on is being requested (if applicable). maxLength: 200 AccountAddonsTypes: type: string enum: - one_time_convert_launch - conversionXl_mini_course - convert_remote_1h - goodUi_annual_solo PaymentMethod: description: Payment method information for billing purposes (used for both GET and UPDATE operations) type: object nullable: true oneOf: - $ref: '#/components/schemas/PaymentMethodCard' - $ref: '#/components/schemas/PaymentMethodPaypal' - $ref: '#/components/schemas/PaymentMethodApplePay' - $ref: '#/components/schemas/PaymentMethodWireTransfer' - $ref: '#/components/schemas/PaymentMethodVoucher' - $ref: '#/components/schemas/PaymentMethodInvoice' discriminator: propertyName: method mapping: card: '#/components/schemas/PaymentMethodCard' paypal: '#/components/schemas/PaymentMethodPaypal' apple_pay: '#/components/schemas/PaymentMethodApplePay' wire_transfer: '#/components/schemas/PaymentMethodWireTransfer' voucher: '#/components/schemas/PaymentMethodVoucher' invoice: '#/components/schemas/PaymentMethodInvoice' PaymentMethodInvoice: type: object description: Invoice payment method data properties: method: type: string enum: - invoice description: Payment method type identifier data: type: object description: Invoice payment method data (empty for now) additionalProperties: false required: - method - data PaymentMethodCard: type: object description: Credit/debit card payment method data (used for both GET and UPDATE operations) properties: method: type: string enum: - card description: Payment method type identifier data: type: object description: Card payment method data properties: stripe_card_token: description: Stripe card token (required for Stripe provider when updating, not returned in GET responses) type: string maxLength: 200 writeOnly: true name_on_card: description: Name on the card type: string nullable: true maxLength: 100 time_added: description: Unix timestamp of the time when card was added into the system by the user, in UTC time type: number nullable: true last_digits: description: Last four digits of the card number (returned by backend, not required in updates) type: number readOnly: true required: - method - data PaymentMethodPaypal: type: object description: PayPal payment method data properties: method: type: string enum: - paypal description: Payment method type identifier data: type: object description: PayPal payment method data (empty for now) additionalProperties: false required: - method - data PaymentMethodApplePay: type: object description: Apple Pay payment method data properties: method: type: string enum: - apple_pay description: Payment method type identifier data: type: object description: Apple Pay payment method data (empty for now) additionalProperties: false required: - method - data PaymentMethodWireTransfer: type: object description: Wire transfer payment method data properties: method: type: string enum: - wire_transfer description: Payment method type identifier data: type: object description: Wire transfer payment method data (empty for now) additionalProperties: false required: - method - data PaymentMethodVoucher: type: object description: Voucher payment method data properties: method: type: string enum: - voucher description: Payment method type identifier data: type: object description: Voucher payment method data (empty for now) additionalProperties: false required: - method - data CheckPartnerData: type: object properties: email: type: string description: The email address that was checked. maxLength: 100 allowed: type: boolean description: True if the email is associated with a valid partner eligible for extended API access. alreadyGranted: type: boolean description: True if extended API access has already been granted to this partner. InternalAccountDetailsUpdate: type: object properties: billing: type: object description: Billing related data and settings properties: settings: type: object description: Billing settings properties: usageLimits: type: object description: Usage limits additionalProperties: false properties: testedUsers: type: object description: The number of tested users that can be created additionalProperties: false properties: limitValue: type: integer description: The number of tested users that can be created expiration: type: integer description: The expiration timestamp of the tested users limit. Default to billing cycle end time. required: - limitValue GenerateTextVariantsRequestDataBase: description: Base structure for requesting AI-generated text variations. Specifies the content to rewrite, the AI model framework and principle to use, number of variations, and optional contextual content. type: object properties: parameters: description: Parameters to customize the AI generation process. properties: variationsNumber: description: The desired number of unique text variations to be generated by the AI. type: number minimum: 1 maximum: 5 default: 1 content: description: The original text content (e.g., headline, call-to-action, product description) that you want the AI to rewrite or generate variations for. type: string openAI_Key: description: (Optional) Your OpenAI API key. Providing this may allow for using more advanced OpenAI models (e.g., GPT-4) or handling larger `context_content`, potentially leading to higher quality or more nuanced variations. If not provided, Convert's default AI capabilities will be used. type: string context_content: description: '(Optional) Additional text to provide context to the AI model, helping it understand the subject matter, tone, or specific constraints for the generated variations. For example, you could provide the product page content if generating a headline for that product. If no `openAI_Key` is provided, this content may be trimmed to the first 200 words. When principle_class=none is provided, this field can be used for custom prompt instructions. ' type: string previousResponses: description: '(Optional) A list of text strings representing previously generated AI variants for the same input `content`. Providing these helps the AI avoid generating duplicate or very similar suggestions, ensuring more diverse outputs if requesting variations iteratively. ' type: array items: type: string required: - content - parameters PrincipleClasses: type: string description: 'The psychological or marketing framework model to guide the AI in generating text variations. Each class has a set of associated principles. - `cialdini`: Based on Robert Cialdini''s principles of persuasion. - `fogg_behavior`: Based on BJ Fogg''s Behavior Model. - `aida`: Attention, Interest, Desire, Action marketing model. - `pas`: Problem, Agitate, Solution copywriting framework. - `fab`: Features, Advantages, Benefits sales framework. ' enum: - cialdini - fogg_behavior - aida - pas - fab - none CialdiniPrinciples: description: 'One of Robert Cialdini''s six (now seven) key principles of influence. Selecting a principle guides the AI to generate text that leverages that specific psychological trigger. - `reciprocity`: People tend to return a favor. - `commitment_and_consistency`: People will go to great lengths to appear consistent in their words and actions. - `social_proof`: People will do things that they see other people are doing. - `authority`: People tend to obey authority figures. - `unity`: Shared identities or experiences increase influence. (Cialdini''s 7th principle) - `scarcity`: Perceived scarcity will generate demand. - `sympathy` (or Liking): People are more easily persuaded by people they like. ' type: string enum: - reciprocity - commitment_and_consistency - social_proof - authority - unity - scarcity - sympathy FoggBehaviorPrinciples: description: 'One of the core components of BJ Fogg''s Behavior Model (B=MAP), which states that for a behavior to occur, Motivation, Ability, and a Prompt (or Trigger) must converge at the same moment. - `motivation`: The underlying drive (e.g., pleasure/pain, hope/fear, social acceptance/rejection). - `ability`: The ease with which the action can be performed (simplicity). - `triggers` (or Prompts): The cue that tells someone to perform the behavior. ' type: string enum: - motivation - ability - triggers AIDAPrinciples: description: 'A stage in the AIDA marketing model, representing a common sequence of events leading to a purchase or action. - `attention`: Grab the audience''s attention. - `interest`: Raise customer interest by focusing on and demonstrating advantages and benefits. - `desire`: Convince customers that they want and desire the product or service and that it will satisfy their needs. - `action`: Lead customers towards taking action and/or purchasing. ' type: string enum: - attention - interest - desire - action PASPrinciples: description: 'A component of the Problem-Agitate-Solution (PAS) copywriting framework, designed to persuade by highlighting a pain point and offering a solution. - `problem`: Identify and state the customer''s problem. - `agitation`: Amplify the problem, making it more acute and emotional. - `solution`: Present your product/service as the solution to this agitated problem. ' type: string enum: - problem - agitation - solution FABPrinciples: description: 'A component of the Features-Advantages-Benefits (FAB) sales technique, used to explain how a product can help a customer. - `features`: Describe the factual statements about the product or service (e.g., "This car has a hybrid engine"). - `advantages`: Explain what the features do and how they can be helpful (e.g., "The hybrid engine gives you better gas mileage"). - `benefits`: Show the customer how the advantages meet their explicit needs and desires (e.g., "You''ll save money on gas and reduce your carbon footprint"). ' type: string enum: - features - advantages - benefits GenerateTextVariantsRequestDataNone: allOf: - $ref: '#/components/schemas/GenerateTextVariantsRequestDataBase' - type: object properties: principle_class: description: Framework model from which principles used for text generation are selected enum: - none GenerateTextVariantsRequestDataCialdini: allOf: - $ref: '#/components/schemas/GenerateTextVariantsRequestDataBase' - type: object properties: principle_class: description: Framework model from which principles used for text generation are selected enum: - cialdini principle: $ref: '#/components/schemas/CialdiniPrinciples' GenerateTextVariantsRequestDataFogg: allOf: - $ref: '#/components/schemas/GenerateTextVariantsRequestDataBase' - type: object properties: principle_class: enum: - fogg_behavior principle: $ref: '#/components/schemas/FoggBehaviorPrinciples' GenerateTextVariantsRequestDataAIDA: allOf: - $ref: '#/components/schemas/GenerateTextVariantsRequestDataBase' - type: object properties: principle_class: enum: - aida principle: $ref: '#/components/schemas/AIDAPrinciples' GenerateTextVariantsRequestDataPAS: allOf: - $ref: '#/components/schemas/GenerateTextVariantsRequestDataBase' - type: object properties: principle_class: enum: - pas principle: $ref: '#/components/schemas/PASPrinciples' GenerateTextVariantsRequestDataFAB: allOf: - $ref: '#/components/schemas/GenerateTextVariantsRequestDataBase' - type: object properties: principle_class: enum: - fab principle: $ref: '#/components/schemas/FABPrinciples' GenerateTextVariantsRequestData: oneOf: - $ref: '#/components/schemas/GenerateTextVariantsRequestDataNone' - $ref: '#/components/schemas/GenerateTextVariantsRequestDataCialdini' - $ref: '#/components/schemas/GenerateTextVariantsRequestDataFogg' - $ref: '#/components/schemas/GenerateTextVariantsRequestDataAIDA' - $ref: '#/components/schemas/GenerateTextVariantsRequestDataPAS' - $ref: '#/components/schemas/GenerateTextVariantsRequestDataFAB' discriminator: propertyName: principle_class mapping: none: '#/components/schemas/GenerateTextVariantsRequestDataNone' cialdini: '#/components/schemas/GenerateTextVariantsRequestDataCialdini' fogg_behavior: '#/components/schemas/GenerateTextVariantsRequestDataFogg' aida: '#/components/schemas/GenerateTextVariantsRequestDataAIDA' pas: '#/components/schemas/GenerateTextVariantsRequestDataPAS' fab: '#/components/schemas/GenerateTextVariantsRequestDataFAB' GenerateTextVariantsResponseData: description: The response containing the AI-generated text variations. type: object properties: data: description: Wrapper for the response data. type: object properties: variants: description: A list of the generated text variations. Each item in the list is a string representing one AI-generated alternative to the input content. type: array items: $ref: '#/components/schemas/VariantResponseItem' VariantResponseItem: description: A single AI-generated text variant. type: object properties: content: description: The AI-generated text string. This is one alternative version of the original content provided in the request. type: string GenerateCodeVariantRequestData: type: object properties: content: description: The original code that you want the AI to improve. type: string stream: description: Whether to stream the response. type: boolean default: false required: - content GenerateCodeVariantResponseData: description: The response containing the AI-generated code variation. type: object properties: data: description: Wrapper for the response data. type: object properties: content: description: The AI-generated code string. Or partial response if streaming is enabled. type: string GenerateCodeVariantResponseStreamData: type: string description: 'Stream of the AI-generated code variation. In format: `data: {"content":"Hello"}` `data: {"content":"World"}` `data: [DONE]` ' ApiKeysListResponse: type: object description: Response containing a list of API keys defined for a specific account, used for server-to-server authentication. properties: data: $ref: '#/components/schemas/ApiKeysList' ApiKeysList: type: array description: A list of API key objects. items: $ref: '#/components/schemas/ApiKey' ApiKeyAuthTypes: type: string description: 'The authentication type for this API key: - requestSigning: Each request must be signed with the key and a hash sent in the header (most secure) - secretKey: A simpler authentication method using the secret key as a Bearer token in the Authorization header (good security) ' enum: - requestSigning - secretKey ApiKeyRole: allOf: - $ref: '#/components/schemas/AccessRoleNamesNoOwner' description: 'The role assigned to this API key, which determines its permissions. Must have equal or lower permissions than the creator''s role when creating. If not specified, inherits the creator''s role.For legacy keys, a default role of account_manager is returned. ' example: browse ApiKey: type: object description: Defines an API key used for authenticating server-side requests to the Convert API. properties: name: type: string description: A user-defined, friendly name for the API key to help identify its purpose or the application using it (e.g., "Reporting Dashboard Integration", "Nightly Data Sync Script"). maxLength: 100 auth_type: $ref: '#/components/schemas/ApiKeyAuthTypes' projects: description: 'An optional list of project IDs that this API key is authorized to access. If null or an empty list, the key typically grants access to all projects within the account it belongs to. This allows for granular control over API key permissions. ' nullable: true type: array items: type: number key_id: type: string description: The public identifier part of the API key pair (ApplicationID). This is sent in the `Convert-Application-ID` header. readOnly: true key_secret: description: 'The secret part of the API key pair (ApplicationSecretKey). This is used to sign API requests and is critical for authentication. **Important:** The full `key_secret` is only returned at the time of API key creation. For security reasons, subsequent retrievals of this API key will show this field masked (e.g., with asterisks or partially hidden). Store the secret securely upon creation. ' type: string readOnly: true role: $ref: '#/components/schemas/ApiKeyRole' CreateApiKeyRequestData: allOf: - $ref: '#/components/schemas/ApiKey' - type: object properties: auth_type: type: string default: requestSigning role: $ref: '#/components/schemas/ApiKeyRole' required: - name AudiencesListResponseData: type: object description: Response containing a list of audiences defined within a project, along with pagination details if applicable. properties: data: $ref: '#/components/schemas/AudiencesList' extra: $ref: '#/components/schemas/Extra' AudiencesList: type: array description: A list of audience objects. items: $ref: '#/components/schemas/Audience' AudienceBase: type: object properties: id: type: integer description: The unique numerical identifier for the audience. readOnly: true description: type: string description: An optional, more detailed explanation of the audience's purpose or criteria, aiding in identification and management. maxLength: 500 status: $ref: '#/components/schemas/AudienceStatuses' name: type: string description: A user-defined, friendly name for the audience (e.g., "New Visitors from USA", "Repeat Purchasers - Mobile"). This name appears in the Convert UI when selecting audiences for experiences. maxLength: 100 preset: type: boolean description: Indicates if this audience is a system-defined preset (e.g., "All Visitors", "Mobile Users"). Preset audiences cannot be modified directly but can be used as templates. readOnly: true selected_default: type: boolean description: If true, this audience will be automatically pre-selected when creating new experiences within the project. Useful for commonly targeted segments. stats: type: object readOnly: true description: Statistics related to the usage of this audience. properties: experiences_usage: description: 'The number of currently active experiences that are using this audience for targeting. This is an optional field, included if ''stats.experiences_usage'' is specified in the `include` parameter. ' type: number default: 0 AudiencesPresetsListResponseData: type: object description: Response containing a list of predefined audience templates (presets) available in the system. properties: data: $ref: '#/components/schemas/AudiencesPresetsList' AudiencesPresetsList: type: array description: A list of audience preset objects. items: $ref: '#/components/schemas/AudiencePreset' AudiencePreset: type: object properties: id: type: integer description: The unique identifier for the audience preset. readOnly: true description: type: string description: A brief explanation of the criteria this preset audience targets. name: type: string description: The display name of the preset audience (e.g., "All Visitors", "Desktop Users"). stats: type: object readOnly: true description: Statistics related to the usage of this preset. properties: experiences_usage: description: 'The number of active experiences currently using this preset audience. ' type: number default: 0 rules: nullable: true allOf: - $ref: '#/components/schemas/RuleObjectAudience' AudienceTypesNoUrl: description: 'Defines the behavior and persistence of an audience that does *not* use URL-based conditions in its rules. - `permanent`: Once a visitor matches the audience criteria, they are permanently considered part of this audience for future sessions and evaluations, even if their characteristics change later. The matching is checked only at the initial bucketing time. - `transient`: A visitor must match the audience criteria upon each evaluation (e.g., on every page load or when an experiment is rechecked) to be included. If conditions are no longer met, the visitor is no longer part of the audience for that specific evaluation. For Full Stack projects, only `transient` and `segmentation` (if applicable without URL rules) are valid. ' type: string enum: - permanent - transient 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 AudienceTypes: type: string enum: - segmentation - permanent - transient AudienceCreate: oneOf: - $ref: '#/components/schemas/AudienceWithoutUrlMatchingCreate' - $ref: '#/components/schemas/AudienceWithUrlMatchingCreate' discriminator: propertyName: type mapping: permanent: '#/components/schemas/AudienceWithoutUrlMatchingCreate' segmentation: '#/components/schemas/AudienceWithUrlMatchingCreate' transient: '#/components/schemas/AudienceWithoutUrlMatchingCreate' Audience: oneOf: - $ref: '#/components/schemas/AudienceWithoutUrlMatching' - $ref: '#/components/schemas/AudienceWithUrlMatching' discriminator: propertyName: type mapping: permanent: '#/components/schemas/AudienceWithoutUrlMatching' segmentation: '#/components/schemas/AudienceWithUrlMatching' transient: '#/components/schemas/AudienceWithoutUrlMatching' AudienceWithoutUrlMatching: allOf: - $ref: '#/components/schemas/AudienceBase' - type: object properties: type: $ref: '#/components/schemas/AudienceTypesNoUrl' rules: nullable: true allOf: - $ref: '#/components/schemas/RuleObjectNoUrl' AudienceWithoutUrlMatchingCreate: required: - name - rules - type allOf: - $ref: '#/components/schemas/AudienceWithoutUrlMatching' AudienceWithUrlMatching: allOf: - $ref: '#/components/schemas/AudienceBase' - type: object properties: type: $ref: '#/components/schemas/AudienceTypesWithUrl' rules: nullable: true allOf: - $ref: '#/components/schemas/RuleObjectAudience' AudienceWithUrlMatchingCreate: required: - name - rules - type allOf: - $ref: '#/components/schemas/AudienceWithUrlMatching' AudienceExpandable: anyOf: - type: integer description: Audience ID - $ref: '#/components/schemas/Audience' SimpleAudienceExpandable: anyOf: - type: integer description: Audience ID - $ref: '#/components/schemas/SimpleAudience' CreateAudienceRequestData: $ref: '#/components/schemas/AudienceCreate' UpdateAudienceRequestData: $ref: '#/components/schemas/Audience' AudienceIncludeFields: type: string enum: - rules - stats.experiences_usage SimpleAudience: type: object properties: id: description: The unique numerical identifier of the audience. type: integer name: description: The user-defined, friendly name of the audience. type: string SimpleAudienceSegment: type: object properties: id: description: The unique numerical identifier of the segment (audience). type: integer name: description: The user-defined, friendly name of the segment. type: string SimpleAudienceSegmentExpandable: oneOf: - type: integer description: Segment ID - $ref: '#/components/schemas/SimpleAudienceSegment' GetAudiencesListRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/AudiencesListFilteringOptions' - $ref: '#/components/schemas/PageNumber' - type: object properties: include: description: Specifies the list of fields to be included in the response, which otherwise would not be sent. type: array items: $ref: '#/components/schemas/AudienceIncludeFields' only: description: 'Only retrieve audiences with the given ids. ' type: array nullable: true items: type: integer maxItems: 100 except: description: 'Except audiences with the given ids. ' type: array items: type: integer maxItems: 100 AudiencesListFilteringOptions: allOf: - $ref: '#/components/schemas/ResultsPerPage' - $ref: '#/components/schemas/SortDirection' - type: object properties: status: type: array nullable: true description: List of audience statuses to be returned items: $ref: '#/components/schemas/AudienceStatuses' search: type: string maxLength: 200 nullable: true description: a search string that would be used to search against audience's name or description is_default: type: boolean nullable: true description: 'A flag to filter audiences by default status If set to true, only default audiences will be returned, if not set, all audiences will be returned ' sort_by: type: string nullable: true default: id description: 'A value to sort audiences by specific field Defaults to **id** if not provided ' enum: - id - type - name - usage - status - key type: allOf: - $ref: '#/components/schemas/AudienceTypes' nullable: true experiences: type: array nullable: true description: List of experiences to be returned items: type: integer maxItems: 100 usage: type: string nullable: true description: It indicates wherever retrieved audiences are used or not inside experiences enum: - used - not_used AudiencesListPersistentOptions: allOf: - $ref: '#/components/schemas/AudiencesListFilteringOptions' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/AudiencesListColumnNames' AudiencesListColumnNames: type: string description: Available columns for the audiences list in the UI. enum: - name - id - type - usage - status - key AudienceStatuses: type: string description: 'The status of an audience: - `active`: The audience is currently active and can be used for targeting experiences. - `archived`: The audience is no longer active and cannot be used for new experiences, but its definition and past usage data are preserved. Archived audiences can often be cloned. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences." ' enum: - active - archived BulkAudiencesIds: type: array description: A list of audience unique numerical identifiers to be affected by a bulk operation. items: type: integer minItems: 1 maxItems: 100 BulkUpdateAudienceRequestData: type: object description: Request body for bulk updating the status of multiple audiences. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkAudiencesIds' status: $ref: '#/components/schemas/AudienceStatuses' required: - id - status BulkDeleteAudienceRequestData: type: object description: Request body for bulk deleting multiple audiences. Contains a list of audience IDs to be permanently removed. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkAudiencesIds' required: - id ForgotPasswordRequestData: type: object properties: username: description: The username or email address associated with the account for which password reset is requested. type: string ResetPasswordConfirmRequestData: type: object required: - newPassword - confirmNewPassword - code properties: authSub: description: '(Deprecated or Internal) An internal user identifier, typically part of the password reset link sent via email. The `token` or `code` is usually the primary field. ' type: string code: description: 'The password reset confirmation code received by the user via email. This code verifies the reset request. ' type: string newPassword: description: 'The new password chosen by the user. Must meet system complexity requirements. Maximum length is 99 characters. ' type: string confirmNewPassword: description: 'Confirmation of the new password. Must exactly match the `newPassword` field. Maximum length is 99 characters. ' type: string token: description: '(Deprecated or Alternative) A password reset token, possibly sent as part of the reset link. The `code` field is often the primary verification. ' type: string AcceptInvitationRequestData: type: object properties: hash: description: The unique invitation token from the collaborator invitation email. type: string maxLength: 200 CheckPartnerRequestData: type: object properties: email: description: The email address of the potential partner to verify. type: string maxLength: 100 ChangeHistoryMethods: type: string enum: - api - app ChangeHistoryObjects: type: string enum: - audience - feature - domain - goal - hypothesis - experience - tag - location ChangeHistoryListResponseData: type: object properties: data: $ref: '#/components/schemas/ChangeHistoryList' extra: $ref: '#/components/schemas/Extra' ChangeHistoryList: type: array description: A list of change history records. items: $ref: '#/components/schemas/ChangeHistory' ChangeHistory: type: object description: Represents a single logged change event, providing an audit trail for actions performed on Convert entities. properties: event: type: string description: The type of action performed (e.g., 'create', 'update', 'delete', 'activate', 'pause'). info: type: object description: (Deprecated) Additional context about the change. Modern implementations use the `changes` object. deprecated: true properties: isAdminChange: type: boolean description: Whether the change was made by a Convert super-admin. text: type: string description: Legacy textual description of the change. changes: type: object description: 'Detailed record of what was modified. Contains `old` and `new` value snapshots for the changed fields. For a ''create'' event, `old` will be null. For a ''delete'' event, `new` will be null. This allows tracking specific attribute modifications. ' properties: old: type: object description: A snapshot of the relevant fields and their values *before* the change was applied. Null for creation events. nullable: true new: type: object description: A snapshot of the relevant fields and their values *after* the change was applied. Null for deletion events. nullable: true method: type: string description: 'How the change was initiated: ''api'' (programmatic) or ''app'' (via Convert UI). ' items: $ref: '#/components/schemas/ChangeHistoryMethods' object: type: string description: 'The type of Convert entity that was changed (e.g., ''experience'', ''goal'', ''audience''). ' object_id: type: string description: The unique identifier of the specific entity that was changed. parent_object_id: type: string nullable: true description: The unique identifier of the parent entity related to this change. For example, for a 'variation' or 'change', this will be the corresponding 'experience' id. user: type: string description: The name or email of the user (or API key name) that performed the action. timestamp: type: integer description: Unix timestamp (UTC) indicating when the change occurred. request_id: type: string nullable: true description: A unique identifier for the specific API request or UI action that resulted in this change, useful for tracing and debugging. project: nullable: true allOf: - $ref: '#/components/schemas/SimpleProjectExpandable' ChangeHistoryExpandFields: type: string enum: - project ChangeHistoryExpandParameter: type: object properties: expand: type: array nullable: true description: 'Specifies linked objects to expand in the response, e.g., ''project''. Refer to the [Expanding Fields](#tag/Expandable-Fields) section. ' items: $ref: '#/components/schemas/ChangeHistoryExpandFields' PlanStatus: type: string description: Account billing status enum: - paid - trial - trialExpired - canceled - paused PageNumber: type: object properties: page: type: integer minimum: 1 description: 'The page number for paginated results. For example, if `results_per_page` is 30, `page: 2` will retrieve items 31-60. Defaults to 1 if not specified. ' Pagination: type: object properties: current_page: description: The current page number being displayed from the paginated set. type: integer minimum: 1 items_count: description: The total number of items available across all pages for the current filter criteria. type: integer minimum: 0 items_per_page: description: The number of items included in the current page of results (matches `results_per_page` from the request). type: integer minimum: 0 pages_count: description: The total number of pages available for the current filter criteria and `results_per_page` setting. type: integer minimum: 0 ResultsPerPage: type: object properties: results_per_page: type: integer nullable: true minimum: 0 maximum: 50 default: 30 description: 'Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50. ' SortDirection: type: object properties: sort_direction: type: string nullable: true default: desc description: 'The direction for sorting the list results, based on the `sort_by` field. - `asc`: Ascending order (e.g., A-Z, 1-10, oldest to newest). - `desc`: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to `desc` (newest/highest first) if not specified. ' enum: - asc - desc OnlyCount: type: object properties: onlyCount: type: boolean description: 'If set to `true` in a list request, the response will only contain the total count of matching items (`extra.pagination.items_count`) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets. ' Extra: type: object properties: pagination: $ref: '#/components/schemas/Pagination' BaseRule: type: object required: - rule_type properties: rule_type: description: 'The specific attribute or condition to evaluate. Examples: ''url'', ''cookie'', ''browser_name'', ''js_condition'', ''page_tag_product_price''. The allowed `rule_type` values depend on whether the rule is for an Audience (which can use visitor and page content attributes if it''s a ''segmentation'' type) or a Location (typically URL or page tag based). ' type: string BaseRuleWithStringValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: The value used to match against 'rule_type' using 'matching' type: string BaseRuleWithJsCodeValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: 'The JS code that would be executed when rule is checked. The return value of this JS code is what is gonna be matched against **true**(or **false** if **matching.negated = true** is provided) ' type: string BaseRuleWithBooleanValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: The value used to match against 'rule_type' using 'matching' type: boolean BaseRuleWithNumericValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: The value used to match against 'rule_type' using 'matching' type: number BaseRuleWithCountryCodeValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: The 2 letter ISO country code used for matching type: string minLength: 2 maxLength: 2 BaseRuleWithLanguageCodeValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: The 2 letter ISO language code used for matching type: string minLength: 2 maxLength: 2 BaseRuleWithGoalTriggeredValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: ID of the goal used for matching type: number BaseRuleWithVisitorTypeValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: Type of the visitors type: string enum: - new - returning BaseRuleWithExperienceBucketedValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: ID of the experience used for matching type: number BaseRuleWithSegmentBucketedValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: ID of the segment used for matching type: number BaseRuleWithDayOfWeekValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: Day of week used for matching type: number minimum: 1 maximum: 7 BaseRuleWithHourOfDayValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: Hour of day used for matching type: number minimum: 0 maximum: 24 BaseRuleWithMinuteOfHourValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: Minute of hour used for matching type: number minimum: 1 maximum: 60 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 BaseRuleWithOsValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: Operating System name used for matching type: string enum: - android - iphone - ipod - ipad - windows - macos - linux BaseRuleWithWeatherConditionValue: allOf: - $ref: '#/components/schemas/BaseRule' - type: object properties: value: description: 'Weather Condition name used for matching. Full or partial condition. The weather provider used by Convert detects the following conditions: - Blizzard - Blowing snow - Cloudy - Fog - Freezing drizzle - Freezing fog - Heavy freezing drizzle - Heavy rain - Heavy rain at times - Light drizzle - Light freezing rain - Light rain - Mist - Moderate rain - Moderate rain at times - Overcast - Partly cloudy ' type: string WeatherConditions: description: Standardized weather condition strings used for targeting. type: string enum: - Blizzard - Blowing snow - Cloudy - Fog - Freezing drizzle - Freezing fog - Heavy freezing drizzle - Heavy rain - Heavy rain at times - Light drizzle - Light freezing rain - Light rain - Mist - Moderate rain - Moderate rain at times - Overcast - Partly cloudy - Patchy freezing drizzle possible - Patchy light drizzle - Patchy light rain - Patchy rain possible - Patchy sleet possible - Patchy snow possible - Sunny - Thundery outbreaks possible BaseMatch: type: object properties: negated: description: 'If `true`, the logical result of the match is inverted. For example, if `match_type` is ''contains'' and `value` is ''apple'', `negated: true` means the rule matches if the attribute *does not* contain ''apple''. ' type: boolean TextMatchRulesTypes: type: string enum: - url - url_with_query - query_string - campaign - keyword - medium - source_name - city - region - browser_version - user_agent - page_tag_page_type - page_tag_category_id - page_tag_category_name - page_tag_product_sku - page_tag_product_name - page_tag_customer_id - page_tag_custom_1 - page_tag_custom_2 - page_tag_custom_3 - page_tag_custom_4 - visitor_id NumericMatchRulesTypes: type: string enum: - avg_time_page - days_since_last_visit - pages_visited_count - visit_duration - visits_count - page_tag_product_price BoolMatchRulesTypes: type: string enum: - bucketed_into_experience - is_desktop - is_mobile - is_tablet GenericTextKeyValueMatchRulesTypes: type: string enum: - generic_text_key_value GenericNumericKeyValueMatchRulesTypes: type: string enum: - generic_numeric_key_value GenericBoolKeyValueMatchRulesTypes: type: string enum: - generic_bool_key_value VisitorDataExistsMatchRulesTypes: type: string enum: - visitor_data_exists JsConditionMatchRulesTypes: type: string enum: - js_condition KeyValueMatchRulesTypes: allOf: - $ref: '#/components/schemas/GenericTextKeyValueMatchRulesTypes' - $ref: '#/components/schemas/GenericNumericKeyValueMatchRulesTypes' - $ref: '#/components/schemas/GenericBoolKeyValueMatchRulesTypes' CookieMatchRulesTypes: type: string enum: - cookie CountryMatchRulesTypes: type: string enum: - country VisitorTypeMatchRulesTypes: type: string enum: - visitor_type LanguageMatchRulesTypes: type: string enum: - language GoalTriggeredMatchRulesTypes: type: string enum: - goal_triggered SegmentBucketedMatchRulesTypes: type: string enum: - bucketed_into_segment DayOfWeekMatchRulesTypes: type: string enum: - local_time_day_of_week - project_time_day_of_week HourOfDayMatchRulesTypes: type: string enum: - local_time_hour_of_day - project_time_hour_of_day MinuteOfHourMatchRulesTypes: type: string enum: - local_time_minute_of_hour - project_time_minute_of_hour BrowserNameMatchRulesTypes: type: string enum: - browser_name OsMatchRulesTypes: type: string enum: - os WeatherConditionMatchRulesTypes: type: string enum: - weather_condition RulesTypes: allOf: - $ref: '#/components/schemas/TextMatchRulesTypes' - $ref: '#/components/schemas/NumericMatchRulesTypes' - $ref: '#/components/schemas/BoolMatchRulesTypes' - $ref: '#/components/schemas/KeyValueMatchRulesTypes' - $ref: '#/components/schemas/VisitorDataExistsMatchRulesTypes' - $ref: '#/components/schemas/CookieMatchRulesTypes' - $ref: '#/components/schemas/CountryMatchRulesTypes' - $ref: '#/components/schemas/VisitorTypeMatchRulesTypes' - $ref: '#/components/schemas/LanguageMatchRulesTypes' - $ref: '#/components/schemas/GoalTriggeredMatchRulesTypes' - $ref: '#/components/schemas/SegmentBucketedMatchRulesTypes' - $ref: '#/components/schemas/DayOfWeekMatchRulesTypes' - $ref: '#/components/schemas/HourOfDayMatchRulesTypes' - $ref: '#/components/schemas/MinuteOfHourMatchRulesTypes' - $ref: '#/components/schemas/BrowserNameMatchRulesTypes' - $ref: '#/components/schemas/OsMatchRulesTypes' - $ref: '#/components/schemas/WeatherConditionMatchRulesTypes' GenericTextMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithStringValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/TextMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/TextMatchingOptions' GenericNumericMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithNumericValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/NumericMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/NumericMatchingOptions' 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' GenericSetMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithStringValue' - type: object required: - rule_type properties: rule_type: type: string matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/SetMatchingOptions' GenericKey: type: object properties: key: description: The name of the key whose value will be retrieved and compared against the rule's `value`. type: string 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' GenericNumericKeyValueMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithNumericValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/GenericNumericKeyValueMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/NumericMatchingOptions' - $ref: '#/components/schemas/GenericKey' GenericBoolKeyValueMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithBooleanValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/GenericBoolKeyValueMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/ChoiceMatchingOptions' - $ref: '#/components/schemas/GenericKey' VisitorDataExistsMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithBooleanValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/VisitorDataExistsMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/ChoiceMatchingOptions' CookieMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithStringValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/CookieMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/CookieMatchingOptions' key: description: The name of the cookie which value is compared to the given rule value type: string CountryMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithCountryCodeValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/CountryMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/ChoiceMatchingOptions' JsConditionMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithJsCodeValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/JsConditionMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/ChoiceMatchingOptions' VisitorTypeMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithVisitorTypeValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/VisitorTypeMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/ChoiceMatchingOptions' LanguageMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithLanguageCodeValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/LanguageMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/ChoiceMatchingOptions' GoalTriggeredMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithGoalTriggeredValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/GoalTriggeredMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/ChoiceMatchingOptions' SegmentBucketedMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithSegmentBucketedValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/SegmentBucketedMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/ChoiceMatchingOptions' ExperienceBucketedMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithExperienceBucketedValue' - type: object required: - rule_type properties: rule_type: type: string matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/ChoiceMatchingOptions' 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' HourOfDayMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithHourOfDayValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/HourOfDayMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/NumericMatchingOptions' MinuteOfHourMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithMinuteOfHourValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/MinuteOfHourMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/NumericMatchingOptions' BrowserNameMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithBrowserNameValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/BrowserNameMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/ChoiceMatchingOptions' OsMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithOsValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/OsMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/ChoiceMatchingOptions' WeatherConditionMatchRule: allOf: - $ref: '#/components/schemas/BaseRuleWithWeatherConditionValue' - type: object required: - rule_type properties: rule_type: $ref: '#/components/schemas/WeatherConditionMatchRulesTypes' matching: allOf: - $ref: '#/components/schemas/BaseMatch' - type: object properties: match_type: $ref: '#/components/schemas/TextMatchingOptions' RuleElementNoUrl: oneOf: - $ref: '#/components/schemas/GenericTextMatchRule' - $ref: '#/components/schemas/GenericNumericMatchRule' - $ref: '#/components/schemas/GenericBoolMatchRule' - $ref: '#/components/schemas/CookieMatchRule' - $ref: '#/components/schemas/GenericTextKeyValueMatchRule' - $ref: '#/components/schemas/GenericNumericKeyValueMatchRule' - $ref: '#/components/schemas/GenericBoolKeyValueMatchRule' - $ref: '#/components/schemas/CountryMatchRule' - $ref: '#/components/schemas/LanguageMatchRule' - $ref: '#/components/schemas/GoalTriggeredMatchRule' - $ref: '#/components/schemas/SegmentBucketedMatchRule' - $ref: '#/components/schemas/DayOfWeekMatchRule' - $ref: '#/components/schemas/HourOfDayMatchRule' - $ref: '#/components/schemas/MinuteOfHourMatchRule' - $ref: '#/components/schemas/BrowserNameMatchRule' - $ref: '#/components/schemas/OsMatchRule' - $ref: '#/components/schemas/WeatherConditionMatchRule' - $ref: '#/components/schemas/VisitorTypeMatchRule' - $ref: '#/components/schemas/JsConditionMatchRule' - $ref: '#/components/schemas/VisitorDataExistsMatchRule' discriminator: propertyName: rule_type mapping: campaign: '#/components/schemas/GenericTextMatchRule' keyword: '#/components/schemas/GenericTextMatchRule' medium: '#/components/schemas/GenericTextMatchRule' source_name: '#/components/schemas/GenericTextMatchRule' avg_time_page: '#/components/schemas/GenericNumericMatchRule' city: '#/components/schemas/GenericTextMatchRule' country: '#/components/schemas/CountryMatchRule' region: '#/components/schemas/GenericTextMatchRule' days_since_last_visit: '#/components/schemas/GenericNumericMatchRule' language: '#/components/schemas/LanguageMatchRule' pages_visited_count: '#/components/schemas/GenericNumericMatchRule' goal_triggered: '#/components/schemas/GoalTriggeredMatchRule' visit_duration: '#/components/schemas/GenericNumericMatchRule' cookie: '#/components/schemas/CookieMatchRule' visitor_type: '#/components/schemas/VisitorTypeMatchRule' visits_count: '#/components/schemas/GenericNumericMatchRule' bucketed_into_experience: '#/components/schemas/GenericBoolMatchRule' bucketed_into_segment: '#/components/schemas/SegmentBucketedMatchRule' local_time_day_of_week: '#/components/schemas/DayOfWeekMatchRule' local_time_hour_of_day: '#/components/schemas/HourOfDayMatchRule' local_time_minute_of_hour: '#/components/schemas/MinuteOfHourMatchRule' project_time_day_of_week: '#/components/schemas/DayOfWeekMatchRule' project_time_hour_of_day: '#/components/schemas/HourOfDayMatchRule' project_time_minute_of_hour: '#/components/schemas/MinuteOfHourMatchRule' browser_name: '#/components/schemas/BrowserNameMatchRule' browser_version: '#/components/schemas/GenericTextMatchRule' os: '#/components/schemas/OsMatchRule' user_agent: '#/components/schemas/GenericTextMatchRule' is_desktop: '#/components/schemas/GenericBoolMatchRule' is_mobile: '#/components/schemas/GenericBoolMatchRule' is_tablet: '#/components/schemas/GenericBoolMatchRule' js_condition: '#/components/schemas/JsConditionMatchRule' page_tag_page_type: '#/components/schemas/GenericTextMatchRule' page_tag_category_id: '#/components/schemas/GenericTextMatchRule' page_tag_category_name: '#/components/schemas/GenericTextMatchRule' page_tag_product_sku: '#/components/schemas/GenericTextMatchRule' page_tag_product_name: '#/components/schemas/GenericTextMatchRule' page_tag_product_price: '#/components/schemas/GenericNumericMatchRule' page_tag_customer_id: '#/components/schemas/GenericTextMatchRule' page_tag_custom_1: '#/components/schemas/GenericTextMatchRule' page_tag_custom_2: '#/components/schemas/GenericTextMatchRule' page_tag_custom_3: '#/components/schemas/GenericTextMatchRule' page_tag_custom_4: '#/components/schemas/GenericTextMatchRule' weather_condition: '#/components/schemas/WeatherConditionMatchRule' generic_text_key_value: '#/components/schemas/GenericTextKeyValueMatchRule' generic_numeric_key_value: '#/components/schemas/GenericNumericKeyValueMatchRule' generic_bool_key_value: '#/components/schemas/GenericBoolKeyValueMatchRule' visitor_id: '#/components/schemas/GenericTextMatchRule' visitor_data_exists: '#/components/schemas/VisitorDataExistsMatchRule' RuleElement: oneOf: - $ref: '#/components/schemas/GenericTextMatchRule' - $ref: '#/components/schemas/GenericNumericMatchRule' - $ref: '#/components/schemas/GenericBoolMatchRule' - $ref: '#/components/schemas/GenericTextKeyValueMatchRule' - $ref: '#/components/schemas/GenericNumericKeyValueMatchRule' - $ref: '#/components/schemas/GenericBoolKeyValueMatchRule' - $ref: '#/components/schemas/CookieMatchRule' - $ref: '#/components/schemas/CountryMatchRule' - $ref: '#/components/schemas/LanguageMatchRule' - $ref: '#/components/schemas/GoalTriggeredMatchRule' - $ref: '#/components/schemas/SegmentBucketedMatchRule' - $ref: '#/components/schemas/DayOfWeekMatchRule' - $ref: '#/components/schemas/HourOfDayMatchRule' - $ref: '#/components/schemas/MinuteOfHourMatchRule' - $ref: '#/components/schemas/BrowserNameMatchRule' - $ref: '#/components/schemas/OsMatchRule' - $ref: '#/components/schemas/WeatherConditionMatchRule' - $ref: '#/components/schemas/VisitorTypeMatchRule' - $ref: '#/components/schemas/JsConditionMatchRule' discriminator: propertyName: rule_type mapping: url: '#/components/schemas/GenericTextMatchRule' url_with_query: '#/components/schemas/GenericTextMatchRule' query_string: '#/components/schemas/GenericTextMatchRule' campaign: '#/components/schemas/GenericTextMatchRule' keyword: '#/components/schemas/GenericTextMatchRule' medium: '#/components/schemas/GenericTextMatchRule' source_name: '#/components/schemas/GenericTextMatchRule' avg_time_page: '#/components/schemas/GenericNumericMatchRule' city: '#/components/schemas/GenericTextMatchRule' country: '#/components/schemas/CountryMatchRule' region: '#/components/schemas/GenericTextMatchRule' days_since_last_visit: '#/components/schemas/GenericNumericMatchRule' language: '#/components/schemas/LanguageMatchRule' pages_visited_count: '#/components/schemas/GenericNumericMatchRule' goal_triggered: '#/components/schemas/GoalTriggeredMatchRule' visit_duration: '#/components/schemas/GenericNumericMatchRule' cookie: '#/components/schemas/CookieMatchRule' visitor_type: '#/components/schemas/VisitorTypeMatchRule' visits_count: '#/components/schemas/GenericNumericMatchRule' bucketed_into_experience: '#/components/schemas/GenericBoolMatchRule' bucketed_into_segment: '#/components/schemas/SegmentBucketedMatchRule' local_time_day_of_week: '#/components/schemas/DayOfWeekMatchRule' local_time_hour_of_day: '#/components/schemas/HourOfDayMatchRule' local_time_minute_of_hour: '#/components/schemas/MinuteOfHourMatchRule' project_time_day_of_week: '#/components/schemas/DayOfWeekMatchRule' project_time_hour_of_day: '#/components/schemas/HourOfDayMatchRule' project_time_minute_of_hour: '#/components/schemas/MinuteOfHourMatchRule' browser_name: '#/components/schemas/BrowserNameMatchRule' browser_version: '#/components/schemas/GenericTextMatchRule' os: '#/components/schemas/OsMatchRule' user_agent: '#/components/schemas/GenericTextMatchRule' is_desktop: '#/components/schemas/GenericBoolMatchRule' is_mobile: '#/components/schemas/GenericBoolMatchRule' is_tablet: '#/components/schemas/GenericBoolMatchRule' js_condition: '#/components/schemas/JsConditionMatchRule' page_tag_page_type: '#/components/schemas/GenericTextMatchRule' page_tag_category_id: '#/components/schemas/GenericTextMatchRule' page_tag_category_name: '#/components/schemas/GenericTextMatchRule' page_tag_product_sku: '#/components/schemas/GenericTextMatchRule' page_tag_product_name: '#/components/schemas/GenericTextMatchRule' page_tag_product_price: '#/components/schemas/GenericNumericMatchRule' page_tag_customer_id: '#/components/schemas/GenericTextMatchRule' page_tag_custom_1: '#/components/schemas/GenericTextMatchRule' page_tag_custom_2: '#/components/schemas/GenericTextMatchRule' page_tag_custom_3: '#/components/schemas/GenericTextMatchRule' page_tag_custom_4: '#/components/schemas/GenericTextMatchRule' weather_condition: '#/components/schemas/WeatherConditionMatchRule' generic_text_key_value: '#/components/schemas/GenericTextKeyValueMatchRule' generic_numeric_key_value: '#/components/schemas/GenericNumericKeyValueMatchRule' generic_bool_key_value: '#/components/schemas/GenericBoolKeyValueMatchRule' RuleElementAudience: oneOf: - $ref: '#/components/schemas/GenericTextMatchRule' - $ref: '#/components/schemas/GenericNumericMatchRule' - $ref: '#/components/schemas/GenericBoolMatchRule' - $ref: '#/components/schemas/GenericTextKeyValueMatchRule' - $ref: '#/components/schemas/GenericNumericKeyValueMatchRule' - $ref: '#/components/schemas/GenericBoolKeyValueMatchRule' - $ref: '#/components/schemas/CookieMatchRule' - $ref: '#/components/schemas/CountryMatchRule' - $ref: '#/components/schemas/LanguageMatchRule' - $ref: '#/components/schemas/GoalTriggeredMatchRule' - $ref: '#/components/schemas/SegmentBucketedMatchRule' - $ref: '#/components/schemas/DayOfWeekMatchRule' - $ref: '#/components/schemas/HourOfDayMatchRule' - $ref: '#/components/schemas/MinuteOfHourMatchRule' - $ref: '#/components/schemas/BrowserNameMatchRule' - $ref: '#/components/schemas/OsMatchRule' - $ref: '#/components/schemas/WeatherConditionMatchRule' - $ref: '#/components/schemas/VisitorTypeMatchRule' - $ref: '#/components/schemas/JsConditionMatchRule' - $ref: '#/components/schemas/VisitorDataExistsMatchRule' discriminator: propertyName: rule_type mapping: url: '#/components/schemas/GenericTextMatchRule' url_with_query: '#/components/schemas/GenericTextMatchRule' query_string: '#/components/schemas/GenericTextMatchRule' campaign: '#/components/schemas/GenericTextMatchRule' keyword: '#/components/schemas/GenericTextMatchRule' medium: '#/components/schemas/GenericTextMatchRule' source_name: '#/components/schemas/GenericTextMatchRule' avg_time_page: '#/components/schemas/GenericNumericMatchRule' city: '#/components/schemas/GenericTextMatchRule' country: '#/components/schemas/CountryMatchRule' region: '#/components/schemas/GenericTextMatchRule' days_since_last_visit: '#/components/schemas/GenericNumericMatchRule' language: '#/components/schemas/LanguageMatchRule' pages_visited_count: '#/components/schemas/GenericNumericMatchRule' goal_triggered: '#/components/schemas/GoalTriggeredMatchRule' visit_duration: '#/components/schemas/GenericNumericMatchRule' cookie: '#/components/schemas/CookieMatchRule' visitor_type: '#/components/schemas/VisitorTypeMatchRule' visits_count: '#/components/schemas/GenericNumericMatchRule' bucketed_into_experience: '#/components/schemas/GenericBoolMatchRule' bucketed_into_segment: '#/components/schemas/SegmentBucketedMatchRule' local_time_day_of_week: '#/components/schemas/DayOfWeekMatchRule' local_time_hour_of_day: '#/components/schemas/HourOfDayMatchRule' local_time_minute_of_hour: '#/components/schemas/MinuteOfHourMatchRule' project_time_day_of_week: '#/components/schemas/DayOfWeekMatchRule' project_time_hour_of_day: '#/components/schemas/HourOfDayMatchRule' project_time_minute_of_hour: '#/components/schemas/MinuteOfHourMatchRule' browser_name: '#/components/schemas/BrowserNameMatchRule' browser_version: '#/components/schemas/GenericTextMatchRule' os: '#/components/schemas/OsMatchRule' user_agent: '#/components/schemas/GenericTextMatchRule' is_desktop: '#/components/schemas/GenericBoolMatchRule' is_mobile: '#/components/schemas/GenericBoolMatchRule' is_tablet: '#/components/schemas/GenericBoolMatchRule' js_condition: '#/components/schemas/JsConditionMatchRule' page_tag_page_type: '#/components/schemas/GenericTextMatchRule' page_tag_category_id: '#/components/schemas/GenericTextMatchRule' page_tag_category_name: '#/components/schemas/GenericTextMatchRule' page_tag_product_sku: '#/components/schemas/GenericTextMatchRule' page_tag_product_name: '#/components/schemas/GenericTextMatchRule' page_tag_product_price: '#/components/schemas/GenericNumericMatchRule' page_tag_customer_id: '#/components/schemas/GenericTextMatchRule' page_tag_custom_1: '#/components/schemas/GenericTextMatchRule' page_tag_custom_2: '#/components/schemas/GenericTextMatchRule' page_tag_custom_3: '#/components/schemas/GenericTextMatchRule' page_tag_custom_4: '#/components/schemas/GenericTextMatchRule' weather_condition: '#/components/schemas/WeatherConditionMatchRule' generic_text_key_value: '#/components/schemas/GenericTextKeyValueMatchRule' generic_numeric_key_value: '#/components/schemas/GenericNumericKeyValueMatchRule' generic_bool_key_value: '#/components/schemas/GenericBoolKeyValueMatchRule' visitor_id: '#/components/schemas/GenericTextMatchRule' visitor_data_exists: '#/components/schemas/VisitorDataExistsMatchRule' TextMatchingOptions: type: string enum: - matches - regexMatches - contains - endsWith - startsWith CookieMatchingOptions: type: string enum: - matches - regexMatches - contains - endsWith - startsWith - exists - doesNotExist NumericMatchingOptions: type: string enum: - equalsNumber - less - lessEqual ChoiceMatchingOptions: type: string enum: - equals ChoiceContainsOptions: type: string enum: - contains SetMatchingOptions: type: string enum: - isIn RuleObject: type: object nullable: true description: 'Defines the logical structure for combining multiple rule conditions. It uses a nested OR -> AND -> OR_WHEN structure. - The top-level `OR` array means if *any* of its contained AND blocks evaluate to true, the entire rule set is true. - Each object within the `OR` array has an `AND` array. For this AND block to be true, *all* of its contained OR_WHEN blocks must evaluate to true. - Each object within the `AND` array has an `OR_WHEN` array. For this OR_WHEN block to be true, *any* of its individual `RuleElement` conditions must evaluate to true. This structure allows for complex logical expressions like `(CondA AND CondB) OR (CondC AND CondD)`. ' properties: OR: description: An array of AND-blocks. The overall rule matches if any of these AND-blocks match. type: array items: type: object properties: AND: description: An array of OR_WHEN-blocks. This AND-block matches if all its OR_WHEN-blocks match. type: array items: type: object properties: OR_WHEN: description: An array of individual rule elements. This OR_WHEN-block matches if any of its rule elements match. type: array items: $ref: '#/components/schemas/RuleElement' RuleObjectNoUrl: type: object nullable: true description: 'Similar to `RuleObject`, but the individual `RuleElementNoUrl` conditions within `OR_WHEN` arrays cannot include URL-based matching types. Used for ''permanent'' or ''transient'' audiences where URL context is not persistently evaluated or relevant for the audience type. ' properties: OR: description: An array of AND-blocks. type: array items: type: object properties: AND: description: An array of OR_WHEN-blocks. type: array items: type: object properties: OR_WHEN: description: An array of individual rule elements that do not involve URL matching. type: array items: $ref: '#/components/schemas/RuleElementNoUrl' RuleObjectAudience: type: object nullable: true description: This one describes a logical rule that is being used inside the app for triggering goals, matching audiences etc properties: OR: description: This describes an outer set of blocks which are evaluated using OR's between them type: array items: type: object properties: AND: description: This describes a colections of logical blocks which are evaluated using AND's between them type: array items: type: object properties: OR_WHEN: description: This describes a colections of logical blocks which are evaluated using OR's between them type: array items: $ref: '#/components/schemas/RuleElementAudience' Base64Image: type: object properties: data: description: The base64 encoded string representation of the image's binary data. 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 SuccessData: type: object properties: code: type: integer format: int32 message: type: string ImportProjectDataSuccess: allOf: - $ref: '#/components/schemas/SuccessData' - type: object properties: imported: type: object description: List of imported objects properties: experiences: type: array description: List of created experiences. Empty if nothing imported items: type: integer audiences: type: array description: List of created audiences. Empty if nothing imported items: type: integer locations: type: array description: List of created locations. Empty if nothing imported items: type: integer goals: type: array description: List of created goals. Empty if nothing imported items: type: integer hypothesis: type: array description: List of created hypothesis. Empty if nothing imported items: type: integer BulkSuccessData: allOf: - $ref: '#/components/schemas/SuccessData' - type: object properties: code: type: integer format: int32 errors: type: array description: List of unprocessed entities. Would be empty, if all passed entities processed items: $ref: '#/components/schemas/BulkEntityError' BulkEntityError: type: object additionalProperties: false properties: id: type: integer description: The unique identifier of the entity that could not be processed. message: type: string description: A message explaining the reason for the failure for this specific entity. UTC_Offset: type: integer description: 'The time offset from Coordinated Universal Time (UTC) in seconds. For example, UTC-5 (EST) would be -18000. UTC+2 would be 7200. Used for interpreting or displaying date/time information according to a specific timezone. ' default: 0 minimum: -43200 maximum: 50400 GA_SettingsBase: type: object properties: enabled: type: boolean description: If true, integration with Google Analytics is enabled for this project or experience, allowing experiment data to be sent to GA. 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. IntegrationGA4Base: type: object properties: type: enum: - ga4 measurementId: type: string description: The GA4 Measurement ID (e.g., "G-XXXXXXXXXX") for the data stream where Convert experiment data will be sent. IntegrationGA4: allOf: - $ref: '#/components/schemas/IntegrationGA4Base' - type: object properties: propertyId: type: string description: ID of the ga4 property where data will be sent. Used internally for API calls to GoogleAnalytics 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 VisitorInsightsBase: type: object properties: enabled: type: boolean description: "If true, Convert Signals\u2122 is enabled for the project, allowing the system to capture sessions\ \ exhibiting user frustration or usability issues.\n" obfuscate_text: type: boolean default: true description: 'True when all text elements (apart from placeholders) should be obfuscated inside a recording. ' sampling_rate: type: integer default: 5 enum: - 5 - 10 - 20 - 30 - 40 - 50 description: 'The percentage of visitors included in sampling for Convert Signals session recordings and Heatmaps for this project. Higher values collect data from a larger share of traffic and consume allocation faster. ' NumericOutlierTypes: description: 'The method used for detecting and handling order outliers in revenue or product count tracking: - `none`: No outlier detection is applied. - `min_max`: Orders with values below a specified minimum or above a specified maximum are capped at those boundaries. - `percentile`: Orders falling below a lower percentile or above an upper percentile are capped at the values corresponding to those percentiles. ' type: string enum: - none - min_max - percentile NumericOutlierBase: type: object properties: detection_type: $ref: '#/components/schemas/NumericOutlierTypes' required: - detection_type NumericOutlierNone: allOf: - $ref: '#/components/schemas/NumericOutlierBase' - type: object additionalProperties: false properties: detection_type: enum: - none NumericOutlierMinMax: allOf: - $ref: '#/components/schemas/NumericOutlierBase' - type: object additionalProperties: false properties: detection_type: enum: - min_max min: type: number description: Minimum value for the outlier detection, under which, the value is considered an outlier max: type: number description: Maximum value for the outlier detection, over which, the value is considered an outlier NumericOutlierPercentile: allOf: - $ref: '#/components/schemas/NumericOutlierBase' - type: object additionalProperties: false properties: detection_type: enum: - percentile min: allOf: - description: Minimum percentile value for the outlier detection; values outside this percentile are considered outliers - $ref: '#/components/schemas/Percentiles' max: allOf: - description: Maximum percentile value for the outlier detection; values outside this percentile are considered outliers - $ref: '#/components/schemas/Percentiles' NumericOutlier: oneOf: - $ref: '#/components/schemas/NumericOutlierNone' - $ref: '#/components/schemas/NumericOutlierMinMax' - $ref: '#/components/schemas/NumericOutlierPercentile' discriminator: propertyName: detection_type mapping: none: '#/components/schemas/NumericOutlierNone' min_max: '#/components/schemas/NumericOutlierMinMax' percentile: '#/components/schemas/NumericOutlierPercentile' Percentiles: type: number description: 'Standard percentile values used for outlier detection thresholds. For example, a `min` of 5 and `max` of 95 means orders in the bottom 5% and top 5% of values are considered outliers and capped. ' enum: - 1 - 5 - 10 - 25 - 50 - 75 - 90 - 95 - 99 TimeRange: type: object properties: start_time: type: number nullable: true description: Unix timestamp (seconds since epoch, UTC) marking the beginning of the time range. If null, implies from the beginning of data. end_time: type: number nullable: true description: Unix timestamp (seconds since epoch, UTC) marking the end of the time range. If null, implies up to the current time. utc_offset: $ref: '#/components/schemas/UTC_Offset' UploadedFileData: type: object description: File Object additionalProperties: false properties: key: description: Storage key of the uploaded file. type: string maxLength: 500 name: description: Original name of the uploaded file. type: string maxLength: 250 url: description: Endpoint to access the file resource associated with the project. type: string readOnly: true example: https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/files/{fileKey} 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. GetDomainsListRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/DomainsListDataOptions' - $ref: '#/components/schemas/PageNumber' - type: object properties: only: description: 'Only retrieve domains with the given ids. ' type: array nullable: true items: type: integer maxItems: 100 except: description: 'Except domains with the given ids. ' type: array items: type: integer maxItems: 100 GetDomainByUrlRequestData: type: object description: Get domain by URL request data properties: url: type: string maxLength: 255 description: URL by which to search the domain. The match can be an exact one or an wildcard one. CheckCodeDomainRequestData: type: object description: Check if tracking code is installed on the given URL; properties: url: type: string maxLength: 255 description: 'URL on which to check the tracking code installed. The given URL needs to be under the domain passes as parameter or otherwise an error would be returned. ' DomainsListResponseData: type: object description: Response containing a list of domains and extra domains list metadata properties: data: $ref: '#/components/schemas/DomainsList' extra: $ref: '#/components/schemas/Extra' DomainsList: type: array description: List of domains items: $ref: '#/components/schemas/Domain' Domain: type: object description: A website domain data. properties: id: type: integer description: Domain ID. readOnly: true url: type: string maxLength: 150 pattern: ^(http|https):// description: Domain's homepage url code_installed: type: boolean description: Indicating whether code installed check passed sometimes in the past. default: false DomainToCreate: required: - url allOf: - $ref: '#/components/schemas/Domain' CreateDomainRequestData: allOf: - $ref: '#/components/schemas/DomainToCreate' UpdateDomainRequestData: allOf: - $ref: '#/components/schemas/Domain' DomainExpandable: description: Expandable domain object. oneOf: - type: integer description: Domain ID - $ref: '#/components/schemas/Domain' DomainExpandableRequest: description: Domain object sent inside request when creating/updating other related objects oneOf: - type: integer description: Domain ID - $ref: '#/components/schemas/DomainToCreate' DomainsListDataOptions: type: object description: Filter domains list. allOf: - $ref: '#/components/schemas/ResultsPerPage' BulkDomainsIds: type: array description: The list of domains id to delete items: type: integer minItems: 1 maxItems: 100 BulkDeleteDomainRequestData: type: object description: Bulk Delete provided domains additionalProperties: false properties: id: $ref: '#/components/schemas/BulkDomainsIds' required: - id 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 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 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 ExperienceChangeServing: description: Object that represents one change done inside an experience oneOf: - $ref: '#/components/schemas/ExperienceChangeDefaultCodeDataServing' - $ref: '#/components/schemas/ExperienceChangeDefaultCodeMultipageDataServing' - $ref: '#/components/schemas/ExperienceChangeDefaultRedirectDataServing' - $ref: '#/components/schemas/ExperienceChangeCustomCodeDataServing' - $ref: '#/components/schemas/ExperienceChangeRichStructureDataServing' - $ref: '#/components/schemas/ExperienceChangeFullStackFeatureServing' discriminator: propertyName: type mapping: defaultCode: '#/components/schemas/ExperienceChangeDefaultCodeDataServing' defaultCodeMultipage: '#/components/schemas/ExperienceChangeDefaultCodeMultipageDataServing' defaultRedirect: '#/components/schemas/ExperienceChangeDefaultRedirectDataServing' customCode: '#/components/schemas/ExperienceChangeCustomCodeDataServing' richStructure: '#/components/schemas/ExperienceChangeRichStructureDataServing' fullStackFeature: '#/components/schemas/ExperienceChangeFullStackFeatureServing' 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' 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' ExperienceChangeUpdate: description: Data structure for updating an existing change within an experience variation. Requires the `id` of the change to be modified. oneOf: - $ref: '#/components/schemas/ExperienceChangeDefaultCodeDataUpdate' - $ref: '#/components/schemas/ExperienceChangeDefaultCodeMultipageDataUpdate' - $ref: '#/components/schemas/ExperienceChangeDefaultRedirectDataUpdate' - $ref: '#/components/schemas/ExperienceChangeRichStructureDataUpdate' - $ref: '#/components/schemas/ExperienceChangeCustomCodeDataUpdate' - $ref: '#/components/schemas/ExperienceChangeFullStackFeatureUpdate' discriminator: propertyName: type mapping: richStructure: '#/components/schemas/ExperienceChangeRichStructureDataUpdate' customCode: '#/components/schemas/ExperienceChangeCustomCodeDataUpdate' defaultCode: '#/components/schemas/ExperienceChangeDefaultCodeDataUpdate' defaultCodeMultipage: '#/components/schemas/ExperienceChangeDefaultCodeMultipageDataUpdate' defaultRedirect: '#/components/schemas/ExperienceChangeDefaultRedirectDataUpdate' fullStackFeature: '#/components/schemas/ExperienceChangeFullStackFeatureUpdate' ExperienceChangeUpdateNoId: description: Data structure for defining a change when updating a collection of changes (e.g., within a variation update), where the `id` might be part of a parent object or implied. oneOf: - $ref: '#/components/schemas/ExperienceChangeDefaultCodeDataUpdateNoId' - $ref: '#/components/schemas/ExperienceChangeDefaultCodeMultipageDataUpdateNoId' - $ref: '#/components/schemas/ExperienceChangeDefaultRedirectDataUpdateNoId' - $ref: '#/components/schemas/ExperienceChangeRichStructureDataUpdateNoId' - $ref: '#/components/schemas/ExperienceChangeCustomCodeDataUpdateNoId' - $ref: '#/components/schemas/ExperienceChangeFullStackFeatureUpdateNoId' discriminator: propertyName: type mapping: richStructure: '#/components/schemas/ExperienceChangeRichStructureDataUpdateNoId' customCode: '#/components/schemas/ExperienceChangeCustomCodeDataUpdateNoId' defaultCode: '#/components/schemas/ExperienceChangeDefaultCodeDataUpdateNoId' defaultCodeMultipage: '#/components/schemas/ExperienceChangeDefaultCodeMultipageDataUpdateNoId' defaultRedirect: '#/components/schemas/ExperienceChangeDefaultRedirectDataUpdateNoId' fullStackFeature: '#/components/schemas/ExperienceChangeFullStackFeatureUpdateNoId' 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 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' ExperienceChangeDefaultCodeDataServing: type: object description: Describes structure for "defaultCode" type of experience change allOf: - $ref: '#/components/schemas/ExperienceChangeIdReadOnly' - $ref: '#/components/schemas/ExperienceChangeDefaultCodeDataBase' 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 ExperienceChangeDefaultCodeDataUpdateNoId: type: object description: Data for updating a 'defaultCode' type change when its ID is managed externally. allOf: - $ref: '#/components/schemas/ExperienceChangeDefaultCodeDataBase' - type: object properties: concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' - required: - type - data ExperienceChangeDefaultCodeDataUpdate: type: object description: Data for updating an existing 'defaultCode' type change, identified by its `id`. allOf: - $ref: '#/components/schemas/ExperienceChangeId' - $ref: '#/components/schemas/ExperienceChangeDefaultCodeDataBase' - type: object properties: concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' - 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 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' ExperienceChangeDefaultRedirectDataServing: type: object description: Describes structure for "defaultRedirect" type of experience change allOf: - $ref: '#/components/schemas/ExperienceChangeIdReadOnly' - $ref: '#/components/schemas/ExperienceChangeDefaultRedirectDataBase' 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 ExperienceChangeDefaultRedirectDataUpdateNoId: type: object description: Data for updating a 'defaultRedirect' type change when its ID is managed externally. allOf: - $ref: '#/components/schemas/ExperienceChangeDefaultRedirectDataBase' - type: object properties: concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' - required: - type - data ExperienceChangeDefaultRedirectDataUpdate: type: object description: Data for updating an existing 'defaultRedirect' type change, identified by its `id`. allOf: - $ref: '#/components/schemas/ExperienceChangeId' - $ref: '#/components/schemas/ExperienceChangeDefaultRedirectDataBase' - type: object properties: concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' - required: - type - data 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 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' ExperienceChangeDefaultCodeMultipageDataServing: type: object description: Describes structure for "defaultCodeMultipage" type of experience change allOf: - $ref: '#/components/schemas/ExperienceChangeIdReadOnly' - $ref: '#/components/schemas/ExperienceChangeDefaultCodeMultipageDataBase' 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 ExperienceChangeDefaultCodeMultipageDataUpdateNoId: type: object description: Data for updating a 'defaultCodeMultipage' type change when its ID is managed externally. allOf: - $ref: '#/components/schemas/ExperienceChangeDefaultCodeMultipageDataBase' - type: object properties: concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' - required: - type - data ExperienceChangeDefaultCodeMultipageDataUpdate: type: object description: Data for updating an existing 'defaultCodeMultipage' type change, identified by its `id`. allOf: - $ref: '#/components/schemas/ExperienceChangeId' - $ref: '#/components/schemas/ExperienceChangeDefaultCodeMultipageDataBase' - type: object properties: concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' - 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 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' ExperienceChangeRichStructureDataServing: type: object description: Describes structure for "defaultCode" type of experience change allOf: - $ref: '#/components/schemas/ExperienceChangeIdReadOnly' - $ref: '#/components/schemas/ExperienceChangeRichStructureDataBase' 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 ExperienceChangeRichStructureDataUpdateNoId: type: object description: Data for updating a 'richStructure' type change when its ID is managed externally. allOf: - $ref: '#/components/schemas/ExperienceChangeRichStructureDataBase' - type: object properties: concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' - required: - type - data ExperienceChangeRichStructureDataUpdate: type: object description: Data for updating an existing 'richStructure' type change, identified by its `id`. allOf: - $ref: '#/components/schemas/ExperienceChangeId' - $ref: '#/components/schemas/ExperienceChangeRichStructureDataBase' - type: object properties: concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' - required: - type - data 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 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' ExperienceChangeCustomCodeDataServing: type: object description: Describes structure for "defaultCode" type of experience change allOf: - $ref: '#/components/schemas/ExperienceChangeIdReadOnly' - $ref: '#/components/schemas/ExperienceChangeCustomCodeDataBase' 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 ExperienceChangeCustomCodeDataUpdateNoId: type: object description: Data for updating a 'customCode' type change when its ID is managed externally. allOf: - $ref: '#/components/schemas/ExperienceChangeCustomCodeDataBase' - type: object properties: concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' - required: - type - data ExperienceChangeCustomCodeDataUpdate: type: object description: Data for updating an existing 'customCode' type change, identified by its `id`. allOf: - $ref: '#/components/schemas/ExperienceChangeId' - $ref: '#/components/schemas/ExperienceChangeCustomCodeDataBase' - type: object properties: concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' - required: - type - data 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' ExperienceChangeFullStackFeatureServing: type: object description: Describes structure for "fullStackFeature" type of experience change allOf: - $ref: '#/components/schemas/ExperienceChangeIdReadOnly' - $ref: '#/components/schemas/ExperienceChangeFullStackFeatureBase' 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 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 ExperienceChangeFullStackFeatureUpdateNoId: type: object description: Data for updating a 'fullStackFeature' type change when its ID is managed externally. allOf: - $ref: '#/components/schemas/ExperienceChangeFullStackFeatureBase' - type: object properties: concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' - required: - type - data UpdateExperienceChangeRequestData: oneOf: - $ref: '#/components/schemas/ExperienceChangeAdd' IntegrationProvider: type: string description: 'Identifies the third-party analytics, heatmap, or data platform with which Convert Experiences is integrated for this specific experience. This allows experiment data (like experience ID and variation ID/name) to be sent to the selected provider. Knowledge Base has many articles on integrations, e.g., "Integrate Convert Experiences with Google Analytics", "Hotjar Integration". ' enum: - baidu - clicktale - clicky - cnzz - crazyegg - econda - eulerian - google_analytics - gosquared - heapanalytics - hotjar - microsoft_clarity - mixpanel - mouseflow - piwik - segmentio - sitecatalyst - woopra - ysance ExperienceIntegrationBase: type: object properties: provider: $ref: '#/components/schemas/IntegrationProvider' enabled: description: 'If `true`, this integration is active for the experience, and Convert will attempt to send experiment data to the specified provider. If `false` or omitted when updating, the integration is disabled. ' type: boolean nullable: true required: - provider ExperienceIntegrationBaidu: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' - type: object properties: custom_dimension: type: string description: Custom dimension where experience data should be sent to. required: - custom_dimension ExperienceIntegrationClicktale: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' ExperienceIntegrationClicky: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' ExperienceIntegrationCnzz: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' - type: object properties: custom_dimension: type: string description: Custom dimension where experience data should be sent to. required: - custom_dimension ExperienceIntegrationCrazyegg: description: 'Configuration for integrating with Crazy Egg. Convert sends experiment and variation data to allow segmentation of Crazy Egg heatmaps and recordings by variation. Project-level API key and secret for Crazy Egg might be required for some functionalities (not specified here, but in KB for other tools). KB: "Integrate Convert Experiences with Crazy Egg". ' allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' ExperienceIntegrationEconda: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' ExperienceIntegrationEulerian: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' ExperienceIntegrationGA3: allOf: - $ref: '#/components/schemas/GA_SettingsBase' - $ref: '#/components/schemas/ExperienceIntegrationBase' - $ref: '#/components/schemas/IntegrationGA3' - type: object properties: custom_dimension: type: string description: Custom dimension where experience data should be sent to. ExperienceIntegrationGA4Base: allOf: - $ref: '#/components/schemas/GA_SettingsBase' - $ref: '#/components/schemas/ExperienceIntegrationBase' - $ref: '#/components/schemas/IntegrationGA4Base' ExperienceIntegrationGA4: allOf: - $ref: '#/components/schemas/ExperienceIntegrationGA4Base' - $ref: '#/components/schemas/IntegrationGA4' - type: object properties: audiences: type: object description: List of GA audiences created for each of this experience's variations additionalProperties: type: string description: Variation ID is the key, value is the ID of the audience created inside GoogleAnalytics ExperienceIntegrationGoogleAnalytics: oneOf: - $ref: '#/components/schemas/ExperienceIntegrationGA3' - $ref: '#/components/schemas/ExperienceIntegrationGA4' discriminator: propertyName: type mapping: ga3: '#/components/schemas/ExperienceIntegrationGA3' ga4: '#/components/schemas/ExperienceIntegrationGA4' ExperienceIntegrationGosquared: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' ExperienceIntegrationHeapanalytics: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' ExperienceIntegrationHotjar: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' ExperienceIntegrationMicrosoftClarity: description: "Configuration for Microsoft Clarity. When enabled, experiment context can be sent for segmentation in\ \ Clarity recordings and heatmaps.\nNo provider-specific settings beyond `enabled` are required; the Clarity project\ \ ID is configured in your site\u2019s global JavaScript.\n" allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' ExperienceIntegrationMixpanel: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' ExperienceIntegrationMouseflow: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' ExperienceIntegrationPiwik: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' - type: object properties: custom_dimension: type: string description: Custom dimension where experience data should be sent to. required: - custom_dimension ExperienceIntegrationSegmentio: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' ExperienceIntegrationSitecatalyst: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' - type: object properties: evar: type: string description: Custom dimension where experience data should be sent to. required: - evar ExperienceIntegrationWoopra: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' ExperienceIntegrationYsance: allOf: - $ref: '#/components/schemas/ExperienceIntegrationBase' - type: object properties: custom_dimension: type: string description: Custom dimension where experience data should be sent to. required: - custom_dimension BaseSectionVersion: type: object properties: id: description: 'A unique identifier for this version within its parent section (e.g., "v1", "02", "ab"). Typically a short string (1-2 characters). This ID is used to construct the overall MVT variation combinations. ' type: string minLength: 1 maxLength: 2 pattern: ^[0-9a-z]{1,2}$ name: description: A user-defined, friendly name for this version (e.g., "Red Button", "Headline Option A", "Original Image"). This name appears in MVT setup and reports. type: string maxLength: 200 concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' SectionVersion: allOf: - $ref: '#/components/schemas/BaseSectionVersion' - type: object properties: changes: type: array items: oneOf: - type: integer description: Change ID - $ref: '#/components/schemas/ExperienceChange' variations: type: array items: oneOf: - type: integer description: Variation ID SectionVersionCreate: allOf: - $ref: '#/components/schemas/BaseSectionVersion' - type: object properties: changes: type: array description: List of changes to apply. If ID of a change is not provided, the change is gonna be created. Otherwise the change would be updated items: oneOf: - $ref: '#/components/schemas/ExperienceChangeAdd' SectionVersionUpdate: allOf: - $ref: '#/components/schemas/BaseSectionVersion' - type: object properties: concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' changes: type: array description: List of changes to apply. If ID of a change is not provided, the change is gonna be created. Empty array will remove changes. Otherwise the change would be updated items: anyOf: - $ref: '#/components/schemas/ExperienceChangeId' - $ref: '#/components/schemas/ExperienceChangeUpdate' - $ref: '#/components/schemas/ExperienceChangeAdd' ExperienceSectionVersionResponseData: description: Response containing the details of a single MVT section version. type: object properties: data: $ref: '#/components/schemas/SectionVersion' CreateSectionVersionRequestData: allOf: - $ref: '#/components/schemas/SectionVersionCreate' UpdateSectionVersionRequestData: allOf: - $ref: '#/components/schemas/SectionVersionUpdate' ExperienceSectionVersionIncludeFields: type: string enum: - changes ExperienceSectionVersionExpandFields: type: string enum: - changes ExperienceSectionsListResponseData: description: Response containing a list of sections defined for a Multivariate (MVT) experience. type: object properties: data: $ref: '#/components/schemas/ExperienceSectionsList' concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' ExperienceSectionsList: description: A list of MVT experience section objects. type: array items: $ref: '#/components/schemas/ExperienceSection' ExperienceSection: allOf: - $ref: '#/components/schemas/BaseExperienceSection' - type: object properties: versions: type: array description: 'Version definition. Each Multivariate experience is made of a list of **Sections** and a list of **Versions** Than, variations of a Multivariate experience are made of all possible combinations of versions, takin one from each section. Example: Experience has Section A and Section B. Section A has Version 1 and Version 2, Section B has Version 3 and Version 4 The resulting experience''s variations will be the following: 1. Section A - Version 1 + Section B - Version 3 1. Section A - Version 2 + Section B - Version 3 1. Section A - Version 1 + Section B - Version 4 1. Section A - Version 1 + Section B - Version 4 ' items: oneOf: - type: string description: Version ID - $ref: '#/components/schemas/SectionVersion' BaseExperienceSection: description: Base properties for a section within a Multivariate (MVT) experience. type: object properties: id: description: 'A unique identifier for this section within the MVT experience (e.g., "s1", "01", "ab"). Typically a short string (1-2 characters). This ID helps in structuring the MVT test. ' type: string minLength: 1 maxLength: 2 pattern: ^[0-9a-z]{1,2}$ name: description: A user-defined, friendly name for this section (e.g., "Page Headline", "Main Call-to-Action Button", "Hero Image"). This name appears in MVT setup and reports. type: string maxLength: 200 concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' UpdateExperienceSectionsRequestData: description: 'Request body for updating all sections (and their versions/changes) for a Multivariate (MVT) experience. The provided list of `sections` will completely replace the existing MVT structure. Any existing sections not included in the request will be removed. The order of sections, versions, and changes is significant and will be preserved. **Caution:** Major structural changes to an active MVT can invalidate test results. ' type: object properties: sections: description: 'An array of `UpdateSectionRequestData` objects. Each object defines a section and its complete set of versions and changes. - To update an existing section, provide its `id` and modified `name` or `versions`. - To add a new section, provide a new unique `id` (1-2 chars), `name`, and its `versions`. - Sections from the current MVT configuration not present in this array will be deleted. ' type: array items: $ref: '#/components/schemas/UpdateSectionRequestData' concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' CreateSectionRequestData: allOf: - $ref: '#/components/schemas/BaseExperienceSection' - type: object properties: versions: type: array description: 'Version definition. Each Multivariate experience is made of a list of **Sections** and a list of **Versions** Than, variations of a Multivariate experience are made of all possible combinations of versions, takin one from each section. Example: Experience has Section A and Section B. Section A has Version 1 and Version 2, Section B has Version 3 and Version 4 The resulting experience''s variations will be the following: 1. Section A - Version 1 + Section B - Version 3 1. Section A - Version 2 + Section B - Version 3 1. Section A - Version 1 + Section B - Version 4 1. Section A - Version 1 + Section B - Version 4 ' items: $ref: '#/components/schemas/SectionVersionCreate' required: - versions UpdateSectionRequestData: allOf: - $ref: '#/components/schemas/BaseExperienceSection' - type: object properties: versions: type: array description: 'Version definition. Each Multivariate experience is made of a list of **Sections** and a list of **Versions** Than, variations of a Multivariate experience are made of all possible combinations of versions, takin one from each section. Example: Experience has Section A and Section B. Section A has Version 1 and Version 2, Section B has Version 3 and Version 4 The resulting experience''s variations will be the following: 1. Section A - Version 1 + Section B - Version 3 1. Section A - Version 2 + Section B - Version 3 1. Section A - Version 1 + Section B - Version 4 1. Section A - Version 1 + Section B - Version 4 ' items: $ref: '#/components/schemas/SectionVersionUpdate' required: - versions ExperienceSectionIncludeFields: type: string enum: - versions - versions.changes ExperienceSectionExpandFields: type: string enum: - versions - versions.changes ExperienceVariationStatuses: type: string enum: - stopped - running ExperienceVariationBase: type: object properties: name: description: A user-defined, friendly name for the variation (e.g., "Original Homepage", "Variation B - Green Button", "Personalized Offer for New Users"). This name appears in reports and the Convert UI. type: string maxLength: 200 description: description: An optional, more detailed explanation of what this variation entails or what changes it implements compared to the original or other variations. type: string maxLength: 2000 nullable: true is_baseline: type: boolean description: 'If `true`, this variation is considered the baseline (control) against which other variations in the experience are compared for performance. Typically, the "Original" variation is the baseline. Only one variation per experience can be the baseline. Knowledge Base: "What is a Baseline?" ' traffic_distribution: description: 'The percentage of eligible traffic allocated to this specific variation. The sum of `traffic_distribution` for all active variations within an experience should ideally be 100% of the traffic allocated to the experience itself. For Multi-Armed Bandit (MAB) experiences, this value may be dynamically adjusted by the system. Knowledge Base: "What is an Traffic Distribution?" ' type: number minimum: 0 maximum: 100 multipleOf: 0.0001 key: description: 'A unique, machine-readable key or identifier for this variation within the project. Often auto-generated from the name if not specified, but can be user-defined for easier programmatic reference (e.g., in Full Stack SDKs). Example: "control", "treatment_A". ' type: string maxLength: 32 concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' 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' ExpandedExperienceVariationData: allOf: - $ref: '#/components/schemas/ExperienceVariationBaseExtended' - type: object properties: changes: description: An array of changes that this variation would apply. type: array items: oneOf: - type: integer description: Change ID - $ref: '#/components/schemas/ExperienceChange' CollapsedExperienceVariationData: allOf: - type: object properties: id: description: Variation unique ID type: integer - type: object properties: changes: description: An array of changes that this variation would apply. type: array items: oneOf: - type: integer description: Change ID - $ref: '#/components/schemas/ExperienceChange' ExperienceVariation: anyOf: - type: integer description: Variation ID - $ref: '#/components/schemas/CollapsedExperienceVariationData' - $ref: '#/components/schemas/ExpandedExperienceVariationData' ExperienceVariationUpdate: allOf: - type: object properties: id: description: 'Variation unique ID. If not provided, a new variation would be created and connected to the experience **Note:** This is the final list of variations so any item not provided, which was previously connected, would get deleted. ' type: integer - $ref: '#/components/schemas/ExperienceVariationBase' - type: object properties: status: $ref: '#/components/schemas/ExperienceVariationStatuses' - type: object properties: changes: description: 'An array of changes that this variation would apply. If an ID is not provided for a change, a new one would be created and connected to the variation **Note:** This is the final list of changes so any item not provided, which was previously connected, would get deleted. ' type: array items: anyOf: - $ref: '#/components/schemas/ExperienceChangeId' - $ref: '#/components/schemas/ExperienceChangeAdd' - $ref: '#/components/schemas/ExperienceChangeUpdate' ExperienceVariationCreate: allOf: - $ref: '#/components/schemas/ExperienceVariationBase' - type: object required: - name properties: changes: description: 'An array of changes that this variation would apply. ' type: array items: $ref: '#/components/schemas/ExperienceChangeAdd' SimpleExperienceVariation: type: object properties: id: description: The unique numerical identifier of the variation. type: integer name: description: The user-defined, friendly name of the variation. type: string SimpleExperienceVariationExpandable: oneOf: - type: integer description: Variation ID - $ref: '#/components/schemas/SimpleExperienceVariation' 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' UpdateExperienceVariationRequestData: allOf: - $ref: '#/components/schemas/ExperienceVariationBaseExtended' - type: object properties: changes: description: 'An array of changes that this variation would apply. Empty array will remove changes. ' type: array items: anyOf: - $ref: '#/components/schemas/ExperienceChangeId' - $ref: '#/components/schemas/ExperienceChangeAdd' - $ref: '#/components/schemas/ExperienceChangeUpdate' ExperienceVariationIncludeFields: type: string enum: - changes ExperienceVariationExpandFields: type: string enum: - changes ExperiencesListResponseData: type: object description: Response containing a list of experiences within a project, along with pagination details if applicable. properties: data: $ref: '#/components/schemas/ExperiencesList' extra: $ref: '#/components/schemas/Extra' ExperiencesList: type: array description: A list of experience objects. items: $ref: '#/components/schemas/Experience' Experience: allOf: - type: object properties: id: type: integer description: Experience's ID which identify an experience in the system project: $ref: '#/components/schemas/ProjectExpandable' alerts: type: array items: $ref: '#/components/schemas/ExperienceAlert' collaborators: type: array items: $ref: '#/components/schemas/ExperienceCollaborator' audiences: type: array description: The list of audiences for which this experience is supposed to run items: $ref: '#/components/schemas/AudienceExpandable' locations: type: array description: The list of locations on which this experience is supposed to run items: $ref: '#/components/schemas/LocationExpandable' goals: type: array description: The list of goals connected to this experience; experience of type deploy does not have goals attached; items: $ref: '#/components/schemas/GoalExpandable' tags: type: array description: The list of tags connected to this experience items: $ref: '#/components/schemas/TagExpandable' multipage_pages: type: array description: Only for multipage experience type items: $ref: '#/components/schemas/MultipageExperiencePage' customizations: $ref: '#/components/schemas/ExperienceUserCustomizations' stats: description: Experience's condensed statistics(only for experiences that get access to a report) type: object properties: goal_id: description: 'ID of the goal used to calculate the stats. It can be provided in the request or otherwise it defaults to experience''s Primary Goal ' type: integer conversions: description: Number of conversions recorded for after this experience was presented, for the primary goal or the goal given inside the request(if any) type: integer variations_observed_results: description: Results observed for each experience's variation type: array items: type: object properties: variation_id: description: Variation id type: integer improvement: description: Improvement observed over Baseline, as percentage type: number probability_beat_control: description: Calculated probability to beat control. Will be 0 if cannot be calculated yet type: number test_result: description: Result of the statistical test for this variation, compared to the baseline type: string enum: - winner - losing - notConcluded - noChange revenue_per_visitor: description: Calculated revenue per visitor. Applicable for revenue goals, otherwise null. type: number default: null mab_allocation: description: Calculated mab allocation. Applicable for experiences with enabled mab_allocation. type: number default: null visitors: description: Number of unique visitors tracked for this experience type: integer variations: type: array description: 'The list of variations of this experience. **Note:** This is the final list of variations so any variation not provided, which was previously connected, would get deleted. ' items: $ref: '#/components/schemas/ExperienceVariation' status: $ref: '#/components/schemas/ExperienceStatuses' - $ref: '#/components/schemas/ExperienceBase' ExperienceAlert: type: object properties: code: type: string description: A machine-readable code for the alert type. enum: - not_in_project - max_visitors_reached - no_goals_set_up - no_visitors_tracked - no_conversions_tracked - experiments_completed title: type: string description: A short, human-readable title for the alert. description: type: string description: A more detailed explanation of the alert and potential actions to take. ExperienceCollaborator: type: object properties: first_name: type: string description: Collaborator's first name. last_name: type: string nullable: true description: Collaborator's last name. role: type: string description: The collaborator's access role within the project or account (e.g., 'Admin', 'Editor'). user_id: type: string description: The unique identifier for the collaborator user. is_author: type: boolean description: True if this collaborator is the original creator (author) of the experience. ExperienceBase: type: object properties: description: description: An optional, detailed explanation of the experience's purpose, hypothesis, or specific changes being tested. type: string maxLength: 500 start_time: description: 'Unix timestamp (UTC) indicating when the experience was first activated (status changed to ''active''). Null or 0 if the experience has never been started. ' type: integer nullable: true end_time: description: 'Unix timestamp (UTC) indicating when the experience was last stopped (e.g., paused or completed). Null or 0 if the experience is currently active or has never been stopped. ' type: integer nullable: true global_js: description: 'Custom JavaScript code that will be executed for all visitors bucketed into this experience, before any variation-specific code is applied. Useful for setting up common functionalities or variables needed by multiple variations. KB: "Project, Experience, Variation Javascript" - "Global Experience JavaScript". ' type: string global_css: description: 'Custom CSS rules that will be applied for all visitors bucketed into this experience, before any variation-specific CSS. Useful for common styling adjustments needed across all variations. ' type: string name: type: string description: A user-defined, friendly name for the experience (e.g., "Homepage Headline Test", "Checkout Funnel Optimization Q3"). This name is prominent in the Convert UI and reports. maxLength: 100 key: description: 'A unique, machine-readable key or identifier for this experience within the project. Often auto-generated from the name if not specified, but can be user-defined for easier programmatic reference (e.g., in Full Stack SDKs or API calls). Example: "homepage_headline_test_q3". ' type: string maxLength: 32 primary_goal: type: integer description: 'The ID of the main conversion goal this experience is intended to optimize. Performance against this primary goal often determines the "winner" of an A/B test and is highlighted in reports. KB: "Experiment Report" - "Primary Goal". ' objective: type: string nullable: true description: 'A detailed statement outlining the objective of this experience. This often includes the hypothesis being tested, the problem it aims to solve, the proposed solution (the variations), and the expected impact on key metrics. Connects to the "Hypotheses (Compass)" feature. ' maxLength: 5000 settings: $ref: '#/components/schemas/ExperienceSettings' site_area: nullable: true description: '(Deprecated) The legacy way to define on which pages the experience should run, using a set of include/exclude rules based on URL components or page tags. Modern experiences should use the `locations` array instead for more flexible targeting. ' type: object properties: include: type: array items: $ref: '#/components/schemas/RuleElement' exclude: type: array items: $ref: '#/components/schemas/RuleElement' traffic_distribution: description: 'The percentage of total eligible website traffic (matching audience and location criteria) that will be directed into this entire experience. For example, a value of 50 means 50% of eligible visitors will participate, while the other 50% will see the default website content and not be tracked for this experience. The traffic within the experience is then further split among its variations based on `variations[].traffic_distribution`. KB: "What is an Traffic Distribution?". ' type: number minimum: 0 maximum: 100 multipleOf: 0.0001 type: $ref: '#/components/schemas/ExperienceTypes' url: description: 'The primary URL used to load the page in Convert''s Visual Editor when creating or editing this experience''s variations. For Split URL tests, this is typically the URL of the original (control) page. ' type: string format: uri maxLength: 2048 version: description: An internal version number for the experience, incremented upon certain modifications. type: number integrations: type: array description: 'A list of configurations for third-party integrations enabled for this experience (e.g., Google Analytics, Hotjar, Mixpanel). Each object specifies the `provider` and any provider-specific settings (like a GA Custom Dimension index). ' items: anyOf: - $ref: '#/components/schemas/ExperienceIntegrationBaidu' - $ref: '#/components/schemas/ExperienceIntegrationClicktale' - $ref: '#/components/schemas/ExperienceIntegrationClicky' - $ref: '#/components/schemas/ExperienceIntegrationCnzz' - $ref: '#/components/schemas/ExperienceIntegrationCrazyegg' - $ref: '#/components/schemas/ExperienceIntegrationEconda' - $ref: '#/components/schemas/ExperienceIntegrationEulerian' - $ref: '#/components/schemas/ExperienceIntegrationGoogleAnalytics' - $ref: '#/components/schemas/ExperienceIntegrationGosquared' - $ref: '#/components/schemas/ExperienceIntegrationHeapanalytics' - $ref: '#/components/schemas/ExperienceIntegrationHotjar' - $ref: '#/components/schemas/ExperienceIntegrationMicrosoftClarity' - $ref: '#/components/schemas/ExperienceIntegrationMixpanel' - $ref: '#/components/schemas/ExperienceIntegrationMouseflow' - $ref: '#/components/schemas/ExperienceIntegrationPiwik' - $ref: '#/components/schemas/ExperienceIntegrationSegmentio' - $ref: '#/components/schemas/ExperienceIntegrationSitecatalyst' - $ref: '#/components/schemas/ExperienceIntegrationWoopra' - $ref: '#/components/schemas/ExperienceIntegrationYsance' screenshots_info: type: array readOnly: true description: Information about the generation status and timestamps of screenshots for each variation in this experience. Used by the UI. items: type: object description: Screenshot metadata for a single variation. properties: variation_id: type: number description: The ID of the variation. in_progress_since: type: number nullable: true description: Unix timestamp (UTC) if screenshot generation is currently in progress for this variation, null otherwise. last_taken_screenshot_time: type: number nullable: true description: 'Unix timestamp (UTC) of when the latest screenshot for this variation was successfully captured. Null if no screenshot exists or if generation failed. ' environments: type: array deprecated: true description: (Deprecated) List of environment names where this experience will run. Use the singular `environment` field instead. items: type: string environment: type: string description: 'The specific environment (e.g., "production", "staging", "development") within the project where this experience is intended to run. This must match one of the environments defined at the project level. If not set, it typically defaults to the project''s default environment (often "production"). KB: "The Environments Feature". ' concurrency_key: $ref: '#/components/schemas/ConcurrencyKey' CloneExperienceRequestData: description: Parameters for cloning an experience. type: object properties: name: type: string description: (Optional) A new name for the cloned experience. If not provided, the name will be based on the original (e.g., "Copy of [Original Name]"). maxLength: 100 ExperienceReportToken: type: object properties: id: type: integer description: The ID of the experience this token pertains to. token: type: string description: The generated access token string. expiration: type: integer description: Unix timestamp (UTC) indicating when this token will expire and no longer be valid. ExperienceCreateUpdateAudiences: type: array description: A list of Audience IDs to associate with the experience. Visitors must match criteria from these audiences (according to `settings.matching_options.audiences`) to be eligible. items: type: integer ExperienceCreateUpdateLocations: type: array description: A list of Location IDs to associate with the experience. The experience will run on pages/conditions defined by these locations (according to `settings.matching_options.locations`). items: type: integer ExperienceCreateUpdateGoals: type: array description: 'A list of Goal IDs to attach to the experience for conversion tracking. The first goal in this list is often implicitly considered the `primary_goal` unless explicitly set otherwise. Not applicable for ''deploy'' type experiences. ' items: type: integer ExperienceUserCustomizations: type: array description: A list of user-defined key-value pairs for customizing UI elements or behavior related to this experience within the Convert application itself. These do not affect the live experiment seen by visitors. items: $ref: '#/components/schemas/UserCustomization' maxItems: 100 ExperienceCreateUpdatePages: type: object properties: multipage_pages: type: array description: 'An array of page objects, each with an `id` (unique within this experience, e.g., ''p1''), `name`, and `url`. Changes for each of these pages are then defined within the `changes` array of each variation, referencing the `page_id`. When updating, this list replaces all existing pages; pages not in the list will be removed. ' items: $ref: '#/components/schemas/MultipageExperiencePage' CreateExperienceRequestData: description: Request body for creating a new experience. Requires at least `name`, `status`, `type`, and `url`. Other fields like variations, audiences, goals, and settings are highly recommended for a functional setup. required: - name - status - type - url allOf: - $ref: '#/components/schemas/ExperienceBase' - $ref: '#/components/schemas/ExperienceCreateUpdatePages' - type: object properties: status: $ref: '#/components/schemas/ExperienceCreateUpdateStatuses' audiences: $ref: '#/components/schemas/ExperienceCreateUpdateAudiences' locations: $ref: '#/components/schemas/ExperienceCreateUpdateLocations' goals: $ref: '#/components/schemas/ExperienceCreateUpdateGoals' tags: type: array description: The list of tags connected to this experience items: $ref: '#/components/schemas/TagExpandableRequest' customizations: $ref: '#/components/schemas/ExperienceUserCustomizations' variations: type: array description: 'The list of variations of this experience **Note:** This list is final, any variations not passed in the list which were previously connected to the experience will get deleted ' items: $ref: '#/components/schemas/ExperienceVariationCreate' UpdateExperienceRequestData: description: Request body for updating an existing experience. Provide only the fields that need to be changed. The `variations`, `audiences`, `locations`, `goals`, `tags`, and `multipage_pages` arrays, if provided, will replace the existing corresponding lists for the experience. allOf: - $ref: '#/components/schemas/ExperienceBase' - $ref: '#/components/schemas/ExperienceCreateUpdatePages' - type: object properties: status: $ref: '#/components/schemas/ExperienceCreateUpdateStatuses' audiences: $ref: '#/components/schemas/ExperienceCreateUpdateAudiences' locations: $ref: '#/components/schemas/ExperienceCreateUpdateLocations' goals: $ref: '#/components/schemas/ExperienceCreateUpdateGoals' tags: type: array description: The list of tags connected to this experience items: $ref: '#/components/schemas/TagExpandableRequest' customizations: $ref: '#/components/schemas/ExperienceUserCustomizations' variations: type: array description: The list of variations of this experience items: $ref: '#/components/schemas/ExperienceVariationUpdate' BulkExperienceIds: type: array description: A list of unique numerical identifiers for experiences to be affected by a bulk operation. items: type: integer minItems: 1 maxItems: 100 BulkUpdateExperiencesRequestData: type: object description: Request body for bulk updating the status of multiple experiences. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkExperienceIds' status: $ref: '#/components/schemas/BulkExperienceStatuses' required: - id - status BulkDeleteExperiencesRequestData: type: object description: Request body for bulk deleting multiple experiences. Contains a list of experience IDs to be permanently removed. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkExperienceIds' required: - id ExperienceReportTokenRequestData: type: object properties: token_action: type: string enum: - regenerate - delete description: 'The action to perform on the report token. If omitted, the current token (if valid) is returned, or a new one is generated if none exists or the old one expired. ' token_expiration: type: integer minimum: 1 maximum: 48 description: 'The desired expiration time for a new or regenerated token, in hours from the current time. If not provided when generating a token, a default expiration (e.g., 24 hours) is used. ' 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 SE_MabSettings: type: object description: 'Configuration for Multi-Armed Bandit (MAB) traffic allocation. If `null`, MAB is disabled and manual traffic allocation is used. MAB dynamically allocates more traffic to better-performing variations based on the `primary_metric` of the `primary_goal`. KB: "Multi-Armed Bandit (MAB) & Auto-Allocation in Convert". ' properties: strategy: description: 'The MAB algorithm used for dynamic traffic allocation: - `epsilon_greedy`: Mostly exploits the best-known variation, but explores others with a small probability (epsilon). - `ucb`: Upper Confidence Bound, balances exploration and exploitation based on uncertainty and potential. - `thompson_sampling`: (Default) A Bayesian approach that samples from posterior distributions to choose variations. ' type: string enum: - epsilon_greedy - ucb - thompson_sampling default: thompson_sampling exploration_rate: description: 'For `epsilon_greedy` strategy, this is the ''epsilon'' value (0 to 1) representing the probability of choosing a random variation for exploration instead of the current best-performing one. A higher value means more exploration. Default is often 0.1 or 0.3. ' type: number minimum: 0 maximum: 1 enum: - 0 - 0.1 - 0.2 - 0.3 - 0.4 - 0.5 - 0.6 - 0.7 - 0.8 - 0.9 - 1 default: 0.3 SE_ProcSettings: description: Overall settings for the statistical engine processing results for this experience. oneOf: - $ref: '#/components/schemas/SE_ProcSettingsFrequentist' - $ref: '#/components/schemas/SE_ProcSettingsBayesian' discriminator: propertyName: stats_type mapping: frequentist: '#/components/schemas/SE_ProcSettingsFrequentist' bayesian: '#/components/schemas/SE_ProcSettingsBayesian' SE_ProcSettingsBase: type: object properties: stats_type: $ref: '#/components/schemas/SE_ProcTypes' SE_ProcSettingsFrequentist: allOf: - $ref: '#/components/schemas/SE_ProcSettingsBase' - type: object description: Stats Engine Settings needed for the Frequentist processing properties: stats_type: enum: - frequentist confidence: description: Confidence value to be used (in percent) type: number minimum: 50 maximum: 99 multipleOf: 1 power: description: Statistical power value to be used (in percent) type: number minimum: 10 maximum: 99 multipleOf: 1 test_type: description: The type of test applied to the data type: string default: two_tails enum: - one_tail - one_tail_left - one_tail_right - two_tails - sequential multiple_comparison_correction: description: Multiple comparison correction type: string enum: - none - bonferroni - sidak power_calculation_type: description: Power calculation type type: string default: dynamic_mde enum: - dynamic_mde - fixed_mde fixed_mde: description: Fixed minimum detectable effect (corresponding to the relative improvement in percent) type: number minimum: 0 maximum: 10000 mab_settings: allOf: - $ref: '#/components/schemas/SE_MabSettings' nullable: true SE_ProcSettingsBayesian: allOf: - $ref: '#/components/schemas/SE_ProcSettingsBase' - type: object description: Stats Engine Settings needed for the Bayesian processing properties: stats_type: enum: - bayesian decision_threshold: description: Threshold after which a decision can be made type: number minimum: 50 maximum: 99 multipleOf: 1 risk_threshold: description: The maximum acceptable level of potential loss if the chosen variant turns out to be worse than the control. It represents the threshold below which the relative risk of preferring a variant over the control must fall to consider the variant as a strong and relatively safe choice. type: number minimum: 1 maximum: 100 multipleOf: 1 mab_settings: allOf: - $ref: '#/components/schemas/SE_MabSettings' nullable: true ExperienceReportingSettings: type: object description: Comprehensive settings governing how an experience's results are reported and analyzed. properties: primary_metric: description: 'The key performance indicator (KPI) that the statistical engine will primarily use to evaluate variations and determine winners, especially for MAB allocation or automated decisions. - `conversion_rate`: Based on the conversion rate of the primary goal. (Default) - `avg_revenue_visitor`: Based on Revenue Per Visitor (RPV) from a revenue goal. - `avg_products_ordered_visitor`: Based on Average Products Per Visitor (APPV) from a revenue goal. ' default: conversion_rate allOf: - $ref: '#/components/schemas/MetricTypes' stats_engine_processing: $ref: '#/components/schemas/SE_ProcSettings' confidence: description: (Deprecated) Legacy setting for confidence level. Use `stats_engine_processing.confidence` for Frequentist settings instead. deprecated: true type: number minimum: 0 keep_winner: description: 'If true, after an experience is marked as ''Completed'' because a winning variation was found, that winning variation will continue to receive 100% of the experience traffic. If false (default), traffic might revert to the original or be evenly split, or the experience might simply stop serving. KB: "My Experiments Stopped, What Happened?" - "An experiment can keep winning variation running". ' type: boolean min_order_value: description: (Deprecated) Minimum order value for transaction outliers. Use `outliers.order_value.min` instead. type: number minimum: 0 deprecated: true max_order_value: description: (Deprecated) Maximum order value for transaction outliers. Use `outliers.order_value.max` instead. type: number deprecated: true minimum: 0 outliers: description: 'Configuration for handling statistical outliers in order-related data (revenue and product counts) to prevent skewed results. KB: "Setting limits for Order Outliers" and "How Outlier Detection Works in Convert Reports and Exports". ' type: object additionalProperties: false properties: order_value: description: Outlier detection settings for the monetary value of orders. allOf: - $ref: '#/components/schemas/NumericOutlier' products_ordered_count: description: Outlier detection settings for the number of products in an order. allOf: - $ref: '#/components/schemas/NumericOutlier' max_running_time: description: 'The maximum number of days the experience should run. If no clear winner is found by this time, the experience may be automatically completed or paused. Set to 0 for no maximum limit. KB: "Setting an end date for running an experiment." (Mentions max days in Stats section). ' type: integer minimum: 0 maximum: 999 max_variation_visitors: description: (Deprecated) Maximum number of visitors per variation. Use `max_experience_visitors` or rely on statistical significance. deprecated: true type: integer minimum: 0 max_experience_visitors: description: The maximum total number of unique visitors to be included in the entire experience. Once reached, the experience may be automatically paused or completed. Set to 0 for no limit. type: integer minimum: 0 min_variation_conversions: type: integer minimum: 0 description: 'The minimum number of conversions a variation must achieve before its statistical significance (confidence/chance to win) is calculated and displayed in reports. Default is often 5. Helps avoid premature conclusions based on very small conversion numbers. KB: "Experiment Report" - "Confidence Level (statistical significance)". ' min_conversion_value: description: (Deprecated or unclear) Minimum conversion value per variation. Might relate to revenue goals or be a legacy setting. type: integer minimum: 0 deprecated: true min_running_time: description: 'The minimum number of days the experience must run before it can be automatically completed, even if a winner is found earlier. Helps ensure stability and account for weekly variations. Set to 0 for no minimum. KB: "My Experiments Stopped, What Happened?". ' type: integer minimum: 0 maximum: 999 min_variation_visitors: description: 'The minimum number of unique visitors each variation (including the original) must receive before statistical significance is calculated. Helps ensure a sufficient sample size for reliable results. ' type: integer minimum: 0 stop_loser: description: 'If true, variations that are statistically determined to be performing significantly worse than the baseline (losing variations) will be automatically stopped. Their traffic is then redistributed among the remaining active variations. KB: "My Experiments Stopped, What Happened?" - "An experiment can stop losing variations". ' type: boolean keep_running_until_confidence: type: boolean description: 'If true, the experiment does not auto-complete when planned sample size (100% progress) is reached alone. It only auto-completes when both planned sample size is reached and the confidence threshold is met. If false, the experiment completes 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. ' srm_check: type: boolean nullable: true description: 'If true, enables Sample Ratio Mismatch (SRM) checks for the experience. SRM occurs when the distribution of visitors to variations significantly deviates from the intended traffic allocation, potentially indicating a problem with the experiment setup. If not provided at experience level, project-level setting is used. KB: "What is SRM?". ' visual_editor: description: Settings related to the behavior and configuration of Convert's Visual Editor when used for this experience. type: object properties: selector_blacklist: description: 'A list of keywords (newline-separated string). If an element''s attribute (class, ID) contains any of these keywords, that attribute part will be ignored when Convert generates CSS selectors for changes. Useful for avoiding dynamic or unstable selectors (e.g., from Squarespace, Bootstrap). KB: "My changes created on the Visual Editor don''t get saved when using Squarespace", "Issues while editing websites on Bootstrap". ' type: string nullable: true screen_width: description: The emulated screen width (in pixels) used when loading the page in the Visual Editor. Allows previewing and editing for different responsive views. type: number minimum: 240 maximum: 7680 nullable: true user_agent: $ref: '#/components/schemas/VisualEditorUserAgents' VisualEditorUserAgents: description: Predefined User-Agent strings that the Visual Editor can emulate for responsive design and device-specific testing. type: string nullable: true enum: - chrome_desktop - chrome_ipad - chrome_iphone - chrome_android - safari_mac - safari_ipad - safari_iphone - firefox_desktop - firefox_ipad - firefox_iphone - firefox_android - edge_desktop - edge_tablet - brave_desktop - brave_ipad - brave_iphone - brave_android - opera_desktop - opera_ipad - opera_iphone - opera_android ExperienceSettings: allOf: - type: object description: Experience's settings list properties: split_url_settings: type: object description: A couple of settings only applicable to Split URL experiments properties: split_regex_support: type: boolean description: 'Whether regular expressions are supported in original/variation URLs of a split URL experiment or not. It only applies to **experience_type** - **split_url** ' split_add_query_params: type: boolean description: 'Whether original/variation urls have incorporated or not the needed regular expression to copy query string parameters from one to the other in the redirect process. It only applies to **experience_type** - **split_url** and it''s only used internally in Convert''s app ' split_query_params_hide_regex: type: boolean description: 'Whether the user selected to hide or not the part of the regular expression automatically added by enabling **split_add_query_params**. It only applies to **experience_type** - **split_url** and it''s only used internally in Convert''s app ' matching_options: type: object description: Various settings used for matching the list of Audiences and Locations properties: audiences: $ref: '#/components/schemas/GenericListMatchingOptions' locations: $ref: '#/components/schemas/GenericListMatchingOptions' visitor_insights: type: object readOnly: true description: 'Visitor Insights (Signals) settings for this experience. Heatmap IDs are stored here when heatmaps are created for the experience''s variations. ' nullable: true properties: heatmaps: type: object readOnly: true description: Map of variation ID to heatmap ID. Populated when heatmaps are created for this experience (one heatmap per variation). additionalProperties: type: string description: Heatmap ID for the variation. nullable: true example: '1003100122': 507f1f77bcf86cd799439012 - $ref: '#/components/schemas/ExperienceReportingSettings' MultipageExperiencePage: description: Defines a single page within a 'multipage' (funnel) experience. allOf: - type: object properties: id: description: The ID of the page. type: string minLength: 1 maxLength: 2 pattern: ^[0-9a-z]{1,2}$ name: description: Name of the page type: string maxLength: 200 url: description: The url of page to load type: string maxLength: 2048 additionalProperties: false ConvertibleExperienceTypes: type: string enum: - a/b - deploy ExperienceTypes: type: string description: 'The type of optimization activity: - `a/b`: Standard A/B test comparing an original page/element against one or more variations. Changes made via Visual Editor or code. KB: "What is an Experiment?". - `a/a`: Tests the original page against an identical copy of itself to validate tracking setup and ensure no inherent bias. KB: "A/A Experiments". - `mvt`: Multivariate test, testing combinations of changes across multiple sections of a page. KB: "Creating a Multivariate Experiment". - `split_url`: Redirects traffic between different URLs to test entirely different page versions. KB: "How do Split URL Experiments work?". - `multipage`: Tests a consistent set of changes across a sequence of pages (funnel). KB: "Create Multipage Experiences". - `deploy`: Rolls out a specific set of changes to a targeted audience without A/B comparison reporting. KB: "What about Deployments?". - `a/b_fullstack`: An A/B test conducted using a Full Stack SDK, potentially involving server-side changes. KB: "Full Stack Experiments on Convert". - `feature_rollout`: A Full Stack experience for gradually rolling out a new feature, often using feature flags. ' enum: - a/b - a/a - mvt - split_url - multipage - deploy - a/b_fullstack - feature_rollout BulkExperienceStatuses: type: string enum: - active - paused - archived ExperienceStatuses: type: string enum: - draft - active - paused - completed - scheduled - archived - deleted ExperienceCreateUpdateStatuses: type: string description: 'The set of statuses a caller may set when creating or updating an experience. ' enum: - draft - active - paused - completed - scheduled - archived ExperienceHistoryObjects: type: string enum: - report - variation - change ExperienceIncludeFields: type: string enum: - alerts - goals - stats - variations - variations.changes - min_running_timestamp - max_running_timestamp - audiences - locations - collaborators ExperienceExpandFields: type: string enum: - project - audiences - goals - locations - variations - variations.changes - tags SimpleExperienceFlat: type: object properties: id: description: The unique numerical identifier of the experience. type: integer variation: $ref: '#/components/schemas/SimpleExperienceVariationExpandable' SimpleExperience: allOf: - $ref: '#/components/schemas/SimpleExperienceFlat' - type: object properties: name: description: Experience name type: string required: - name SimpleExperienceExpandable: description: Represents an experience in a simplified form, either as its ID and a variation context, or including its name. oneOf: - $ref: '#/components/schemas/SimpleExperienceFlat' - $ref: '#/components/schemas/SimpleExperience' ExperienceId: type: integer description: The unique numerical identifier for an experience. BaseSimpleExperience: type: object properties: id: $ref: '#/components/schemas/ExperienceId' name: description: The user-defined, friendly name of the experience. type: string BaseExperienceExpandable: description: Represents an experience, either as its unique ID or as a simple object with its ID and name. Used when an experience is referenced by another entity and can be optionally expanded. oneOf: - $ref: '#/components/schemas/ExperienceId' - $ref: '#/components/schemas/BaseSimpleExperience' GetExperiencesListRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/ExperiencesListFilteringOptions' - $ref: '#/components/schemas/PageNumber' - type: object properties: include: description: 'Specifies the list of fields to be included in the response, which otherwise would be not sent. Read more in the section related to [Optional Fields](#tag/Optional-Fields) ' type: array items: $ref: '#/components/schemas/ExperienceIncludeFields' expand: description: 'Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields)' type: array items: $ref: '#/components/schemas/ExperienceExpandFields' only: description: 'Only retrieve experiences with the given ids. ' type: array nullable: true items: type: integer maxItems: 100 except: description: 'Except experiences with the given ids. ' type: array items: type: integer maxItems: 100 ExperiencesListFilteringOptions: type: object allOf: - $ref: '#/components/schemas/ResultsPerPage' - $ref: '#/components/schemas/SortDirection' - type: object properties: goal_id: type: integer nullable: true description: 'Goal ID to be used for fetching experience''s stats. Only applicable for the experiences that have access to a report. Defaults to primary experience''s goal if none given. ' sort_by: type: string nullable: true default: id description: 'A value used to sort experiences by specific field Defaults to **id** if not provided ' enum: - id - conversions - improvement - name - start_time - end_time - status - primary_goal - key - environment search: type: string maxLength: 200 nullable: true description: A search string that would be used to search against Experience's name and description status: type: array nullable: true description: The status of the experiences to be returned; either of the below can be provided items: $ref: '#/components/schemas/ExperienceStatuses' type: type: array nullable: true description: The type of the experiences to be returned; either of the below can be provided items: $ref: '#/components/schemas/ExperienceTypes' tags: type: array nullable: true description: The list of tag ID's used to filter the list of returned experiences items: type: integer audiences: type: array nullable: true description: The list of audience ID's used to filter the list of returned experiences items: type: integer goals: type: array nullable: true description: The list of goal ID's used to filter the list of returned experiences items: type: integer features: type: array nullable: true description: The list of feature ID's used to filter the list of returned experiences items: type: integer hypotheses: type: array nullable: true description: The list of hypotheses ID's used to filter the list of returned experiences items: type: integer locations: type: array nullable: true description: The list of location ID's used to filter the list of returned experiences items: type: integer environments: type: array nullable: true description: The list of environments used to filter the list of returned experiences items: type: string ExperiencesListPersistentOptions: allOf: - $ref: '#/components/schemas/ExperiencesListFilteringOptions' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/ExperiencesListColumnNames' ExperiencesListColumnNames: type: string description: Available columns for the experiences list in the UI. enum: - name - id - improvement - conversions - primary_goal - start_time - end_time - status - key - environment - running_days - traffic_allocation - revenue_per_visitor GetExperienceLiveDataRequestData: allOf: - $ref: '#/components/schemas/ExperienceLiveDataFilteringOptions' - $ref: '#/components/schemas/LiveDataExpandParameter' ExperienceLiveDataFilteringOptions: type: object description: Filters for the live data feed of a single experience. properties: event_types: type: array nullable: true items: $ref: '#/components/schemas/LiveDataEventTypes' goals: type: array nullable: true description: A list of Goal IDs to filter conversion/transaction events for. maxItems: 20 items: type: integer segments: nullable: true allOf: - $ref: '#/components/schemas/ReportingSegmentsFilters' ExperienceLiveDataPersistentOptions: allOf: - $ref: '#/components/schemas/ExperienceLiveDataFilteringOptions' - $ref: '#/components/schemas/LiveDataAutoRefreshSettings' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/ExperienceLiveDataColumnNames' ExperienceLiveDataColumnNames: type: string description: Available columns for the experience-level live data feed in the UI. enum: - time - event - variation - more_info GetExperienceHistoryRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/ExperienceHistoryFilteringOptions' - $ref: '#/components/schemas/PageNumber' TriggerExperienceScreenshotsRequestData: type: object description: Parameters for triggering screenshot generation for an experience's variations. properties: variations: description: 'An optional list of specific variation IDs for which to generate/regenerate screenshots. If omitted, screenshots are triggered for all variations within the experience. ' type: array items: type: number force_regenerate: description: 'If set to true, screenshots are triggered for all variations within the experience, regardless of whether they have a manual screenshot uploaded. If omitted, screenshots are triggered only for variations that do not have a manual screenshot uploaded. ' type: boolean ExperienceHistoryFilteringOptions: allOf: - type: object description: Filter Single Experience history list. properties: methods: type: array nullable: true items: $ref: '#/components/schemas/ChangeHistoryMethods' objects: type: array nullable: true items: $ref: '#/components/schemas/ExperienceHistoryObjects' sort_by: type: string nullable: true default: timestamp description: "A value to sort history list by specific field(s)\n\n Defaults to **timestamp** if not provided\n" enum: - timestamp - event - object variations: description: List of variations ids type: array nullable: true items: type: number maxItems: 100 changes: description: List of changes ids type: array nullable: true items: type: number maxItems: 100 author_id: type: string nullable: true description: The id of the author who made changes - $ref: '#/components/schemas/ChangeHistoryExpandParameter' - $ref: '#/components/schemas/ResultsPerPage' - $ref: '#/components/schemas/SortDirection' ExperienceHistoryPersistentOptions: allOf: - $ref: '#/components/schemas/ExperienceHistoryFilteringOptions' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/ExperienceHistoryColumnNames' ExperienceHistoryColumnNames: type: string description: Available columns for the experience change history log in the UI. enum: - timestamp - event - object - object_id - method - more_info ExperienceReportFirstViewPersistentOptions: allOf: - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/ExperienceReportFirstViewColumnNames' ExperienceReportFirstViewColumnNames: type: string description: Available columns for the goals-by-variations view in the experience report UI. enum: - goal_name - best_improvement - conversions - visitors - conversion_rate - confidence ExperienceReportSecondViewPersistentOptions: allOf: - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/ExperienceReportSecondViewColumnNames' ExperienceReportSecondViewColumnNames: type: string description: Available columns for the variations-by-goals view in the experience report UI. enum: - variation_name - improvement - conversions - visitors - conversion_rate - confidence - confidence_interval - observed_power - status - expected - risk - traffic - average_order_value - average_products_per_order HeatmapDevices: type: string enum: - desktop - tablet - mobile default: desktop description: Device type for the heatmap image. HeatmapInteractions: type: string enum: - click - scroll - move default: click description: Interaction type for the heatmap overlay. GetExperienceHeatmapBackgroundRequestData: type: object description: Optional filters for the heatmap background image. properties: device: $ref: '#/components/schemas/HeatmapDevices' GetExperienceHeatmapOverlayRequestData: type: object description: Optional filters for the heatmap overlay (interaction) image. properties: device: $ref: '#/components/schemas/HeatmapDevices' interaction: $ref: '#/components/schemas/HeatmapInteractions' ExperienceHeatmapBackgroundResponseData: type: object description: Response for POST heatmap background by heatmap id. properties: data: type: object properties: heatmap_id: type: string device: $ref: '#/components/schemas/HeatmapDevices' background: type: string format: byte nullable: true description: Base64-encoded background image. Null when available is false. ExperienceHeatmapOverlayResponseData: type: object description: Response for POST heatmap overlay by heatmap id. properties: data: type: object properties: heatmap_id: type: string device: $ref: '#/components/schemas/HeatmapDevices' interaction: $ref: '#/components/schemas/HeatmapInteractions' overlay: type: string format: byte nullable: true description: Base64-encoded overlay image. Null when available is false. FeaturesListResponseData: type: object description: Response containing a list of features defined within a Full Stack project, along with pagination details if applicable. properties: data: $ref: '#/components/schemas/FeaturesList' extra: $ref: '#/components/schemas/Extra' FeaturesList: type: array description: A list of feature objects. items: $ref: '#/components/schemas/Feature' Feature: type: object description: 'Represents a feature flag or a set of configurable variables within a Full Stack project. Features are used in ''a/b_fullstack'' or ''feature_rollout'' experiences to control application behavior or content dynamically, often from the server-side or within client-side applications using an SDK. Each feature has a unique `key` for programmatic access and a list of `variables` whose values can be altered per experience variation. Knowledge Base: "Full Stack Experiments on Convert". ' properties: id: description: The unique numerical identifier for the feature. type: integer readOnly: true name: description: A user-defined, friendly name for the feature (e.g., "New Checkout Process", "Beta User Dashboard"). This name appears in the Convert UI. type: string maxLength: 100 status: $ref: '#/components/schemas/FeatureStatuses' key: description: 'A unique, machine-readable string key for this feature (e.g., "new_checkout_flow", "beta_dashboard_enabled"). This key is used by the SDKs to identify and retrieve the feature''s configuration and variable values. It''s typically auto-generated from the name if not specified, but can be user-defined. ' type: string maxLength: 32 stats: $ref: '#/components/schemas/FeatureStats' description: description: An optional, more detailed explanation of the feature's purpose, what it controls, or its intended use cases. type: string maxLength: 200 variables: type: array description: 'An array of `FeatureVariable` objects that define the configurable parameters associated with this feature. For example, a feature "Button Customization" might have variables like "buttonColor" (string), "buttonText" (string), and "isEnabled" (boolean). The values of these variables can be different for each variation of an experience that uses this feature. ' items: $ref: '#/components/schemas/FeatureVariable' FeatureStats: type: object readOnly: true properties: times_used: type: integer description: The number of currently active experiences (e.g., 'a/b_fullstack', 'feature_rollout') that are using this feature to control variations. FeatureVariableBase: type: object description: Base properties for a variable within a feature. Each variable has a key, a type, and a default value. properties: key: type: string description: 'A unique, machine-readable string key for this variable within the feature (e.g., "buttonColor", "discountPercentage", "showHeader"). This key is used by SDKs to retrieve the variable''s value for the active variation. ' maxLength: 32 type: type: string description: 'The data type of the variable. This determines the kind of values it can hold and how it''s treated by the SDKs. - `json`: A JSON object or array. - `string`: A text string. - `boolean`: A true/false value. - `float`: A floating-point number. - `integer`: A whole number. ' default_value: description: 'The default value for this variable. This value is used if the feature is not part of an active experiment for a user, or if no specific value is set for the variation a user is bucketed into. The type of `default_value` must match the specified `type` of the variable. ' nullable: true required: - key - type FeatureVariableString: allOf: - $ref: '#/components/schemas/FeatureVariableBase' - type: object properties: type: enum: - json - string default_value: type: string nullable: true FeatureVariableBool: allOf: - $ref: '#/components/schemas/FeatureVariableBase' - type: object properties: type: enum: - boolean default_value: type: boolean nullable: true FeatureVariableNumeric: allOf: - $ref: '#/components/schemas/FeatureVariableBase' - type: object properties: type: enum: - float - integer default_value: type: number nullable: true FeatureVariable: oneOf: - $ref: '#/components/schemas/FeatureVariableString' - $ref: '#/components/schemas/FeatureVariableBool' - $ref: '#/components/schemas/FeatureVariableNumeric' discriminator: propertyName: type mapping: boolean: '#/components/schemas/FeatureVariableBool' float: '#/components/schemas/FeatureVariableNumeric' json: '#/components/schemas/FeatureVariableString' integer: '#/components/schemas/FeatureVariableNumeric' string: '#/components/schemas/FeatureVariableString' CreateFeatureRequestData: allOf: - $ref: '#/components/schemas/Feature' required: - name - variables UpdateFeatureRequestData: allOf: - type: object properties: id: description: Feature ID type: integer - $ref: '#/components/schemas/Feature' GetFeaturesListRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/FeaturesListFilteringOptions' - $ref: '#/components/schemas/PageNumber' - type: object properties: include: description: Specifies the list of fields to be included in the response, which otherwise would not be sent. type: array items: $ref: '#/components/schemas/FeatureOptionalFields' FeatureOptionalFields: type: string enum: - stats FeaturesListFilteringOptions: allOf: - $ref: '#/components/schemas/ResultsPerPage' - $ref: '#/components/schemas/SortDirection' - type: object properties: search: type: string maxLength: 100 description: A search string that would be used to search against Feature's id, name, key and description nullable: true only: description: 'Only retrieve features with the given ids. ' type: array nullable: true items: type: integer maxItems: 100 except: description: 'Except features with the given ids. ' type: array items: type: integer maxItems: 100 sort_by: type: string description: 'A value to sort features by specific field Defaults to **id** if not provided ' enum: - id - name - key - status nullable: true default: id FeaturesListPersistentOptions: allOf: - $ref: '#/components/schemas/FeaturesListFilteringOptions' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/FeaturesListColumnNames' FeaturesListColumnNames: type: string description: Available columns for the features list in the UI. enum: - name - id - key - status FeatureStatuses: type: string description: 'The current status of a feature: - `active`: The feature is active and can be used in Full Stack experiments. Its variables can be controlled by experiences. - `archived`: The feature is archived and no longer available for new experiments. Existing experiments using it might behave based on last known configuration or default values. ' enum: - active - archived default: active BulkFeaturesIds: type: array description: A list of feature unique numerical identifiers to be affected by a bulk operation. items: type: integer minItems: 1 maxItems: 100 BulkUpdateFeatureRequestData: type: object description: Request body for bulk updating the status of multiple features. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkFeaturesIds' status: $ref: '#/components/schemas/FeatureStatuses' required: - id - status BulkDeleteFeatureRequestData: type: object description: Request body for bulk deleting multiple features. Contains a list of feature IDs to be permanently removed. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkFeaturesIds' required: - id FileBase: type: object description: Base properties common to an uploaded file in Convert's storage. properties: url: description: The direct URL from which this file can be accessed or downloaded. This URL points to Convert's file storage. type: string example: https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/files/{fileKey} key: description: 'The unique storage key (often including the filename and a unique prefix/suffix) for this file within Convert''s system. This key is used to retrieve or delete the file. ' type: string example: example_file_1234567890.jpg file_name: description: The original filename of the uploaded file, as provided by the user during upload (e.g., "annual_report.pdf", "user_avatar.png"). type: string example: example.jpg file_size: description: The size of the file in bytes. type: integer example: 474702 mime_type: description: The MIME type of the file (e.g., "application/pdf", "image/jpeg", "text/csv"), indicating its format. type: string example: image/jpeg status: description: Indicates the status of the file, primarily relevant during or immediately after an upload operation. type: string enum: - success - error message: description: A message related to the file's status, providing more details in case of an error during upload. type: string UploadedFile: allOf: - $ref: '#/components/schemas/FileBase' - type: object description: File Object in upload response with additional status fields properties: status: description: Status of the file upload operation type: string enum: - success - error message: description: Message related to the file upload status type: string UploadFileRequestData: type: object description: 'Request body for uploading a generic file. Uses multipart/form-data. Supported file types include PDF, DOC(X), XLS(X), PPT(X), TXT, CSV, and common image formats (JPG, PNG, GIF, WEBP, SVG). Maximum file size is 5MB. ' properties: file_name: description: The desired name for the file as it will be stored and identified in Convert (e.g., "campaign_brief.pdf", "logo_variation.svg"). Include the file extension. type: string maxLength: 200 file: description: 'The actual binary file content to be uploaded. Constraints: - Maximum file size: 5MB. - Supported types: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, CSV, JPG, JPEG, BMP, GIF, PNG, WEBP, SVG. ' type: string format: binary required: - file_name - file FileData: allOf: - $ref: '#/components/schemas/FileBase' - type: object description: File content object with base64 encoded data properties: content: description: Base64 encoded content of the file type: string example: JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoKPDwgL0xlbg... GoalsListResponseData: type: object description: Response containing a list of conversion goals defined within a project, along with pagination details if applicable. properties: data: $ref: '#/components/schemas/GoalsList' extra: $ref: '#/components/schemas/Extra' GoalsList: type: array description: A list of goal objects. items: $ref: '#/components/schemas/Goal' GoalTypes: type: string description: 'The type of user action or event that this goal tracks as a conversion. - `advanced`: A goal defined by a complex set of custom rules using the Advanced Goal Editor (now represented by `triggering_rule`). - `visits_page`: Tracks a conversion when a visitor views a specific page or set of pages matching URL criteria. KB: "Goals" - "Visit a specific page". - `revenue`: Tracks e-commerce transactions, capturing revenue amount and product count. Can be manual or GA-integrated. KB: "Add Revenue Tracking to Your Site". - `clicks_link`: Tracks clicks on specific hyperlinks ( tags) based on the link''s URL (`href` attribute). KB: "Goals" - "Click on a link". - `submits_form`: Tracks submissions of HTML forms based on the form''s `action` URL. KB: "Goals" - "Submit a form". - `clicks_element`: Tracks clicks on any HTML element identified by a CSS selector. KB: "Goals" - "Clicks something on a page". - `dom_interaction`: (Newer type) Tracks various DOM events on specified elements (e.g., clicks, hovers, changes). More flexible than `clicks_element`. - `scroll_percentage`: Tracks when a visitor scrolls to a certain percentage depth of a page (e.g., 25%, 50%, 75%, 100%). KB: "Measuring Page Scroll in Convert Experiences". - `ga_import`: A goal imported from Google Analytics (Universal Analytics or GA4). Its triggering logic is based on the corresponding GA event/goal. KB: "How do I Import Goals from Google Analytics?". - `code_trigger`: A goal that is triggered exclusively via a JavaScript call (`_conv_q.push(["triggerConversion", "GOAL_ID"])`). KB: "Custom Prebuilt Goals" - "Create a JS Goal". ' enum: - advanced - visits_page - revenue - clicks_link - submits_form - clicks_element - dom_interaction - scroll_percentage - ga_import - code_trigger GoalBase: type: object description: Base properties common to all types of conversion goals. properties: id: description: The unique numerical identifier for the goal. readOnly: true type: integer name: description: A user-defined, friendly name for the goal (e.g., "Completed Purchase", "Newsletter Signup", "Viewed Pricing Page"). This name appears in reports and when selecting goals for experiences. type: string maxLength: 100 key: description: 'A unique, machine-readable string key for this goal within the project. Often auto-generated from the name if not specified, but can be user-defined for easier programmatic reference. Example: "completed_purchase_main_flow". ' type: string maxLength: 32 description: description: An optional, more detailed explanation of what this goal measures or its significance to business objectives. type: string maxLength: 500 is_system: type: boolean readOnly: true description: Indicates if this is a system-defined default goal (e.g., "Decrease Bounce Rate", "Increase Engagement"). System goals cannot be deleted but their usage can be controlled. stats: $ref: '#/components/schemas/GoalStats' triggering_rule: nullable: true allOf: - $ref: '#/components/schemas/RuleObject' selected_default: type: boolean description: If true, this goal will be automatically pre-selected when creating new experiences within the project. Useful for commonly tracked primary conversions. status: $ref: '#/components/schemas/GoalStatuses' GoalStatuses: type: string description: 'The current status of a goal: - `active`: The goal is active and will track conversions for experiences it''s attached to. - `archived`: The goal is archived and will not track new conversions. Its historical data remains accessible in reports for experiences that previously used it. Archived goals can often be cloned or unarchived. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences." ' enum: - active - archived Goal: oneOf: - $ref: '#/components/schemas/DomInteractionGoal' - $ref: '#/components/schemas/ScrollPercentageGoal' - $ref: '#/components/schemas/RevenueGoal' - $ref: '#/components/schemas/SubmitsFormGoal' - $ref: '#/components/schemas/ClicksLinkGoal' - $ref: '#/components/schemas/ClicksElementGoal' - $ref: '#/components/schemas/AdvancedGoal' - $ref: '#/components/schemas/NoSettingsGoal' - $ref: '#/components/schemas/GaGoal' discriminator: propertyName: type mapping: advanced: '#/components/schemas/AdvancedGoal' visits_page: '#/components/schemas/NoSettingsGoal' revenue: '#/components/schemas/RevenueGoal' clicks_link: '#/components/schemas/ClicksLinkGoal' submits_form: '#/components/schemas/SubmitsFormGoal' clicks_element: '#/components/schemas/ClicksElementGoal' dom_interaction: '#/components/schemas/DomInteractionGoal' scroll_percentage: '#/components/schemas/ScrollPercentageGoal' ga_import: '#/components/schemas/GaGoal' code_trigger: '#/components/schemas/NoSettingsGoal' CreateGoal: oneOf: - $ref: '#/components/schemas/CreateDomInteractionGoal' - $ref: '#/components/schemas/CreateScrollPercentageGoal' - $ref: '#/components/schemas/CreateRevenueGoal' - $ref: '#/components/schemas/CreateSubmitsFormGoal' - $ref: '#/components/schemas/CreateClicksLinkGoal' - $ref: '#/components/schemas/CreateClicksElementGoal' - $ref: '#/components/schemas/CreateAdvancedGoal' - $ref: '#/components/schemas/CreateNoSettingsGoal' - $ref: '#/components/schemas/CreateGaGoal' discriminator: propertyName: type mapping: advanced: '#/components/schemas/CreateAdvancedGoal' visits_page: '#/components/schemas/CreateNoSettingsGoal' revenue: '#/components/schemas/CreateRevenueGoal' clicks_link: '#/components/schemas/CreateClicksLinkGoal' submits_form: '#/components/schemas/CreateSubmitsFormGoal' clicks_element: '#/components/schemas/CreateClicksElementGoal' dom_interaction: '#/components/schemas/CreateDomInteractionGoal' scroll_percentage: '#/components/schemas/CreateScrollPercentageGoal' ga_import: '#/components/schemas/CreateGaGoal' code_trigger: '#/components/schemas/CreateNoSettingsGoal' GoalExpandable: oneOf: - type: integer description: Goal ID - $ref: '#/components/schemas/Goal' DomInteractionGoal: allOf: - $ref: '#/components/schemas/GoalBase' - type: object properties: type: enum: - dom_interaction settings: $ref: '#/components/schemas/DomInteractionGoalSettings' CreateDomInteractionGoal: allOf: - $ref: '#/components/schemas/DomInteractionGoal' required: - name - type - settings ScrollPercentageGoal: allOf: - $ref: '#/components/schemas/GoalBase' - type: object properties: type: enum: - scroll_percentage settings: $ref: '#/components/schemas/ScrollPercentageGoalSettings' CreateScrollPercentageGoal: allOf: - $ref: '#/components/schemas/ScrollPercentageGoal' required: - name - type - settings RevenueGoal: allOf: - $ref: '#/components/schemas/GoalBase' - type: object properties: type: enum: - revenue settings: $ref: '#/components/schemas/RevenueGoalSettings' CreateRevenueGoal: allOf: - $ref: '#/components/schemas/RevenueGoal' required: - name - type - settings SubmitsFormGoal: allOf: - $ref: '#/components/schemas/GoalBase' - type: object properties: type: enum: - submits_form settings: $ref: '#/components/schemas/SubmitsFormGoalSettings' CreateSubmitsFormGoal: allOf: - $ref: '#/components/schemas/SubmitsFormGoal' required: - name - type - settings ClicksLinkGoal: allOf: - $ref: '#/components/schemas/GoalBase' - type: object properties: type: enum: - clicks_link settings: $ref: '#/components/schemas/ClicksLinkGoalSettings' CreateClicksLinkGoal: allOf: - $ref: '#/components/schemas/ClicksLinkGoal' required: - name - type - settings ClicksElementGoal: allOf: - $ref: '#/components/schemas/GoalBase' - type: object properties: type: enum: - clicks_element settings: $ref: '#/components/schemas/ClicksElementGoalSettings' CreateClicksElementGoal: allOf: - $ref: '#/components/schemas/ClicksElementGoal' required: - name - type - settings GaGoal: allOf: - $ref: '#/components/schemas/GoalBase' - type: object properties: type: enum: - ga_import settings: $ref: '#/components/schemas/GaGoalSettings' CreateGaGoal: allOf: - $ref: '#/components/schemas/GaGoal' required: - name - type AdvancedGoal: allOf: - $ref: '#/components/schemas/GoalBase' - type: object properties: type: enum: - advanced CreateAdvancedGoal: allOf: - $ref: '#/components/schemas/AdvancedGoal' required: - triggering_rule - name - type NoSettingsGoal: allOf: - $ref: '#/components/schemas/GoalBase' - type: object properties: type: enum: - visits_page - code_trigger CreateNoSettingsGoal: allOf: - $ref: '#/components/schemas/NoSettingsGoal' required: - name - type DomInteractionGoalSettings: type: object additionalProperties: false properties: tracked_items: type: array description: An array defining one or more DOM elements and the interaction events on them that should trigger this goal. items: type: object description: Defines a single DOM element and event to track. properties: selector: type: string description: A CSS selector that identifies the HTML element(s) to monitor for interactions (e.g., "#submitButton", ".product-image"). event: type: string description: The specific DOM event to listen for on the selected element(s) (e.g., "click", "mouseover", "change", "focus"). required: - tracked_items ScrollPercentageGoalSettings: type: object additionalProperties: false properties: percentage: type: number description: The scroll depth percentage (e.g., 25, 50, 75, 100) that a visitor must reach on a page for this goal to trigger. The page(s) are defined in the goal's `triggering_rule`. required: - percentage GaGoalSettings: type: object additionalProperties: false properties: ga_event: description: The name of the event in Google Analytics (GA4) or the Goal configuration in Universal Analytics that this Convert goal corresponds to. When this GA event/goal occurs, the Convert goal is triggered. type: string RevenueGoalSettings: type: object additionalProperties: false properties: triggering_type: type: string description: 'How this revenue goal is triggered: - `manual`: The goal is triggered by a specific JavaScript call (`_conv_q.push(["pushRevenue", ...])`) on the purchase confirmation page, which includes revenue amount and product count. The `triggering_rule` should be empty or not set. - `ga`: Convert attempts to automatically capture revenue data from a standard Google Analytics E-commerce tracking implementation when the `triggering_rule` (e.g., matching the confirmation page URL) is met. ' enum: - manual - ga required: - triggering_type SubmitsFormGoalSettings: type: object additionalProperties: false properties: action: type: string description: 'The URL specified in the `action` attribute of the HTML form(s) to be tracked. When a form submitting to this URL is successfully submitted, the goal triggers. The page(s) where the form resides are defined in the goal''s `triggering_rule`. ' required: - action ClicksLinkGoalSettings: type: object additionalProperties: false properties: href: type: string description: 'The exact URL (or a pattern if regex is supported by the `triggering_rule`''s match type for this setting) found in the `href` attribute of the hyperlink(s) to be tracked. When a link with this `href` is clicked, the goal triggers. The page(s) where the link resides are defined in the goal''s `triggering_rule`. ' required: - href ClicksElementGoalSettings: type: object additionalProperties: false properties: selector: type: string description: 'A CSS selector that identifies the HTML element(s) to be tracked. When any element matching this selector is clicked, the goal triggers. The page(s) where the element(s) reside are defined in the goal''s `triggering_rule`. ' only_where_experience_runs: type: boolean description: 'If true, triggers only on pages where the associated experience runs (Experience Location). Does not apply sitewide or to unrelated pages. ' required: - selector GoalStats: type: object readOnly: true properties: conversions_last_48h: type: integer description: The total number of times this goal has been triggered (converted) across all experiences in the last 48 hours. Useful for verifying if a goal is actively tracking. times_used: type: integer description: The number of active (non-archived) experiences that currently have this goal attached for tracking. CreateGoalRequestData: anyOf: - $ref: '#/components/schemas/CreateGoal' UpdateGoalRequestData: anyOf: - $ref: '#/components/schemas/Goal' SimpleGoal: type: object properties: id: description: The unique numerical identifier of the goal. type: integer name: description: The user-defined, friendly name of the goal. type: string SimpleGoalExpandable: oneOf: - type: integer description: Goal ID - $ref: '#/components/schemas/SimpleGoal' GetGoalsRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/GoalsListFilteringOptions' - $ref: '#/components/schemas/PageNumber' - type: object properties: include: description: Specifies the list of fields to be included in the response, which otherwise would not be sent. type: array items: $ref: '#/components/schemas/GoalOptionalFields' only: description: 'Only retrieve goals with the given ids. Including ''stats'' reduces the maximum number of ''only'' items to 50. ' type: array nullable: true items: type: integer maxItems: 200 except: description: 'Except goals with the given ids. Including ''stats'' reduces the maximum number of ''except'' items to 50. ' type: array items: type: integer maxItems: 200 GoalOptionalFields: type: string enum: - triggering_rule - stats GoalsListFilteringOptions: allOf: - $ref: '#/components/schemas/ResultsPerPage' - $ref: '#/components/schemas/SortDirection' - type: object properties: status: type: array nullable: true description: List of goal statuses to be returned items: $ref: '#/components/schemas/GoalStatuses' is_default: type: boolean nullable: true description: "A value that would be used to filter by default or not default goals. if not provided, all goals\ \ will be returned \n" search: type: string maxLength: 200 nullable: true description: A search string that would be used to search against Goal's name and description tracking: type: string nullable: true description: A value that would be used to filter by tracked or not tracked goals enum: - tracked - not_tracked - null usage: type: string nullable: true description: A value that would be used to filter by using in at least one experiment enum: - used - not_used - null goal_type: type: array nullable: true description: List of goal types to be returned items: $ref: '#/components/schemas/GoalTypes' experiences: type: array nullable: true description: List of experiences to be returned items: type: integer maxItems: 100 sort_by: type: string nullable: true default: id description: 'A value to sort audiences by specific field Defaults to **id** if not provided ' enum: - id - goal_tracking_status - name - times_used - type - key - status GoalsListPersistentOptions: allOf: - $ref: '#/components/schemas/GoalsListFilteringOptions' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/GoalsListColumnNames' GoalsListColumnNames: type: string description: Available columns for the goals list in the UI. enum: - name - id - type - times_used - goal_tracking_status - status - key BulkGoalsIds: type: array description: The list of goals id to delete items: type: integer minItems: 1 maxItems: 100 BulkUpdateGoalRequestData: type: object description: Request body for bulk updating the status of multiple goals. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkGoalsIds' status: $ref: '#/components/schemas/GoalStatuses' required: - id - status BulkDeleteGoalRequestData: type: object description: Request body for bulk deleting multiple goals. Contains a list of goal IDs to be permanently removed. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkGoalsIds' required: - id HypothesesListResponseData: type: object description: Response containing a list of hypotheses defined within a project, along with pagination details if applicable. properties: data: $ref: '#/components/schemas/HypothesesList' extra: $ref: '#/components/schemas/Extra' HypothesesList: type: array description: A list of hypothesis objects. items: $ref: '#/components/schemas/HypothesisData' HypothesisBase: type: object properties: id: type: integer description: The unique numerical identifier for the hypothesis. readOnly: true name: type: string description: A user-defined, concise name for the hypothesis (e.g., "Changing CTA Button Color to Green", "Simplifying Signup Form"). This name appears in the Compass section of Convert. maxLength: 100 url: type: string description: (Optional) A URL relevant to this hypothesis, such as the page where the proposed change would be implemented or a link to supporting research/data. maxLength: 2048 nullable: true project: $ref: '#/components/schemas/ProjectExpandable' prioritization_score: readOnly: true type: string description: 'The calculated priority score for this hypothesis, based on the chosen `prioritization_score_type` (PIE or ICE) and its attribute scores. Helps in ranking hypotheses to decide which to test next. KB: "Hypotheses (Compass)" - "How to Prioritize a Hypothesis". ' objective: type: string maxLength: 5000 description: 'A detailed description of the hypothesis. This should clearly state: 1. The **problem** observed (e.g., "Low click-through rate on the main CTA"). 2. The **proposed solution/change** (e.g., "Change the CTA button text from ''Learn More'' to ''Get Started Now''"). 3. The **expected outcome/impact** (e.g., "This will increase clicks on the CTA by 15% because ''Get Started Now'' is more action-oriented"). KB: "Hypotheses (Compass)" - "What is a Hypothesis". ' status: $ref: '#/components/schemas/HypothesisStatuses' start_date: description: (Optional) The date (YYYY-MM-DD) when this hypothesis was conceptualized or formally logged. type: string maxLength: 10 format: date nullable: true end_date: description: (Optional) The target date (YYYY-MM-DD) by which this hypothesis is expected to be tested or resolved. type: string maxLength: 10 format: date nullable: true summary: type: string description: (Optional) A brief summary or key takeaway from this hypothesis, often filled in after testing. maxLength: 500 description: type: string nullable: true maxLength: 5000 description: This is more details that want to be added besides the name of the hypothesis files: type: array description: Files attached to the hypothesis nullable: true items: $ref: '#/components/schemas/UploadedFileData' created_at: type: integer description: Unix timestamp (UTC) indicating when this hypothesis was created in the system. updated_at: type: integer readOnly: true description: Unix timestamp (UTC) indicating when this hypothesis entry was last updated or created. created_by: type: string readOnly: true nullable: true description: The name or identifier of the user who created this hypothesis. HypothesisCreateUpdateExperiences: type: array description: A list of experience IDs that are testing or were derived from this hypothesis. This links the hypothesis to actual experiments. items: type: integer maxItems: 100 HypothesisExperiences: type: array description: A list of experience IDs linked to this hypothesis. items: type: integer HypothesisData: oneOf: - $ref: '#/components/schemas/HypothesisDataPIE' - $ref: '#/components/schemas/HypothesisDataICE' discriminator: propertyName: prioritization_score_type mapping: PIE: '#/components/schemas/HypothesisDataPIE' ICE: '#/components/schemas/HypothesisDataICE' Hypothesis: oneOf: - $ref: '#/components/schemas/HypothesisPIE' - $ref: '#/components/schemas/HypothesisICE' discriminator: propertyName: prioritization_score_type mapping: PIE: '#/components/schemas/HypothesisPIE' ICE: '#/components/schemas/HypothesisICE' CreateHypothesis: oneOf: - $ref: '#/components/schemas/CreateHypothesisPIE' - $ref: '#/components/schemas/CreateHypothesisICE' discriminator: propertyName: prioritization_score_type mapping: PIE: '#/components/schemas/CreateHypothesisPIE' ICE: '#/components/schemas/CreateHypothesisICE' UpdateHypothesis: oneOf: - $ref: '#/components/schemas/UpdateHypothesisPIE' - $ref: '#/components/schemas/UpdateHypothesisICE' discriminator: propertyName: prioritization_score_type mapping: PIE: '#/components/schemas/UpdateHypothesisPIE' ICE: '#/components/schemas/UpdateHypothesisICE' HypothesisPIEBase: allOf: - $ref: '#/components/schemas/HypothesisBase' - type: object properties: prioritization_score_type: type: string description: A given description of prioritizing model enum: - PIE prioritization_score_attributes: $ref: '#/components/schemas/PIE_Attributes' HypothesisPIE: allOf: - $ref: '#/components/schemas/HypothesisPIEBase' - type: object properties: experiences: type: array nullable: true description: The list of experiences connected to this hypothesis items: $ref: '#/components/schemas/BaseExperienceExpandable' tags: type: array nullable: true description: The list of tags connected to this hypothesis items: $ref: '#/components/schemas/TagExpandable' HypothesisDataPIE: allOf: - $ref: '#/components/schemas/HypothesisPIEBase' - type: object properties: experiences: $ref: '#/components/schemas/HypothesisExperiences' tags: type: array nullable: true description: The list of tags connected to this hypothesis items: $ref: '#/components/schemas/TagExpandable' HypothesisDataICE: allOf: - $ref: '#/components/schemas/HypothesisICEBase' - type: object properties: experiences: $ref: '#/components/schemas/HypothesisExperiences' tags: type: array nullable: true description: The list of tags connected to this hypothesis items: $ref: '#/components/schemas/TagExpandable' CreateUpdateHypothesisPIEBase: allOf: - $ref: '#/components/schemas/HypothesisPIEBase' - type: object properties: experiences: $ref: '#/components/schemas/HypothesisCreateUpdateExperiences' tags: type: array nullable: true description: The list of tags connected to this hypothesis items: $ref: '#/components/schemas/TagExpandableRequest' CreateHypothesisPIE: allOf: - $ref: '#/components/schemas/CreateUpdateHypothesisPIEBase' required: - name - status - prioritization_score_type - prioritization_score_attributes UpdateHypothesisPIE: allOf: - $ref: '#/components/schemas/CreateUpdateHypothesisPIEBase' HypothesisICEBase: allOf: - $ref: '#/components/schemas/HypothesisBase' - type: object properties: prioritization_score_type: type: string description: A given description of prioritizing model enum: - ICE prioritization_score_attributes: $ref: '#/components/schemas/ICE_Attributes' HypothesisICE: allOf: - $ref: '#/components/schemas/HypothesisICEBase' - type: object properties: experiences: type: array nullable: true description: The list of experiences connected to this hypothesis items: $ref: '#/components/schemas/BaseExperienceExpandable' tags: type: array nullable: true description: The list of tags connected to this hypothesis items: $ref: '#/components/schemas/TagExpandable' CreateUpdateHypothesisICEBase: allOf: - $ref: '#/components/schemas/HypothesisICEBase' - type: object properties: experiences: $ref: '#/components/schemas/HypothesisCreateUpdateExperiences' tags: type: array nullable: true description: The list of tags connected to this hypothesis items: $ref: '#/components/schemas/TagExpandableRequest' CreateHypothesisICE: allOf: - $ref: '#/components/schemas/CreateUpdateHypothesisICEBase' required: - name - status - prioritization_score_type - prioritization_score_attributes UpdateHypothesisICE: allOf: - $ref: '#/components/schemas/CreateUpdateHypothesisICEBase' PIE_Attributes: description: 'Scores for the PIE (Potential, Importance, Ease) prioritization model. Each attribute is scored on a scale of 1 to 5. KB: "Hypotheses (Compass)" - "PIE prioritization model". ' title: PIE_Attributes type: object properties: potential: type: integer description: 'Score (1-5, 5 highest): How likely is this hypothesis to result in a significant improvement if successful?' minimum: 1 maximum: 5 importance: type: integer description: 'Score (1-5, 5 highest): How valuable is the traffic or user segment this hypothesis targets? (e.g., high-traffic pages, critical conversion funnel steps).' minimum: 1 maximum: 5 ease: type: integer description: 'Score (1-5, 5 easiest): How easy is it to implement the changes required to test this hypothesis, considering technical complexity and resource requirements?' minimum: 1 maximum: 5 ICE_Attributes: description: 'Scores for the ICE (Impact, Confidence, Ease) prioritization model. Each attribute is scored on a scale of 1 to 5. KB: "Hypotheses (Compass)" - "ICE prioritization model". ' title: ICE_Attributes type: object properties: impact: type: integer description: 'Score (1-5, 5 highest): If this hypothesis is successful, how much positive impact will it have on the key metric(s) you''re trying to improve?' minimum: 1 maximum: 5 confidence: type: integer description: 'Score (1-5, 5 highest): How confident are you that this hypothesis will achieve the desired impact and that the proposed changes are technically feasible?' minimum: 1 maximum: 5 ease: type: integer description: 'Score (1-5, 5 easiest): How easy is it to implement the changes required to test this hypothesis, considering technical complexity and resource requirements?' minimum: 1 maximum: 5 CreateHypothesisRequestData: $ref: '#/components/schemas/CreateHypothesis' UpdateHypothesisRequestData: $ref: '#/components/schemas/UpdateHypothesis' HypothesisStatuses: description: 'The current stage or outcome of a hypothesis in its lifecycle: - `draft`: The hypothesis is still being formulated or refined; not yet ready for testing. - `completed`: The hypothesis definition is finalized and it''s ready to be linked to an experiment or tested. - `applied`: The hypothesis is currently being tested in one or more active experiences. - `proven`: Testing has concluded, and the hypothesis was validated (i.e., the proposed change led to a positive, statistically significant outcome). Can be moved to Knowledge Base. - `disproven`: Testing has concluded, and the hypothesis was invalidated (i.e., the proposed change did not lead to the expected positive outcome or had a negative impact). Can be moved to Knowledge Base. - `archived`: The hypothesis is no longer active or relevant for current testing but is kept for historical records. KB: "Hypotheses (Compass)" - "Status of Hypothesis". ' type: string enum: - applied - archived - completed - draft - proven - disproven UpdateHypothesisStatusRequestData: type: object properties: status: $ref: '#/components/schemas/HypothesisStatuses' GetHypothesesListRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/HypothesesListFilteringOptions' - $ref: '#/components/schemas/PageNumber' - type: object properties: expand: description: 'Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields)' type: array items: $ref: '#/components/schemas/HypothesesListExpandFields' HypothesesListFilteringOptions: allOf: - $ref: '#/components/schemas/ResultsPerPage' - $ref: '#/components/schemas/SortDirection' - type: object properties: sort_by: type: string nullable: true default: id description: 'A value to sort hypotheses by specific field(s) Defaults to **id** if not provided ' enum: - id - name - score - start_date - status scoreMax: type: integer nullable: true default: 5 description: The maximum score for hypotheses which you would like to retrieve enum: - 0 - 1 - 2 - 3 - 4 - 5 scoreMin: type: integer default: 0 nullable: true description: The minimum score for hypotheses which you would like to retrieve enum: - 0 - 1 - 2 - 3 - 4 - 5 search: type: string maxLength: 200 nullable: true description: A search string that would be used to search against hypotheses's name or description status: type: array nullable: true description: The status of the hypotheses you'd like to be returned; one of the below can be provided items: $ref: '#/components/schemas/HypothesisStatuses' experiences: type: array nullable: true description: The list of experience ID's used to filter the list of returned hypotheses items: type: integer tags: type: array nullable: true description: The list of tag ID's used to filter the list of returned hypotheses items: type: integer only: description: 'Only retrieve hypotheses with the given ids. ' type: array nullable: true items: type: integer maxItems: 100 except: description: 'Except hypotheses with the given ids. ' type: array items: type: integer maxItems: 100 HypothesesListPersistentOptions: allOf: - $ref: '#/components/schemas/HypothesesListFilteringOptions' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/HypothesesListColumnNames' HypothesesListColumnNames: type: string description: Available columns for the hypotheses list in the UI. enum: - id - name - start_date - score - status - created_at - updated_at - created_by - experience HypothesesListExpandFields: type: string enum: - project - tags HypothesisExpandFields: type: string enum: - project - tags - experiences BulkHypothesisIds: type: array description: A list of hypothesis unique numerical identifiers to be affected by a bulk operation. items: type: integer minItems: 1 maxItems: 100 BulkUpdateHypothesesRequestData: type: object description: Request body for bulk updating the status of multiple hypotheses. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkHypothesisIds' status: $ref: '#/components/schemas/HypothesisStatuses' required: - id - status BulkDeleteHypothesesRequestData: type: object description: Request body for bulk deleting multiple hypotheses. Contains a list of hypothesis IDs to be permanently removed. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkHypothesisIds' required: - id GetCdnImagesListRequestData: type: object description: Parameters for listing images uploaded to a project's CDN storage. Supports pagination. properties: start_from: description: 'The `key` (filename on CDN) of an image from which to start listing. The returned list will include images lexicographically after this key. Used for pagination. ' type: string max_results: type: integer nullable: true minimum: 0 maximum: 100 default: 50 description: 'The maximum number of images to return in this request. Used for pagination. Default is 50. ' CdnImagesListResponseData: type: object description: Response containing a list of images hosted on Convert's CDN for the project. properties: data: $ref: '#/components/schemas/CdnImagesList' CdnImagesList: type: array description: A list of CDN image objects. items: $ref: '#/components/schemas/CdnImage' CdnImage: type: object description: Represents an image file hosted on Convert's CDN, typically used in experience variations. properties: cdn_url: description: The publicly accessible URL of the image on the Content Delivery Network (CDN). This URL can be used directly in `` tags or CSS. type: string key: description: 'The unique key or path identifier for this image within Convert''s CDN storage for the project (e.g., "project_images/my_hero_image.jpg"). This key is used for managing the image (e.g., deletion) and can be used for pagination (`start_from`). ' type: string UploadCdnImageRequestData: type: object description: 'Request body for uploading an image to the project''s CDN storage. Uses multipart/form-data. Supported image types: JPEG, PNG, GIF, WEBP, SVG. Maximum file size: 2MB. Maximum 50 images per hour per account-project. Knowledge Base: "Image Upload Guidelines for Convert Visual Editor". ' properties: image_name: description: The desired filename (including extension, e.g., "new_banner.png", "logo_variant.svg") for the image as it will be stored on the CDN. type: string maxLength: 200 image: description: 'The binary image file content to be uploaded. Constraints: Max 2MB; JPEG, PNG, GIF, WEBP, SVG. ' type: string format: binary required: - image_name - image UploadImageNoNameRequestData: type: object description: 'Request body for uploading an image where the filename might be derived from the uploaded file or generated by the system. Uses multipart/form-data. Typically used for quick uploads like variation screenshots. Constraints are the same as for `UploadCdnImageRequestData`. ' properties: image: type: string format: binary required: - image KnowledgeBasesListResponseData: type: object description: Response containing a list of Knowledge Base entries for a project, along with pagination details if applicable. properties: data: $ref: '#/components/schemas/KnowledgeBasesList' extra: $ref: '#/components/schemas/Extra' KnowledgeBasesList: type: array description: A list of Knowledge Base entry objects. items: $ref: '#/components/schemas/KnowledgeBase' BaseKnowledgeBase: type: object properties: id: type: integer description: The unique numerical identifier for this Knowledge Base entry. readOnly: true name: type: string description: A concise title for the Knowledge Base entry, often derived from the original hypothesis name or a summary of the key learning (e.g., "Green CTA Button Increased Signups by 10%", "Simplified Navigation Did Not Improve Task Completion"). maxLength: 100 project: $ref: '#/components/schemas/ProjectExpandable' status: $ref: '#/components/schemas/KnowledgeBaseStatuses' summary: type: string description: 'A detailed summary of the findings, insights, and conclusions derived from the tested hypothesis that led to this Knowledge Base entry. This should articulate what was learned, whether the hypothesis was proven or disproven, and any actionable takeaways. ' maxLength: 500 url: type: string description: Url reference for the knowledge base maxLength: 2048 nullable: true objective: type: string maxLength: 5000 description: A given description for the knowledge base to easily identify it later start_date: description: The date in format YYYY-MM-DD type: string maxLength: 10 format: date nullable: true end_date: description: The date in format YYYY-MM-DD type: string maxLength: 10 format: date nullable: true prioritization_score_type: type: string description: A given description of prioritizing model nullable: true prioritization_score_attributes: type: object description: Prioritization score attributes nullable: true experiences: type: array nullable: true description: The list of experiences connected to this knowledge base items: $ref: '#/components/schemas/BaseExperienceExpandable' description: type: string maxLength: 5000 description: Detailed description of the knowledge base files: type: array description: Files attached to the knowledge base nullable: true items: $ref: '#/components/schemas/UploadedFileData' created_by: type: string readOnly: true nullable: true description: The name or identifier of the user who created this Knowledge Base entry (often the person who marked the source hypothesis as proven/disproven). updated_at: type: integer readOnly: true description: Unix timestamp (UTC) indicating when this Knowledge Base entry was last updated or created. KnowledgeBase: allOf: - $ref: '#/components/schemas/BaseKnowledgeBase' - type: object properties: tags: type: array nullable: true description: The list of tags connected to this knowledge base items: $ref: '#/components/schemas/TagExpandable' KnowledgeBaseStatuses: description: 'The status of a Knowledge Base entry: - `active`: The entry is current and relevant. - `archived`: The entry is kept for historical purposes but may no longer be considered current best practice or has been superseded by newer learnings. ' type: string enum: - active - archived default: active GetKnowledgeBasesListRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/KnowledgeBasesListFilteringOptions' - $ref: '#/components/schemas/PageNumber' - type: object properties: expand: description: 'Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields)' type: array items: $ref: '#/components/schemas/KnowledgeBasesExpandFields' KnowledgeBasesListFilteringOptions: allOf: - $ref: '#/components/schemas/ResultsPerPage' - $ref: '#/components/schemas/SortDirection' - type: object properties: sort_by: type: string nullable: true default: name description: 'A value to sort knowledge bases by specific field(s) Defaults to **name** if not provided ' enum: - name - updated_at - status search: type: string maxLength: 200 nullable: true description: A search string that would be used to search against knowledge bases name status: type: array nullable: true description: The status of the knowledge bases you'd like to be returned; one of the below can be provided items: $ref: '#/components/schemas/KnowledgeBaseStatuses' tags: type: array nullable: true description: The list of tag ID's used to filter the list of returned knowledge bases items: type: integer only: description: 'Only retrieve knowledge bases with the given ids. ' type: array nullable: true items: type: integer maxItems: 100 except: description: 'Except knowledge bases with the given ids. ' type: array items: type: integer maxItems: 100 KnowledgeBasesListPersistentOptions: allOf: - $ref: '#/components/schemas/KnowledgeBasesListFilteringOptions' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/KnowledgeBasesListColumnNames' KnowledgeBasesListColumnNames: type: string description: Available columns for the Knowledge Base list in the UI. enum: - name - status - created_by - updated_at KnowledgeBasesExpandFields: type: string enum: - project - tags CreateKnowledgeBaseRequestData: allOf: - $ref: '#/components/schemas/BaseKnowledgeBase' - type: object properties: tags: type: array nullable: true description: The list of tags connected to this observation items: $ref: '#/components/schemas/TagExpandableRequest' required: - name - summary UpdateKnowledgeBasesStatusRequestData: type: object description: Request body for updating the status of a Knowledge Base entry. additionalProperties: false properties: status: $ref: '#/components/schemas/KnowledgeBaseStatuses' required: - status BulkKnowledgeBaseIds: type: array description: A list of Knowledge Base entry unique numerical identifiers to be affected by a bulk operation. items: type: integer minItems: 1 maxItems: 100 BulkUpdateKnowledgeBasesRequestData: type: object description: Request body for bulk updating the status of multiple Knowledge Base entries. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkKnowledgeBaseIds' status: $ref: '#/components/schemas/KnowledgeBaseStatuses' required: - id - status BulkDeleteKnowledgeBasesRequestData: type: object description: Request body for bulk deleting multiple Knowledge Base entries. Contains a list of entry IDs to be permanently removed. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkKnowledgeBaseIds' required: - id LiveDataEventTypes: type: string enum: - view_experience - conversion - transaction LiveDataEventsListResponseData: type: object description: Response containing a list of recent live tracking events for a project or account. properties: data: $ref: '#/components/schemas/LiveDataEventsList' LiveDataEventsList: type: array description: A list of live data event objects, showing real-time interactions. items: $ref: '#/components/schemas/LiveDataEvent' LiveDataEvent: type: object description: Represents a single real-time tracking event, such as a visitor being exposed to an experience or triggering a conversion goal. properties: devices: description: 'A list of device categories the visitor''s device belongs to (e.g., "DESK" for desktop, "IPH" for iPhone, "ALLTAB" for any tablet). Based on User-Agent parsing. KB: "Targeting Mobile, Tablet, and Desktop". ' type: array items: $ref: '#/components/schemas/ReportingSegmentsDeviceCategories' browser: $ref: '#/components/schemas/ReportingSegmentsBrowser' country: $ref: '#/components/schemas/ReportingSegmentsCountry' visitor_type: $ref: '#/components/schemas/ReportingSegmentsVisitorType' campaign: allOf: - $ref: '#/components/schemas/ReportingSegmentsCampaign' nullable: true custom_segments: description: A list of custom Convert Audiences (of type 'segmentation') that this visitor is currently a member of. type: array items: $ref: '#/components/schemas/SimpleAudienceSegmentExpandable' nullable: true sources: description: The traffic source(s) attributed to the visitor's session (e.g., 'direct', 'referral', 'Search', 'Campaign'). Derived from UTM parameters or referrer. type: array items: $ref: '#/components/schemas/ReportingSegmentsSource' nullable: true event_type: $ref: '#/components/schemas/LiveDataEventTypes' experiences: type: array description: 'A list of experiences relevant to this event. - If `event_type` is ''view_experience'', this list contains the experience(s) the visitor was just bucketed into. - If `event_type` is ''conversion'' or ''transaction'', this list contains the experience(s) the visitor was part of when they triggered the goal/transaction. Each item can be an experience ID or an expanded simple experience object (ID, name, variation ID/name). ' items: $ref: '#/components/schemas/SimpleExperienceExpandable' nullable: true conversion: description: Details about the conversion event, present if `event_type` is 'conversion' or 'transaction'. type: object nullable: true properties: goals: type: array items: $ref: '#/components/schemas/SimpleGoalExpandable' products_ordered_count: type: integer description: For 'transaction' events, the number of distinct products included in the order. nullable: true revenue: type: number description: For 'transaction' events, the monetary value of the order. nullable: true project: allOf: - $ref: '#/components/schemas/SimpleProjectExpandable' timestamp: type: integer description: Unix timestamp (UTC) indicating precisely when this event occurred. LiveDataAutoRefreshSettings: type: object properties: auto_refresh: type: object nullable: true properties: speed: type: integer minimum: 0 maximum: 5 enabled: type: boolean LiveDataExpandFields: type: string enum: - custom_segments - experiences - experiences.variation - conversion.goals - project LiveDataExpandParameter: type: object properties: expand: type: array nullable: true description: 'Specifies linked objects to expand in the live data response. Refer to the [Expanding Fields](#tag/Expandable-Fields) section. ' items: $ref: '#/components/schemas/LiveDataExpandFields' LocationTrigger: description: 'Defines how and when an experience associated with this location should be activated for a visitor who matches the location''s rules. The `type` determines the activation mechanism. Knowledge Base: "Locations" - "Dynamic Website Triggers". ' oneOf: - $ref: '#/components/schemas/LocationTriggerDomElement' - $ref: '#/components/schemas/LocationTriggerCallback' - $ref: '#/components/schemas/LocationTriggerManual' - $ref: '#/components/schemas/LocationTriggerUponRun' discriminator: propertyName: type mapping: dom_element: '#/components/schemas/LocationTriggerDomElement' callback: '#/components/schemas/LocationTriggerCallback' manual: '#/components/schemas/LocationTriggerManual' upon_run: '#/components/schemas/LocationTriggerUponRun' LocationTriggerTypes: type: string default: upon_run description: 'Specifies the mechanism that activates an experience when its location rules are met: - `upon_run`: (Default) The experience activates as soon as the Convert tracking script loads and evaluates that the visitor matches the location''s rules (e.g., URL match). This is the standard behavior for most A/B tests. - `manual`: The experience only activates when explicitly triggered by a JavaScript call (`window._conv_q.push({ what: ''triggerLocation'', params: { locationId: ''...'' } })`). Gives precise programmatic control over activation. - `dom_element`: The experience activates upon a specific user interaction (e.g., ''click'', ''hover'', ''in_view'', ''change'') with a defined DOM element (identified by a CSS `selector`). Useful for testing changes related to interactive elements. - `callback`: The experience activates when a custom JavaScript `callback` function (provided in `js`) calls the `activate()` function passed to it. Allows for complex asynchronous activation logic, e.g., after an API response or a specific SPA state change. Note: For Full Stack projects, `upon_run` is effectively the only mode, as activation is handled by the SDK. ' enum: - upon_run - manual - dom_element - callback LocationTriggerBase: type: object properties: type: $ref: '#/components/schemas/LocationTriggerTypes' required: - type LocationTriggerUponRun: allOf: - $ref: '#/components/schemas/LocationTriggerBase' - type: object properties: type: type: string enum: - upon_run additionalProperties: false LocationTriggerManual: allOf: - $ref: '#/components/schemas/LocationTriggerBase' - type: object properties: type: type: string enum: - manual additionalProperties: false LocationDomTriggerEvents: type: string description: 'The type of user interaction with a DOM element that will trigger the experience: - `click`: Activates when the element is clicked. - `hover`: Activates when the mouse pointer hovers over the element (mouseenter). - `in_view`: Activates when the element becomes visible in the browser''s viewport (e.g., user scrolls to it). KB: "Launch Experiments Using Custom JavaScript When Elements Appear in DOM". - `change`: Activates when the value of a form element (like input, select, textarea) changes. ' enum: - click - hover - in_view - change LocationTriggerDomElement: allOf: - $ref: '#/components/schemas/LocationTriggerBase' - type: object properties: type: type: string enum: - dom_element selector: description: Describes html selector type: string events: type: array description: Events for LocationTriggerDomElement items: $ref: '#/components/schemas/LocationDomTriggerEvents' additionalProperties: false required: - selector - events LocationTriggerCallback: allOf: - $ref: '#/components/schemas/LocationTriggerBase' - type: object properties: type: type: string enum: - callback js: type: string description: "Describes the js callback that will be executed in order to fire the experience.\n\nIt is called\ \ with two arguments:\n- `activate` - a function that should be called when the experience should be activated\n\ - `options` - an object with the following properties:\n - `locationId` - id of the location that is being\ \ activated\n - `isActive` - boolean flag that indicates if the location is active\nExample:\n```\nfunction(activate,\ \ options) {\n if (options.isActive) {\n setTimeout(function() {\n /* it activates the experiences\ \ 1 second after the\n location trigger is initialized - at the load of the tracking script */\n activate();\n\ \ }, 1000);\n }\n}\n```\n" additionalProperties: false required: - js LocationsListResponseData: type: object description: Response containing a list of locations defined within a project, along with pagination details if applicable. properties: data: $ref: '#/components/schemas/LocationsList' extra: $ref: '#/components/schemas/Extra' LocationsList: type: array description: A list of location objects. items: $ref: '#/components/schemas/Location' LocationBase: type: object properties: id: type: integer description: The unique numerical identifier for the location. readOnly: true description: type: string description: An optional, more detailed explanation of this location's purpose or the pages/conditions it targets. maxLength: 500 status: $ref: '#/components/schemas/LocationStatuses' name: type: string description: A user-defined, friendly name for the location (e.g., "All Product Pages", "Homepage Only", "Checkout Funnel"). This name appears in the Convert UI when selecting locations for experiences. maxLength: 100 preset: type: boolean description: Indicates if this location is a system-defined preset (e.g., "All Pages"). Preset locations cannot be modified directly but can be used as templates. readOnly: true selected_default: type: boolean description: If true, this location will be automatically pre-selected when creating new experiences within the project. Useful for commonly targeted site areas. stats: type: object readOnly: true description: Statistics related to the usage of this location. properties: experiences_usage: description: 'The number of currently active experiences that are using this location for targeting. This is an optional field, included if ''stats.experiences_usage'' is specified in the `include` parameter. ' type: number default: 0 LocationsPresetsListResponseData: type: object description: Response containing a list of predefined location templates (presets) available in the system. properties: data: $ref: '#/components/schemas/LocationsPresetsList' LocationsPresetsList: type: array description: A list of location preset objects. items: $ref: '#/components/schemas/LocationPreset' LocationPreset: type: object properties: id: type: integer description: The unique identifier for the location preset. readOnly: true description: type: string description: A brief explanation of the pages or conditions this preset location targets. name: type: string description: The display name of the preset location (e.g., "All Pages", "URL Starts With..."). stats: type: object readOnly: true description: Statistics related to the usage of this preset. properties: experiences_usage: description: 'The number of active experiences currently using this preset location. ' type: number default: 0 rules: nullable: true allOf: - $ref: '#/components/schemas/RuleObject' readOnly: true Location: allOf: - $ref: '#/components/schemas/LocationBase' - type: object properties: rules: nullable: true allOf: - $ref: '#/components/schemas/LocationRuleObject' trigger: $ref: '#/components/schemas/LocationTrigger' 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 LocationCreate: required: - name - rules allOf: - $ref: '#/components/schemas/Location' LocationRuleObject: type: object nullable: true description: 'Defines the logical structure for combining multiple rule conditions for a Location. It uses a nested OR -> AND -> OR_WHEN structure, similar to Audience rules, but `LocationRuleElement` types are restricted to page content/URL attributes. ' properties: OR: description: An array of AND-blocks. The location matches if any of these AND-blocks match. type: array items: type: object properties: AND: description: An array of OR_WHEN-blocks. This AND-block matches if all its OR_WHEN-blocks match. type: array items: type: object properties: OR_WHEN: description: An array of individual `LocationRuleElement` conditions. This OR_WHEN-block matches if any of its rule elements match. type: array items: $ref: '#/components/schemas/LocationRuleElement' LocationRuleElement: oneOf: - $ref: '#/components/schemas/GenericTextMatchRule' - $ref: '#/components/schemas/GenericNumericMatchRule' - $ref: '#/components/schemas/GenericTextKeyValueMatchRule' - $ref: '#/components/schemas/GenericNumericKeyValueMatchRule' - $ref: '#/components/schemas/GenericBoolKeyValueMatchRule' - $ref: '#/components/schemas/JsConditionMatchRule' discriminator: propertyName: rule_type mapping: url: '#/components/schemas/GenericTextMatchRule' url_with_query: '#/components/schemas/GenericTextMatchRule' query_string: '#/components/schemas/GenericTextMatchRule' page_tag_page_type: '#/components/schemas/GenericTextMatchRule' page_tag_category_id: '#/components/schemas/GenericTextMatchRule' page_tag_category_name: '#/components/schemas/GenericTextMatchRule' page_tag_product_sku: '#/components/schemas/GenericTextMatchRule' page_tag_product_name: '#/components/schemas/GenericTextMatchRule' page_tag_product_price: '#/components/schemas/GenericNumericMatchRule' page_tag_customer_id: '#/components/schemas/GenericTextMatchRule' page_tag_custom_1: '#/components/schemas/GenericTextMatchRule' page_tag_custom_2: '#/components/schemas/GenericTextMatchRule' page_tag_custom_3: '#/components/schemas/GenericTextMatchRule' page_tag_custom_4: '#/components/schemas/GenericTextMatchRule' generic_text_key_value: '#/components/schemas/GenericTextKeyValueMatchRule' generic_numeric_key_value: '#/components/schemas/GenericNumericKeyValueMatchRule' generic_bool_key_value: '#/components/schemas/GenericBoolKeyValueMatchRule' js_condition: '#/components/schemas/JsConditionMatchRule' LocationExpandable: anyOf: - type: integer description: Location ID - $ref: '#/components/schemas/Location' SimpleLocationExpandable: anyOf: - type: integer description: Location ID - $ref: '#/components/schemas/SimpleLocation' CreateLocationRequestData: $ref: '#/components/schemas/LocationCreate' UpdateLocationRequestData: $ref: '#/components/schemas/Location' LocationIncludeFields: type: string enum: - rules - trigger - stats.experiences_usage GetLocationsListRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/LocationsListFilteringOptions' - $ref: '#/components/schemas/PageNumber' - type: object properties: include: description: Specifies the list of fields to be included in the response, which otherwise would not be sent. type: array items: $ref: '#/components/schemas/LocationIncludeFields' only: description: 'Only retrieve location with the given ids. ' type: array nullable: true items: type: integer maxItems: 100 except: description: 'Except locations with the given ids. ' type: array items: type: integer maxItems: 100 LocationsListFilteringOptions: allOf: - $ref: '#/components/schemas/ResultsPerPage' - $ref: '#/components/schemas/SortDirection' - type: object properties: status: type: array nullable: true description: List of Location statuses to be returned items: $ref: '#/components/schemas/LocationStatuses' is_default: type: boolean nullable: true description: 'It indicates wherever retrieved locations are default or not If not provided, it will return all locations. If not provided, it will return all locations ' search: type: string maxLength: 200 nullable: true description: a search string that would be used to search against Location's name or description sort_by: type: string nullable: true default: id description: 'A value to sort Location by specific field Defaults to **id** if not provided ' enum: - id - name - usage - status - key usage: type: string nullable: true description: It indicates wherever retrieved locations are used or not inside experiences enum: - used - not_used LocationsListPersistentOptions: allOf: - $ref: '#/components/schemas/LocationsListFilteringOptions' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/LocationsListColumnNames' LocationsListColumnNames: type: string description: Available columns for the locations list in the UI. enum: - name - id - usage - status - key LocationStatuses: type: string description: 'The current status of a location: - `active`: The location is active and can be used for targeting experiences. - `archived`: The location is archived and no longer available for new experiences, but its definition is preserved. Archived locations can often be cloned. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences." ' enum: - active - archived default: active BulkLocationsIds: type: array description: A list of location unique numerical identifiers to be affected by a bulk operation. items: type: integer minItems: 1 maxItems: 100 BulkUpdateLocationsRequestData: type: object description: Request body for bulk updating the status of multiple locations. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkLocationsIds' status: $ref: '#/components/schemas/LocationStatuses' required: - id - status BulkDeleteLocationsRequestData: type: object description: Request body for bulk deleting multiple locations. Contains a list of location IDs to be permanently removed. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkLocationsIds' required: - id OAuthScopeMode: type: string enum: - selected_accounts_projects OAuthScopeProject: type: object required: - project_id - role properties: project_id: type: integer minimum: 1 role: description: User's role for this project. type: string name: description: Display name of the project. type: string OAuthScopeAccount: type: object required: - account_id properties: account_id: type: integer minimum: 1 projects: type: array items: $ref: '#/components/schemas/OAuthScopeProject' OAuthScopeAccountResponse: type: object required: - account_id properties: account_id: type: integer minimum: 1 name: description: Display name of the account. type: string projects: type: array items: $ref: '#/components/schemas/OAuthScopeProject' OAuthScopeRequest: type: object required: - mode properties: mode: $ref: '#/components/schemas/OAuthScopeMode' accounts: type: array items: $ref: '#/components/schemas/OAuthScopeAccount' OAuthScopeResponse: type: object required: - mode properties: mode: $ref: '#/components/schemas/OAuthScopeMode' accounts: type: array items: $ref: '#/components/schemas/OAuthScopeAccountResponse' OAuthApprovedScopeRequest: type: object required: - mode - accounts properties: mode: $ref: '#/components/schemas/OAuthScopeMode' accounts: type: array items: $ref: '#/components/schemas/OAuthScopeAccount' OAuthScopeSummary: type: object required: - mode - accounts_count - project_limited_accounts_count - projects_count properties: mode: $ref: '#/components/schemas/OAuthScopeMode' accounts_count: type: integer minimum: 0 project_limited_accounts_count: type: integer minimum: 0 projects_count: type: integer minimum: 0 OAuthAuthorizedAccountRef: type: object required: - account_id - name properties: account_id: type: integer minimum: 1 name: type: string OAuthInitiateAuthorizationRequestData: type: object required: - client_id - pkce_challenge - scope properties: client_id: description: OAuth client application ID. type: string pkce_challenge: description: PKCE S256 code challenge. type: string minLength: 43 maxLength: 128 pattern: ^[A-Za-z0-9\-_]+$ pkce_challenge_method: description: PKCE challenge method. Only `S256` is accepted. type: string enum: - S256 scope: $ref: '#/components/schemas/OAuthScopeRequest' state: description: Opaque value from the OAuth client, passed through unchanged in the response. type: string OAuthInitiateAuthorizationResponseData: type: object required: - request_id - client_id - client_name - status - scope - callback_url properties: request_id: type: string format: uuid client_id: type: string client_name: description: Display name of the OAuth client application. type: string status: type: string enum: - pending scope: $ref: '#/components/schemas/OAuthScopeResponse' callback_url: type: string format: uri state: type: string OAuthAuthorizationRequestDetailsResponseData: type: object required: - request_id - client_id - status - scope - callback_url properties: request_id: type: string format: uuid client_id: type: string client_name: description: Display name of the OAuth client application. type: string status: type: string enum: - pending - approved - exchanged scope: $ref: '#/components/schemas/OAuthScopeResponse' callback_url: type: string format: uri OAuthApproveAuthorizationRequestData: type: object required: - request_id - state - scope properties: request_id: type: string format: uuid state: description: CSRF protection value received by the client during the /authorize redirect. Passed through to the callback URL. type: string scope: $ref: '#/components/schemas/OAuthApprovedScopeRequest' OAuthApproveAuthorizationResponseData: type: object required: - callback_url - accounts_linked - scope_summary properties: callback_url: description: Client redirect URL containing the one-time authorization code and state parameter. type: string format: uri accounts_linked: type: array items: $ref: '#/components/schemas/OAuthAuthorizedAccountRef' scope_summary: $ref: '#/components/schemas/OAuthScopeSummary' OAuthTokenRequestData: type: object required: - grant_type - code - client_id - code_verifier properties: grant_type: description: Authorization grant type. type: string enum: - authorization_code default: authorization_code code: description: One-time authorization code from consent redirect. type: string minLength: 1 client_id: description: Identifier of the OAuth client application that initiated the authorization request. type: string code_verifier: description: PKCE verifier for code challenge validation. type: string minLength: 43 maxLength: 128 pattern: ^[A-Za-z0-9\-._~]+$ OAuthTokenResponseData: type: object required: - access_token - token_type - expires_at - scope properties: access_token: description: Opaque OAuth session bearer token. type: string token_type: type: string enum: - Bearer expires_at: type: integer description: Absolute expiration timestamp (unix seconds). scope: $ref: '#/components/schemas/OAuthScopeResponse' OAuthCreateClientRequestData: type: object required: - name - callback_url - embedded properties: name: type: string maxLength: 120 callback_url: type: string format: uri description: type: string maxLength: 500 embedded: type: boolean default: false description: 'Enable this when the OAuth client is used by a third-party or embedded integration. An embedded client stays active even if the user who created it is later deleted, so integrations that depend on it continue to work. ' OAuthUpdateClientRequestData: type: object properties: name: type: string maxLength: 120 callback_url: type: string format: uri description: type: string maxLength: 500 embedded: type: boolean description: 'Enable this when the OAuth client is used by a third-party or embedded integration. An embedded client stays active even if the user who created it is later deleted, so integrations that depend on it continue to work. ' OAuthClientData: type: object required: - id - name - callback_url - embedded properties: id: type: string readOnly: true name: type: string callback_url: type: string format: uri description: type: string embedded: type: boolean description: 'Enable this when the OAuth client is used by a third-party or embedded integration. An embedded client stays active even if the user who created it is later deleted, so integrations that depend on it continue to work. ' created_at: type: integer OAuthClientsListResponseData: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/OAuthClientData' OAuthClientResponseData: type: object required: - id - name - callback_url - embedded properties: id: type: string name: type: string callback_url: type: string format: uri description: type: string embedded: type: boolean description: 'Enable this when the OAuth client is used by a third-party or embedded integration. An embedded client stays active even if the user who created it is later deleted, so integrations that depend on it continue to work. ' created_at: type: integer OAuthDeleteClientResponseData: type: object required: - code - message properties: code: type: integer message: type: string ObservationsListResponseData: type: object description: Response containing a list of observations for a project, along with pagination details if applicable. properties: data: $ref: '#/components/schemas/ObservationsList' extra: $ref: '#/components/schemas/Extra' ObservationsList: type: array description: A list of observation objects. items: $ref: '#/components/schemas/Observation' BaseObservation: type: object properties: id: type: integer description: The unique numerical identifier for the observation. readOnly: true name: type: string description: A user-defined, concise title for the observation (e.g., "Users drop off on pricing page", "High bounce rate on mobile landing page", "Positive feedback on new feature idea"). maxLength: 100 description: type: string maxLength: 5000 description: (Optional) A detailed description of the observation, including context, data points, user quotes, or any relevant details that support the insight. nullable: true project: $ref: '#/components/schemas/ProjectExpandable' status: $ref: '#/components/schemas/ObservationStatuses' url: type: string description: (Optional) A URL relevant to this observation, such as the page where the behavior was observed or a link to an analytics report. maxLength: 2048 nullable: true created_by: type: string readOnly: true nullable: true description: The name or identifier of the user who created this observation. created_at: type: integer readOnly: true description: Unix timestamp (UTC) indicating when this observation was created in the system. updated_at: type: integer readOnly: true description: Unix timestamp (UTC) indicating when this observation entry was last updated or created. Observation: allOf: - $ref: '#/components/schemas/BaseObservation' - type: object properties: images: type: array description: This is the document that is used as a visual representation of the observe feature deprecated: true nullable: true items: $ref: '#/components/schemas/ObservationImageData' files: type: array description: This is the document that is used as a visual representation of the observe feature nullable: true items: $ref: '#/components/schemas/UploadedFileData' tags: type: array nullable: true description: The list of tags connected to this observation items: $ref: '#/components/schemas/TagExpandable' ObservationImageData: type: object description: (Deprecated) Represents an image attached to an observation. additionalProperties: false properties: url: description: URL of the image, typically hosted on Convert's CDN. type: string maxLength: 500 name: description: The display name of the image file. type: string maxLength: 250 ObservationImage: allOf: - $ref: '#/components/schemas/ObservationImageData' - type: object required: - url - name ObservationFile: allOf: - $ref: '#/components/schemas/UploadedFileData' - type: object required: - key - name CreateUpdateObservation: allOf: - $ref: '#/components/schemas/BaseObservation' - type: object properties: images: type: array description: This is the document that is used as a visual representation of the observe feature nullable: true items: $ref: '#/components/schemas/ObservationImage' maxItems: 3 files: type: array description: This is the document that is used as a visual representation of the observe feature nullable: true items: $ref: '#/components/schemas/ObservationFile' maxItems: 3 tags: type: array nullable: true description: The list of tags connected to this observation items: $ref: '#/components/schemas/TagExpandableRequest' CreateObservation: allOf: - $ref: '#/components/schemas/CreateUpdateObservation' - type: object required: - name CreateObservationRequestData: $ref: '#/components/schemas/CreateObservation' UpdateObservationRequestData: $ref: '#/components/schemas/CreateUpdateObservation' ObservationStatuses: description: 'The current status of an observation in its lifecycle: - `active`: The observation is current, under consideration, or being actively discussed. This is the default for new observations. - `archived`: The observation has been reviewed and is no longer actively being pursued (e.g., deemed not actionable, superseded, or already addressed). It''s kept for historical records. Knowledge Base: "Observations Feature Guide" - "Status Management". ' type: string enum: - active - archived default: active GetObservationsListRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/ObservationsListFilteringOptions' - $ref: '#/components/schemas/PageNumber' - type: object properties: expand: description: 'Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to [Expanding Fields](#tag/Expandable-Fields)' type: array items: $ref: '#/components/schemas/ObservationsExpandFields' ObservationsListFilteringOptions: allOf: - $ref: '#/components/schemas/ResultsPerPage' - $ref: '#/components/schemas/SortDirection' - type: object properties: sort_by: type: string nullable: true default: name description: 'A value to sort observations by specific field(s) Defaults to **name** if not provided ' enum: - name - created_by - date_added - status search: type: string maxLength: 200 nullable: true description: A search string that would be used to search against observation's name or description status: type: array nullable: true description: The status of the observations you'd like to be returned; one of the below can be provided items: $ref: '#/components/schemas/ObservationStatuses' tags: type: array nullable: true description: The list of tag ID's used to filter the list of returned observations items: type: integer only: description: 'Only retrieve observations with the given ids. ' type: array nullable: true items: type: integer maxItems: 100 except: description: 'Except observations with the given ids. ' type: array items: type: integer maxItems: 100 ObservationsListPersistentOptions: allOf: - $ref: '#/components/schemas/ObservationsListFilteringOptions' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/ObservationsListColumnNames' ObservationsListColumnNames: type: string description: Available columns for the observations list in the UI. enum: - name - created_by - created_at - updated_at - status ObservationsExpandFields: type: string enum: - project - tags BulkObservationIds: type: array description: A list of observation unique numerical identifiers to be affected by a bulk operation. items: type: integer minItems: 1 maxItems: 100 BulkUpdateObservationsRequestData: type: object description: Request body for bulk updating the status of multiple observations. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkObservationIds' status: $ref: '#/components/schemas/ObservationStatuses' required: - id - status BulkDeleteObservationsRequestData: type: object description: Request body for bulk deleting multiple observations. Contains a list of observation IDs to be permanently removed. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkObservationIds' required: - id PlanFeature: type: object description: Plan feature definition in the global catalog properties: item_id: type: string description: 'Unique identifier for the feature (format: "feature#{feature_id}")' readOnly: true type: type: string description: Type of item, always "feature" for features enum: - feature readOnly: true feature_id: type: string description: Unique feature identifier name: type: string description: Display name of the feature nullable: true description: type: string description: Description of what the feature does nullable: true created_at: type: string description: Creation timestamp readOnly: true updated_at: type: string description: Last update timestamp readOnly: true required: - feature_id - type PlanFeatureList: type: array description: List of plan features items: $ref: '#/components/schemas/PlanFeature' PlanFeatureResponse: type: object description: Response containing a plan feature properties: data: $ref: '#/components/schemas/PlanFeature' PlanFeatureListResponse: type: object description: Response containing a list of plan features properties: data: $ref: '#/components/schemas/PlanFeatureList' CreatePlanFeatureRequest: type: object description: Request body for creating a new plan feature properties: feature_id: type: string description: Unique feature identifier name: type: string description: Display name of the feature nullable: true description: type: string description: Description of what the feature does nullable: true required: - feature_id UpdatePlanFeatureRequest: type: object description: Request body for updating a plan feature properties: name: type: string description: Display name of the feature nullable: true description: type: string description: Description of what the feature does nullable: true PlanLimit: type: object description: Plan limit definition in the global catalog properties: item_id: type: string description: 'Unique identifier for the limit (format: "limit#{limit_key}")' readOnly: true type: type: string description: Type of item, always "limit" for limits enum: - limit readOnly: true limit_key: type: string description: Unique limit key (e.g., "pv", "tv", "pers", "domains") name: type: string description: Display name of the limit nullable: true description: type: string description: Description of what the limit controls nullable: true created_at: type: string description: Creation timestamp readOnly: true updated_at: type: string description: Last update timestamp readOnly: true required: - limit_key - type PlanLimitList: type: array description: List of plan limits items: $ref: '#/components/schemas/PlanLimit' PlanLimitResponse: type: object description: Response containing a plan limit properties: data: $ref: '#/components/schemas/PlanLimit' PlanLimitListResponse: type: object description: Response containing a list of plan limits properties: data: $ref: '#/components/schemas/PlanLimitList' CreatePlanLimitRequest: type: object description: Request body for creating a new plan limit properties: limit_key: type: string description: Unique limit key (e.g., "pv", "tv", "pers", "domains") name: type: string description: Display name of the limit nullable: true description: type: string description: Description of what the limit controls nullable: true required: - limit_key UpdatePlanLimitRequest: type: object description: Request body for updating a plan limit properties: name: type: string description: Display name of the limit nullable: true description: type: string description: Description of what the limit controls nullable: true PlanManagement: type: object description: Billing plan data structure for management operations properties: plan_id: type: integer description: Unique identifier for the billing plan readOnly: true plan_name: type: string description: Display name of the billing plan main_plan_name: type: string description: Main plan name if this is a variant nullable: true product: $ref: '#/components/schemas/Products' price: type: string description: Price of the plan (in cents or base currency unit) contract: type: string description: Contract type enum: - year - pay_as_you_go plan_duration: type: string description: Duration of the plan (e.g., "1Y", "1M") plan_group: type: string description: Plan group identifier nullable: true pricing_iteration: type: string description: Pricing iteration version active: type: string description: Whether the plan is active ("1" or "0") enum: - '1' - '0' no_cancel: type: string description: Whether cancellation is allowed ("1" or "0") nullable: true stripe_live_id: type: string description: Stripe live price/plan ID nullable: true stripe_testing_id: type: string description: Stripe testing price/plan ID nullable: true paddle_price_id_production: type: string description: Paddle production price ID nullable: true paddle_price_id_sandbox: type: string description: Paddle sandbox price ID nullable: true stripe_product_id_test: type: string description: Stripe product ID for test/sandbox environment nullable: true stripe_product_id_live: type: string description: Stripe product ID for production/live environment nullable: true paddle_product_id_sandbox: type: string description: Paddle product ID for sandbox environment nullable: true paddle_product_id_production: type: string description: Paddle product ID for production environment nullable: true tw_live_id: type: string description: Third-party live ID nullable: true tw_testing_id: type: string description: Third-party testing ID nullable: true functions: type: object description: Plan features as JSON object mapping feature_id to enabled status additionalProperties: type: integer enum: - 0 - 1 limits: type: object description: Plan limits as JSON object with limit keys and their values additionalProperties: type: object properties: number: type: string nullable: true unit_overusage: type: string nullable: true unit_count: type: string nullable: true required: - plan_id - plan_name - product - price - contract - plan_duration - active PlanManagementList: type: array description: List of billing plans items: $ref: '#/components/schemas/PlanManagement' PlanManagementResponse: type: object description: Response containing a billing plan properties: data: $ref: '#/components/schemas/PlanManagement' PlanManagementListResponse: type: object description: Response containing a list of billing plans properties: data: $ref: '#/components/schemas/PlanManagementList' CreatePlanRequest: $ref: '#/components/schemas/PlanManagement' UpdatePlanRequest: $ref: '#/components/schemas/PlanManagement' ProjectsListResponseData: type: object description: Response containing a list of projects accessible to the user, along with pagination details if applicable. properties: data: $ref: '#/components/schemas/ProjectsList' extra: $ref: '#/components/schemas/Extra' ProjectsExportResponseFile: type: object description: Represents the structure of the JSON file exported for a project, containing all its configurations (experiences, goals, audiences, etc.). ProjectsList: type: array description: A list of project objects. items: $ref: '#/components/schemas/Project' Project: description: 'Represents a Convert project, which is a container for organizing a set of related optimization activities (experiences), their goals, target audiences, associated website domains, and collaborators. Each project has its own unique tracking script. Knowledge Base: "What is a Project?". ' allOf: - $ref: '#/components/schemas/BaseProject' - type: object properties: id: type: integer description: Unique identifier representing a specific project in an user account. The project Id is part of the tracking snippet accessRole: $ref: '#/components/schemas/AccessRoleNames' owner_email: type: string description: Used only internally - An email of project owner. This field will exist only if project type is shared. account_id: type: integer description: The unique ID of the account under which this project is created. Account ID is also part of the tracking snippet created_at: type: integer description: Unix timestamp when project was created, in UTC time. modified_at: type: integer description: Unix timestamp when project was last modified, in UTC time. tracking_snippet: type: string description: The tracking code that needs to be placed on site in order to serve experiences from this project. updateMetadata: type: object description: 'Live update status for CDN invalidation of this project''s data and JS bundle. These fields allow the UI to inform the user when changes are pending and when they took effect. All timestamps are in seconds (UTC). ' properties: pendingChanges: type: object description: Flags indicating if changes are pending CDN invalidation. properties: data: type: boolean description: True if data changes are pending CDN invalidation. js: type: boolean description: True if JS bundle changes are pending CDN invalidation. lastInvalidation: type: object description: Timestamps for the last completed CDN invalidations. properties: js: type: integer nullable: true description: Timestamp (seconds) when the last JS CDN invalidation completed. data: type: integer nullable: true description: Timestamp (seconds) when the last Data CDN invalidation completed. nextInvalidation: type: object description: Timestamps for the nearest scheduled CDN invalidations. properties: js: type: integer nullable: true description: The nearest scheduled CDN invalidation time (seconds) for the JS bundle if pending. data: type: integer nullable: true description: The nearest scheduled CDN invalidation time (seconds) for Data if pending. type: type: string description: Used only internally - A value which describes project ownership. Can be own or shared. enum: - own - shared stats: type: object description: Various stats for this project. Optional field, controlled using [include fields](#tag/Optional-Fields) properties: visitor_data: type: object description: Visitor Data usage statistics for current project properties: visitor_profiles_count: type: integer description: The total count of Visitor Data records inside current project. visitor_profiles_fields_count: type: integer description: The total count of Visitor Data Placeholders inside current project. active_personalised_experiences_count: type: integer description: The total count of active experiences that use Visitor Data Placeholders inside current project. google_analytics: description: Various stats related to google analytics integration type: object properties: used_slots: description: List of Google Analytics Classic implementation slots used by experiences integrations type: array items: type: integer deprecated: true used_dimensions: description: List of Google Analytics Universal implementation custom dimensions used by experiences integrations type: array items: type: integer usage: type: object description: Usage metrics for the current billing period properties: used_tested_users: type: integer description: The number of tested users counted into the current project in the current billing interval. This counter is used towards account's usage quota for certain billing plans. used_tested_visitors: type: integer description: The number of tested visitors counted into the current project in the current billing interval. This counter is used towards account's usage quota for certain billing plans. active_segments_count: type: integer description: Total number of Audiences with type segment inside this project. segments_count: type: integer deprecated: true description: Total number of Audiences with type segment inside this project. experiences_count: type: integer description: The total number of experiences existing inside current project. active_experiences_count: type: integer description: The number of active experiences existing inside current project. active_experiments_count: type: integer description: The number of active experiments inside the project besides deploys. active_goals_count: type: integer description: The number of active goals existing inside current project. visitor_insights: type: object description: Visitor Insights usage statistics for Convert Signals session recordings and Heatmaps for the current project. properties: usage: type: number format: float nullable: true description: 'The proportion of the allocated capacity used for session recordings and heatmaps for this project in the current billing period, expressed as a decimal between 0 and 1 (for example 0.75 means 75% of the allocation is used). ' reset_at: type: string format: date-time nullable: true description: 'The date and time when the capacity allocation for session recordings and heatmaps resets for the current billing period. ' domains: type: array items: $ref: '#/components/schemas/Domain' description: The list of websites included in this project. sdk_key: type: string readOnly: true nullable: true description: An autogenerated hash key used to retrieve data of fullstack project. Available only for fullstack projects type. DNSRecordTypes: description: The type of the DNS record. type: string enum: - TXT - CNAME CustomDomainOwnershipVerificationItem: type: object properties: name: type: string description: The name of the DNS record. type: $ref: '#/components/schemas/DNSRecordTypes' value: type: string description: The value of the DNS record. 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: true properties: current_version: description: The version string of the tracking script currently active for this project (e.g., "v2.11.3"). type: string previous_version: type: string description: The version string of the tracking script that was active before the `current_version`. Only available if a rollback is possible (manual mode). nullable: true readOnly: true available_versions: $ref: '#/components/schemas/TrackingScriptAvailableVersions' release: $ref: '#/components/schemas/TrackingScriptRelease' visitor_insights: allOf: - $ref: '#/components/schemas/VisitorInsightsBase' - type: object properties: id: type: string readOnly: true description: Id of the visitor insights nullable: true description: "Settings for Convert Signals\u2122 (Visitor Insights), which captures sessions with user frustration\ \ signals.\nKB: \"Understanding Convert Signals\u2122 and signals.observer.min.js script in Convert\".\n" integrations_settings: type: object description: Project-wide settings for various third-party integrations (e.g., Google Analytics, Crazy Egg, Hotjar). Experience-level settings can sometimes override these. properties: crazyegg: description: 'Settings for Crazy Egg integration. Requires API key and secret for certain functionalities like automatically creating snapshots for variations. KB: "Integrate Convert Experiences with Crazy Egg". ' properties: api_key: type: string maxLength: 100 nullable: true description: Crazy Egg API key for this project. api_secret: type: string maxLength: 100 nullable: true description: Crazy Egg API secret. Not returned in GET requests for security. google_analytics: $ref: '#/components/schemas/GA_Settings' kissmetrics: type: object properties: enabled: type: boolean description: If true, enables sending of Convert experiment data to Kissmetrics for this project. hotjar: type: object properties: enabled: type: boolean description: If true, enables sending of Convert experiment data (as tags) to Hotjar for this project. status: $ref: '#/components/schemas/ProjectStatuses' custom_domain: type: object nullable: true description: 'Configuration for using a custom domain (CNAME) to serve the Convert tracking script and receive tracking data. This can improve branding and potentially reduce issues with ad blockers or third-party cookie restrictions. Requires DNS setup. ' required: - domain properties: domain: type: string description: The custom domain name (e.g., "analytics.yourcompany.com") to be used for Convert tracking. maxLength: 150 pattern: ^.+\..+ status: type: string description: 'The activation status of the custom domain: - `pending`: DNS changes are made, awaiting verification and activation by Convert. - `active`: Custom domain is verified and actively being used for tracking. ' readOnly: true enum: - pending - active ownership_verification: type: array nullable: true readOnly: true description: DNS records and values required to verify ownership of the custom domain. Provided by Convert during setup. items: $ref: '#/components/schemas/CustomDomainOwnershipVerificationItem' version: type: string description: The version of the custom domain. readOnly: true environments: type: object description: 'A user-defined map of environments for this project (e.g., "production", "staging", "development"). Each environment has its own variant of the tracking script. Experiences are typically configured to run in a specific environment. The number of allowed environments depends on the account''s subscription plan. KB: "The Environments Feature". ' additionalProperties: type: object description: Defines a single environment. The key of this object in the parent `environments` map is the environment's machine-readable name (e.g., "production"). properties: label: type: string description: A user-friendly display name for the environment (e.g., "Production Live Site", "QA Staging Server"). is_default: type: boolean description: If true, this environment is considered the default for the project. New experiences might default to this environment if not specified. Only one environment can be the default. js: type: string nullable: true description: 'The environment-specific javascript code that will be loaded after the project''s global javascript. When an environment is specified in the request, this code will be appended to the project''s global_javascript with a newline character. ' required: - label - is_default default: production: label: Production is_default: true default_goals: type: array description: A list of Goal IDs that will be automatically added to any new experience created within this project. items: $ref: '#/components/schemas/SimpleGoalExpandable' default_audiences: type: array description: A list of Audience IDs that will be automatically added to any new experience created within this project. items: $ref: '#/components/schemas/SimpleAudienceExpandable' default_locations: type: array description: A list of Location IDs that will be automatically added to any new experience created within this project. items: $ref: '#/components/schemas/SimpleLocationExpandable' TrackingScriptAvailableVersions: type: array description: A list of available versions for the Convert tracking script, each with a version tag, changelog, release date, and potentially the date it was or will be applied to the project. readOnly: true items: type: object properties: version: type: string description: The version tag string (e.g., "v2.11.3", "v3.0.0-beta1"). changelog: type: string nullable: true description: A summary of changes, improvements, and bug fixes included in this script version. released_date: type: integer format: int64 description: Unix timestamp (UTC) when this script version was officially released by Convert. apply_date: type: integer format: int64 nullable: true description: Unix timestamp (UTC) when this version was (or is scheduled to be) applied to the project, if using manual or scheduled updates. TrackingScriptReleaseBase: type: object description: Base settings for managing how new versions of the Convert tracking script are applied to the project. properties: type: type: string description: 'The chosen strategy for updating the tracking script: ''manual'', ''latest'' (auto-update), or ''scheduled''. ' TrackingScriptReleaseTypes: type: string description: 'Defines the update strategy for the project''s Convert tracking script: - `manual`: (Default) The project remains on its current script version. Updates to newer versions must be initiated manually by an administrator. Allows for controlled rollouts and rollbacks to the immediate previous version. - `latest`: The project''s tracking script will automatically update to the newest stable version as soon as Convert releases it. Ensures access to the latest features and fixes with minimal intervention. - `scheduled`: Updates to the latest script version are automatically applied at a predefined day and time of the week, allowing updates during off-peak hours. KB: "Tracking Script Version Management". ' enum: - manual - latest - scheduled TrackingScriptReleaseAutomaticApplyOn: type: object description: Configuration for scheduled tracking script updates, specifying the day of the week and time for automatic application of new versions. additionalProperties: false properties: day: type: integer description: Day of the week for scheduled updates (e.g., 1 for Monday, 7 for Sunday - convention needs to be clear). minimum: 1 maximum: 7 time: type: string pattern: ^([01]?[0-9]|2[0-4]):([0-5][0-9])$ description: Time of day (in project's timezone or UTC, needs clarification) in HH:MM format for scheduled updates (e.g., "03:00" for 3 AM). required: - day - time TrackingScriptReleaseManual: allOf: - $ref: '#/components/schemas/TrackingScriptReleaseBase' - type: object additionalProperties: false properties: type: enum: - manual TrackingScriptReleaseLatest: allOf: - $ref: '#/components/schemas/TrackingScriptReleaseBase' - type: object additionalProperties: false properties: type: enum: - latest TrackingScriptReleaseScheduled: allOf: - $ref: '#/components/schemas/TrackingScriptReleaseBase' - type: object additionalProperties: false properties: type: enum: - scheduled automatic_apply_on: $ref: '#/components/schemas/TrackingScriptReleaseAutomaticApplyOn' TrackingScriptRelease: oneOf: - $ref: '#/components/schemas/TrackingScriptReleaseManual' - $ref: '#/components/schemas/TrackingScriptReleaseLatest' - $ref: '#/components/schemas/TrackingScriptReleaseScheduled' discriminator: propertyName: type mapping: manual: '#/components/schemas/TrackingScriptReleaseManual' latest: '#/components/schemas/TrackingScriptReleaseLatest' scheduled: '#/components/schemas/TrackingScriptReleaseScheduled' ProjectGASettingsBase: allOf: - $ref: '#/components/schemas/GA_SettingsBase' - type: object properties: auto_revenue_tracking: type: boolean description: Attempt to pull revenue data from Google Analytics Revenue Tracking code. ProjectIntegrationGA3: allOf: - $ref: '#/components/schemas/ProjectGASettingsBase' - $ref: '#/components/schemas/IntegrationGA3' ProjectIntegrationGA4: allOf: - $ref: '#/components/schemas/ProjectGASettingsBase' - $ref: '#/components/schemas/IntegrationGA4' - type: object properties: no_wait_pageview: type: boolean description: Boolean indicating whether to wait for the page view event to complete before sending other events. GA_Settings: oneOf: - $ref: '#/components/schemas/ProjectIntegrationGA3' - $ref: '#/components/schemas/ProjectIntegrationGA4' discriminator: propertyName: type mapping: ga3: '#/components/schemas/ProjectIntegrationGA3' ga4: '#/components/schemas/ProjectIntegrationGA4' ProjectStatuses: description: 'The overall status of a project: - `active`: The project is active, and experiences within it can run and track data. - `inactive`: The project is inactive (archived or paused). No experiences within it will run, and no new data will be tracked. - `suspended`: The project (or account) has been suspended, typically due to billing issues or terms of service violations. Services are disabled. ' type: string enum: - active - inactive - suspended ProjectExpandable: readOnly: true anyOf: - type: integer description: Project ID to which the data belongs to - $ref: '#/components/schemas/Project' ExportProjectRequestData: type: object properties: includeProject: type: boolean default: true description: If true (default), includes the main project settings and configurations in the export. If false, only selected sub-entities (experiences, goals, etc.) might be exported. experiences: $ref: '#/components/schemas/ProjectExportObject' audiences: $ref: '#/components/schemas/ProjectExportObject' locations: $ref: '#/components/schemas/ProjectExportObject' goals: $ref: '#/components/schemas/ProjectExportObject' hypothesis: $ref: '#/components/schemas/ProjectExportObject' ProjectExportObject: type: object description: 'Defines filtering for a specific type of entity (e.g., experiences, goals) within a project export. Allows either an `include` list (only these IDs) or an `exclude` list (all IDs except these). If both are omitted, all items of that entity type are included. ' properties: include: type: array items: type: integer description: 'A list of specific entity IDs (e.g., experience IDs, goal IDs) to be *included* in the export. If provided, only these items will be exported for this entity type. Cannot be used with `exclude`. ' exclude: type: array items: type: integer description: 'A list of specific entity IDs to be *excluded* from the export. If provided, all items of this entity type except these will be exported. Cannot be used with `include`. ' ImportProjectRequestData: allOf: - type: object properties: file: type: string format: json description: 'The JSON file containing project data to be imported. ' required: - file CreateProjectRequestData: allOf: - $ref: '#/components/schemas/BaseProject' - type: object properties: domains: type: array items: $ref: '#/components/schemas/DomainToCreate' description: The list of websites included in this project. required: - name - $ref: '#/components/schemas/ProjectsRequestIncludeExpand' UpdateProjectRequestData: allOf: - $ref: '#/components/schemas/BaseProject' - type: object properties: domains: type: array items: $ref: '#/components/schemas/DomainExpandableRequest' description: 'The list of domains included in this project. If a domain ID is provided, that domain will just be updated. Otherwise the domain will be created. **Caution:** Any domain not in the provided list would be deleted from the project ' - $ref: '#/components/schemas/ProjectsRequestIncludeExpand' GeneratedDebugTokenDataResponse: type: object properties: data: $ref: '#/components/schemas/GenerateDebugTokenData' GenerateDebugTokenData: type: object readOnly: true properties: value: type: string ttl: type: integer description: Unix timestamp (UTC) indicating when this debug token will expire and become invalid. GetProjectsListRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/ProjectsListFilteringOptions' - $ref: '#/components/schemas/PageNumber' - $ref: '#/components/schemas/ProjectsRequestIncludeExpand' ProjectsRequestIncludeExpand: type: object properties: include: description: 'Specifies optional related data fields to include for each project in the list. Refer to the [Optional Fields](#tag/Optional-Fields) section. ' type: array items: $ref: '#/components/schemas/ProjectsListIncludeField' expand: description: 'Specifies linked objects to expand for each project in the list. Refer to the [Expanding Fields](#tag/Expandable-Fields) section. ' type: array items: $ref: '#/components/schemas/ProjectsListExpandFields' ProjectsListFilteringOptions: allOf: - $ref: '#/components/schemas/ResultsPerPage' - $ref: '#/components/schemas/SortDirection' - type: object properties: status: type: array nullable: true items: type: string enum: - active - inactive description: Filters projects by their status search: type: string maxLength: 200 nullable: true description: A search string that would be used to search against Project's name and description legacy_script: type: boolean nullable: true enum: - true - false description: Filters projects based on whether they use the legacy script (`true`) or the new script (`false`). tracking_script_release_type: type: array nullable: true items: $ref: '#/components/schemas/TrackingScriptReleaseTypes' description: Filters projects by their tracking script release type. tracking_script_version: type: object nullable: true description: 'Filters projects by their tracking script version. ' properties: is: type: string isNot: type: string only: description: 'Only retrieve projects with the given ids. ' type: array nullable: true items: type: integer maxItems: 100 except: description: 'Except projects with the given ids. ' type: array items: type: integer maxItems: 100 sort_by: type: string nullable: true default: id description: 'A value to sort projects by specific field(s) Defaults to **id** if not provided ' enum: - id - active_tests - project_name - project_type - status - used_visitors project_type: type: array nullable: true items: type: string enum: - web - fullstack description: Filters projects by their type. ProjectsListPersistentOptions: allOf: - $ref: '#/components/schemas/ProjectsListFilteringOptions' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/ProjectsListColumnNames' ProjectsListColumnNames: type: string description: Available columns for the projects list in the UI. enum: - id - project_name - project_type - active_tests - used_visitors - status GetProjectLiveDataRequestData: allOf: - $ref: '#/components/schemas/ProjectLiveFilteringOptions' - $ref: '#/components/schemas/LiveDataExpandParameter' ProjectLiveFilteringOptions: type: object description: Filters for the live data feed of a single project. properties: experiences: type: array nullable: true description: A list of Experience IDs to filter events for. Only events related to these experiences will be returned. items: type: integer event_types: type: array nullable: true items: $ref: '#/components/schemas/LiveDataEventTypes' goals: type: array nullable: true description: A list of Goal IDs to filter conversion/transaction events for. maxItems: 20 items: type: integer segments: nullable: true allOf: - $ref: '#/components/schemas/ReportingSegmentsFilters' ProjectLiveDataPersistentOptions: allOf: - $ref: '#/components/schemas/ProjectLiveFilteringOptions' - $ref: '#/components/schemas/LiveDataAutoRefreshSettings' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/ProjectLiveDataColumnNames' ProjectLiveDataColumnNames: type: string description: Available columns for the project-level live data feed in the UI. enum: - time - event - experience - variation - more_info ProjectsListIncludeField: $ref: '#/components/schemas/ProjectIncludeFields' ProjectIncludeFields: type: string enum: - global_javascript - domains - stats.usage - stats.active_experiences_count - stats.active_experiments_count - stats.experiences_count - stats.segments_count - stats.active_segments_count - stats.active_goals_count - stats.google_analytics - stats.visitor_data - stats.visitor_insights - default_goals - default_audiences - default_locations - settings.tracking_script.available_versions ProjectsListExpandFields: $ref: '#/components/schemas/ProjectExpandFields' ProjectExpandFields: type: string enum: - default_goals - default_audiences - default_locations SimpleProject: type: object properties: id: description: The unique numerical identifier of the project. type: integer name: description: The user-defined, friendly name of the project. type: string reporting_settings: type: object description: Essential reporting settings for the project. properties: currency_symbol: type: string description: "The default currency symbol used in reports for this project (e.g., \"$\", \"\u20AC\")." maxLength: 10 settings: type: object description: Essential general settings for the project. properties: time_zone: type: string description: The configured timezone for the project (e.g., "America/New_York"). utc_offset: $ref: '#/components/schemas/UTC_Offset' time_format: type: string description: Preferred time display format ('12h' or '24h') in the UI for this project. enum: - 12h - 24h SimpleProjectExpandable: oneOf: - type: integer description: Project ID - $ref: '#/components/schemas/SimpleProject' SDKKeyData: type: object properties: sdk_key: type: string ProjectHistoryRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/PageNumber' - $ref: '#/components/schemas/ProjectHistoryFilteringOptions' ProjectHistoryFilteringOptions: allOf: - $ref: '#/components/schemas/SortDirection' - $ref: '#/components/schemas/ResultsPerPage' - type: object properties: methods: type: array nullable: true items: $ref: '#/components/schemas/ChangeHistoryMethods' objects: type: array nullable: true items: $ref: '#/components/schemas/ChangeHistoryObjects' audiences: type: array nullable: true description: List of audiences id to get data by maxItems: 100 items: type: integer goals: type: array nullable: true description: List of goals id to get data by maxItems: 100 items: type: integer locations: type: array nullable: true description: List of locations id to get data by maxItems: 100 items: type: integer hypotheses: type: array nullable: true description: List of hypotheses id to get data by maxItems: 100 items: type: integer domains: type: array nullable: true description: List of domains id to get data by maxItems: 100 items: type: integer tags: type: array nullable: true description: List of tags id to get data by maxItems: 100 items: type: integer experiences: type: array nullable: true description: List of experiences id to get data by maxItems: 100 items: type: integer sort_by: type: string nullable: true default: timestamp description: 'A value to sort history list by specific field(s) Defaults to **timestamp** if not provided ' enum: - timestamp - project_id - event - object - $ref: '#/components/schemas/ChangeHistoryExpandParameter' ProjectHistoryPersistentOptions: allOf: - $ref: '#/components/schemas/ProjectHistoryFilteringOptions' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/ProjectHistoryColumnNames' ProjectHistoryColumnNames: type: string description: Available columns for the project change history log in the UI. enum: - timestamp - object_id - event - object - method - more_info BulkProjectIds: type: array description: A list of project unique numerical identifiers to be affected by a bulk operation. items: type: integer minItems: 1 maxItems: 100 BulkUpdateProjectsRequestData: type: object description: Request body for bulk updating settings (like tracking script version) for multiple projects. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkProjectIds' settings: type: object description: Project settings to be updated across the specified projects. additionalProperties: false properties: tracking_script: type: object description: Tracking script settings to apply, specifically the `current_version`. additionalProperties: false properties: current_version: type: string description: The target tracking script version string to apply to all selected projects. required: - id ReportingSegmentsBrowser: type: string description: 'The web browser used by the visitor. Used for segmenting reports to understand how experiences perform across different browsers. Knowledge Base: "Using Basic and Advanced Post segmentation". ' enum: - internet_explorer - chrome - firefox - safari - edge - other ReportingSegmentsCampaign: type: string description: 'The campaign name associated with the visitor''s session, typically derived from `utm_campaign` URL parameters. Allows report segmentation by marketing campaign. Knowledge Base: "How Do You Fill Medium, Keyword and Source Name?". ' ReportingSegmentsSource: type: string description: 'The traffic source that brought the visitor to the site (e.g., ''google'', ''facebook.com'', ''direct'', ''newsletter''). Derived from `utm_source` URL parameters or the HTTP referrer. Enables report segmentation by traffic source. Knowledge Base: "How Do You Fill Medium, Keyword and Source Name?". ' enum: - campaign - search - referral - direct - ai_tool ReportingSegmentsCountry: type: string description: 'The two-letter ISO 3166-1 alpha-2 country code of the visitor, determined by IP geolocation. Used for segmenting reports by country to analyze geographical performance. Knowledge Base: "How Do I Target by Geographic Location Like City, Region or Country?". ' maxLength: 2 minLength: 2 ReportingSegmentsVisitorType: type: string description: 'Classifies the visitor as either ''new'' or ''returning'' based on their site visit history (tracked by Convert cookies). - `new`: First-time visitor to the site (or no existing Convert cookie). - `returning`: Visitor has been to the site before. Allows report segmentation to compare behavior of new vs. returning users. Knowledge Base: "What is a New/Returning Visitor as Defined in an Experiment''s Audience?". ' enum: - new - returning ReportingSegmentsCustomSegment: description: 'The numerical ID of a custom Convert Audience (of type ''segmentation'') that the visitor is a member of. Allows report segmentation based on predefined custom segments (e.g., "High-Value Customers", "Engaged Users"). Knowledge Base: "Create Custom Segments". ' type: integer ReportingSegmentsDeviceCategories: type: string description: 'The category of device used by the visitor. Enables report segmentation by device type. - `iPhone`, `other_phones`, `all_phones`: Mobile phone categories. - `desktop`: Desktop or laptop computer. - `iPad`, `other_tablets`, `all_tablets`: Tablet categories. Note: Some devices might fall into multiple categories (e.g., an iPhone is both ''iPhone'' and ''all_phones''). Knowledge Base: "Targeting Mobile, Tablet, and Desktop". ' enum: - iPhone - all_phones - other_phones - desktop - iPad - all_tablets - other_tablets ReportingSegmentsFilters: type: object description: 'A collection of filters used to segment experience report data based on various visitor attributes and traffic sources. Applying these filters allows for deeper analysis of how different user groups interact with experience variations. Knowledge Base: "Using Basic and Advanced Post segmentation". ' properties: devices: type: array items: $ref: '#/components/schemas/ReportingSegmentsDeviceCategories' nullable: true browsers: description: Filter report data for visitors using one or more specified web browsers. type: array items: $ref: '#/components/schemas/ReportingSegmentsBrowser' nullable: true countries: description: Filter report data for visitors from one or more specified countries (using 2-letter ISO codes). type: array items: $ref: '#/components/schemas/ReportingSegmentsCountry' nullable: true visitor_types: description: Filter report data for 'new' or 'returning' visitors. type: array items: $ref: '#/components/schemas/ReportingSegmentsVisitorType' nullable: true campaigns: description: Filter report data for visitors attributed to one or more specified marketing campaign names (from `utm_campaign`). type: array items: $ref: '#/components/schemas/ReportingSegmentsCampaign' nullable: true custom_segments: description: Filter report data for visitors belonging to one or more specified custom Convert Audience segments (by segment ID). type: array items: $ref: '#/components/schemas/ReportingSegmentsCustomSegment' nullable: true sources: description: Filter report data for visitors from one or more specified traffic sources (e.g., 'direct', 'search', 'referral'). type: array items: $ref: '#/components/schemas/ReportingSegmentsSource' nullable: true ExperienceAggregatedReportBase: type: object properties: stats_methodology: $ref: '#/components/schemas/SE_ProcTypes' variations_data: $ref: '#/components/schemas/ExperienceReportVariationsData' ExperienceAggregatedReportFrequentist: allOf: - $ref: '#/components/schemas/ExperienceAggregatedReportBase' - type: object properties: stats_methodology: type: string enum: - frequentist reportData: type: array description: List of data for each of the analyzed goals items: $ref: '#/components/schemas/ExperienceAggregatedGoalReportFrequentist' ExperienceAggregatedReportBayesian: allOf: - $ref: '#/components/schemas/ExperienceAggregatedReportBase' - type: object properties: stats_methodology: type: string enum: - bayesian reportData: type: array description: List of data for each of the analyzed goals items: $ref: '#/components/schemas/ExperienceAggregatedGoalBayesian' ExperienceAggregatedMetricReportFrequentist: oneOf: - $ref: '#/components/schemas/ExperienceAggregatedMetricFrequentist' - $ref: '#/components/schemas/ExperienceAggregatedMetricNoStatistics' discriminator: propertyName: metric_type mapping: conversion_rate: '#/components/schemas/ExperienceAggregatedMetricFrequentist' avg_revenue_visitor: '#/components/schemas/ExperienceAggregatedMetricFrequentist' avg_products_ordered_visitor: '#/components/schemas/ExperienceAggregatedMetricFrequentist' average_order_value: '#/components/schemas/ExperienceAggregatedMetricNoStatistics' average_products_per_order: '#/components/schemas/ExperienceAggregatedMetricNoStatistics' ExperienceAggregatedMetricReportBayesian: oneOf: - $ref: '#/components/schemas/ExperienceAggregatedMetricBayesian' - $ref: '#/components/schemas/ExperienceAggregatedMetricNoStatistics' discriminator: propertyName: metric_type mapping: conversion_rate: '#/components/schemas/ExperienceAggregatedMetricBayesian' avg_revenue_visitor: '#/components/schemas/ExperienceAggregatedMetricBayesian' avg_products_ordered_visitor: '#/components/schemas/ExperienceAggregatedMetricBayesian' average_order_value: '#/components/schemas/ExperienceAggregatedMetricNoStatistics' average_products_per_order: '#/components/schemas/ExperienceAggregatedMetricNoStatistics' ExperienceAggregatedReport: oneOf: - $ref: '#/components/schemas/ExperienceAggregatedReportFrequentist' - $ref: '#/components/schemas/ExperienceAggregatedReportBayesian' discriminator: propertyName: stats_methodology mapping: frequentist: '#/components/schemas/ExperienceAggregatedReportFrequentist' bayesian: '#/components/schemas/ExperienceAggregatedReportBayesian' ExperienceAggregatedGoalReportBase: type: object properties: goal_id: type: integer description: The unique numerical identifier of the conversion goal for which these metrics are reported. srm: description: 'Sample Ratio Mismatch flag for this goal across all variations. `true` if a statistically significant mismatch in visitor distribution was detected compared to the intended traffic allocation, potentially indicating an issue with the experiment setup or tracking for this goal. KB: "What is SRM?". ' type: boolean nullable: true srm_pvalue: description: 'The p-value from the Chi-square test used to detect Sample Ratio Mismatch for this goal. A low p-value (e.g., < 0.01 or < 0.05) suggests a significant mismatch. KB: "What is SRM?" - "Understanding SRM p-values". ' type: number nullable: true variations: type: array description: An array containing detailed performance metrics for each variation specifically for this goal. items: type: object properties: id: type: integer description: The unique numerical identifier of the variation. visitors: type: integer description: The number of unique visitors who were exposed to this variation and were eligible to convert on this goal. conversion_data: type: object deprecated: true description: (Deprecated) Data for conversion rate metric. Use the `metrics` array instead. properties: conversions: type: integer description: Number of recorded conversions for the variation conversion_rate: type: number description: Observed Conversion rate conversion_rate_change: type: number description: The observed difference in percentage between conversion rate of this variation and the one of the baseline conversion_rate_interval: type: number description: The estimated conversion rate interval represented by the value that needs to be added/substracted from the conversion rate in order to obtain the interval confidence: type: number description: Observed statistical confidence value statistically_significant: type: boolean description: Whether the observed change in conversion rate is statistically significant or not. revenue_data: type: object deprecated: true nullable: true description: (Deprecated) Data for average revenue per visitor metric. Use the `metrics` array instead. properties: revenue_per_visitor: type: number description: Observed average revenue per visitor total_revenue: type: number description: Total revenue tracked for this variation revenue_per_visitor_interval: type: number description: Value that needs to be added/substracted from the revenue_per_visitor in order to get the margins of the error interval confidence: type: number description: Observed statistical confidence value revenue_per_visitor_change: type: number description: The observed difference in percentage between revenue_per_visitor for this variation and the one for the baseline statistically_significant: type: boolean description: Whether the observed change in revenue_per_visitor rate is statistically significant or not. products_data: type: object deprecated: true nullable: true description: (Deprecated) Data for average ordered products count per visitor. Use the `metrics` array instead. properties: products_per_visitor: type: number description: Observed average products ordered per visitor total_products: type: number description: Total products ordered tracked for this variation products_per_visitor_interval: type: number description: Value that needs to be added/substracted from the products_per_visitor in order to get the margins of the error interval confidence: type: number description: Observed statistical confidence value products_per_visitor_change: type: number description: The observed difference in percentage between products_per_visitor for this variation and the one for the baseline statistically_significant: type: boolean description: Whether the observed change in products_per_visitor rate is statistically significant or not. metrics: type: array description: 'A list of detailed metric calculations for this variation concerning this specific goal. Each object in the array corresponds to a primary metric type (e.g., ''conversion_rate'', ''avg_revenue_visitor'') and contains the relevant statistical values (e.g., observed value, change from baseline, confidence/chance_to_win, interval). The structure of each metric object depends on whether the report is Frequentist or Bayesian. ' ExperienceAggregatedGoalReportFrequentist: allOf: - $ref: '#/components/schemas/ExperienceAggregatedGoalReportBase' - type: object properties: variations: type: array items: type: object properties: metrics: type: array items: $ref: '#/components/schemas/ExperienceAggregatedMetricReportFrequentist' ExperienceAggregatedGoalBayesian: allOf: - $ref: '#/components/schemas/ExperienceAggregatedGoalReportBase' - type: object properties: variations: type: array items: type: object properties: metrics: type: array items: $ref: '#/components/schemas/ExperienceAggregatedMetricReportBayesian' MetricTypes: type: string description: 'The primary types of performance metrics calculated by the reporting engine for each goal. - `conversion_rate`: The percentage of visitors who completed the goal (Conversions / Visitors). - `avg_revenue_visitor`: Average Revenue Per Visitor (RPV = Total Revenue / Total Visitors). Applicable for revenue goals. - `avg_products_ordered_visitor`: Average Products Per Visitor (APPV = Total Products Ordered / Total Visitors). Applicable for revenue goals tracking product counts. - `average_order_value`: Average Order Value (AOV = Total Revenue / Total Conversions). Applicable for revenue goals tracking order value. - `average_products_per_order`: Average Products Per Order (APPO = Total Products Ordered Per Visitor / Total Conversions). Applicable for revenue goals tracking product counts. Knowledge Base: "Understanding Report Metrics in Convert". ' enum: - conversion_rate - avg_revenue_visitor - avg_products_ordered_visitor - average_order_value - average_products_per_order BaseMetricNoStatistics: type: object properties: metric_total: type: integer description: 'The total sum contributing to this metric for this variation and goal. - For `conversion_rate`: Total number of conversions. - For `avg_revenue_visitor`: Total revenue recorded. - For `avg_products_ordered_visitor`: Total number of products ordered. - For `average_order_value`: Total revenue recorded. - For `average_products_per_order`: Total number of products ordered. ' metric_value: type: number description: The observed value of this metric (e.g., 0.05 for a 5% conversion rate, 2.50 for $2.50 RPV). metric_change: type: number description: 'The percentage difference in this metric''s value for the current variation compared to the baseline variation. Positive indicates improvement, negative indicates decline. (e.g., 0.20 for a 20% improvement). Knowledge Base: "Understanding Report Metrics in Convert" - "Improvement". ' BaseMetric: allOf: - $ref: '#/components/schemas/BaseMetricNoStatistics' - type: object properties: metric_interval: type: number description: 'The half-width of the confidence (Frequentist) or credible (Bayesian) interval for the `metric_value` or `metric_change`. For example, if `metric_value` is 0.05 and `metric_interval` is 0.01, the interval is [0.04, 0.06]. This represents the range within which the true value of the metric likely lies. ' ExperienceAggregatedMetricFrequentist: allOf: - type: object properties: metric_type: $ref: '#/components/schemas/MetricTypes' confidence: type: number description: Observed statistical confidence value statistically_significant: type: boolean description: Whether the observed change in conversion rate is statistically significant or not. estimated_progress: description: 'Estimated Test Progress in terms of relative remaining samples vs the total sample size needed to complete the test (at the current MDE). ' type: number nullable: true remaining_samples: description: Remaining needed samples type: integer nullable: true normality_conditions_met: deprecated: true description: Normality Conditions Met type: boolean observed_power: description: Observed Power type: number nullable: true powerful: description: Powerful type: boolean nullable: true done: description: Set to true when the tests conditions are met, mainly when the test is complete according to power calculations. type: boolean srm: description: Sample Ratio Mismatch at the pairwise level (variant and control). type: boolean nullable: true srm_pvalue: description: P value for the Sample Ratio Mismatch test at the pairwise level. type: number nullable: true required: - metric_type - $ref: '#/components/schemas/BaseMetric' ExperienceAggregatedMetricBayesian: allOf: - type: object properties: metric_type: $ref: '#/components/schemas/MetricTypes' chance_to_win: description: Chance to win as a number 0-100 type: number expected: description: Expected type: number nullable: true risk: description: Risk type: array items: type: number nullable: true estimated_progress: description: 'Estimated Test Progress in terms of relative remaining samples vs the total sample size needed to complete the test (at the current MDE). ' type: number nullable: true done: description: Set to true when the posterior both exceeds the decision threshold in its 'chance to win' and remains below the risk threshold in its relative risk assessment, indicating a strong and acceptably safe performance. type: boolean srm: description: Sample Ratio Mismatch at the pairwise level (variant and control). type: boolean nullable: true srm_pvalue: description: P value for the Sample Ratio Mismatch test at the pairwise level. type: number nullable: true required: - metric_type - $ref: '#/components/schemas/BaseMetric' ExperienceAggregatedMetricNoStatistics: allOf: - type: object properties: metric_type: type: string enum: - average_order_value - average_products_per_order required: - metric_type - $ref: '#/components/schemas/BaseMetricNoStatistics' ExperienceDailyReport: type: object properties: variations_data: $ref: '#/components/schemas/ExperienceReportVariationsData' reportData: type: object description: Contains the daily statistics for the requested goal and metric. properties: variations: type: array description: A list, where each item contains the daily performance data for one variation. items: type: object description: Daily statistics for a single variation. properties: id: description: The unique numerical identifier of the variation. type: number stats: type: array description: An array of data points, each representing one day's performance for this variation. items: allOf: - $ref: '#/components/schemas/StatsDataPoint' - type: object properties: totals: description: 'Total number of conversions/sum of revenue/products ordered for this variation, depending on the reporting metric as follows: - **conversion_rate requested** - this value will hold the number of conversions - **avg_revenue_per_visitor** - this value will hold the sum of the revenue - **avg_products_ordered_per_visitor** - this value will hold the sum of the number of ordered products - **average_order_value** - this value will hold the sum of the average order value - **average_products_per_order** - this value will hold the sum of the average products per order ' type: number visitors: description: Count of visitors that saw this variation type: number extra: type: array description: Additional daily statistics aggregated across all variations for comparison (e.g., total daily visitors for the whole experiment). items: $ref: '#/components/schemas/ExperienceDailyReportExtraDataItem' ExperienceDailyReportExtraDataItem: type: object properties: type: $ref: '#/components/schemas/ReportExtraStatsTypes' stats: type: array description: An array of data points, each representing one day's aggregated value for this `type`. items: $ref: '#/components/schemas/StatsDataPoint' StatsDataPoint: type: object description: Represents a single data point in a time series, typically for a specific day. properties: timestamp: description: Unix timestamp (UTC, seconds since epoch) representing the start of the day for this data point. type: number value: description: The numerical value of the metric or statistic for this data point (e.g., daily conversion rate, daily visitor count). type: number format: double ReportExtraStatsTypes: description: Types of aggregated daily statistics that can be included in the 'extra' section of a daily report. type: string enum: - total_visitors - avg_conversion_rate - avg_revenue_visitor - avg_products_ordered ExperienceDailyTrafficAllocationReport: type: object description: Provides a day-by-day breakdown of traffic allocation percentages for each variation in an experience, typically used for MAB experiments. properties: variations_data: $ref: '#/components/schemas/ExperienceReportVariationsData' reportData: type: object description: Contains the daily traffic allocation data. properties: variations: type: array description: A list, where each item contains the daily traffic allocation data for one variation. items: type: object description: Daily traffic allocation for a single variation. properties: id: description: The unique numerical identifier of the variation. type: number stats: type: array description: An array of data points, each representing the traffic allocation percentage for this variation on a specific day. items: $ref: '#/components/schemas/StatsDataPoint' ExperienceReportSettingsData: description: Data structure containing the specific reporting settings configured for an experience. type: object properties: data: type: object properties: campaigns: description: A list of unique marketing campaign names (from `utm_campaign`) that brought visitors to this experience. Includes visitor counts per campaign. Useful for segmenting results. type: array readOnly: true items: type: object properties: name: description: The campaign name. type: string visitors_count: description: The number of visitors in this experience attributed to this campaign. type: number custom_segments: description: A list of custom Convert Audience segments (of type 'segmentation') that visitors to this experience belonged to. Useful for post-test segmentation. type: array readOnly: true items: $ref: '#/components/schemas/SimpleAudienceSegment' ExperienceReportVariationsData: type: array description: An array containing basic identifying information for each variation in the experience (ID, name, baseline status, traffic distribution). items: $ref: '#/components/schemas/ExperienceVariationBaseExtended' TimeRangeRequestData: type: object description: Parameters for defining a specific time range for report data retrieval. properties: utc_offset: $ref: '#/components/schemas/UTC_Offset' start_time: type: number nullable: true description: Unix timestamp (seconds since epoch) for the beginning of the reporting period. If null, data from the experience start is typically used. Should be interpreted with `utc_offset`. end_time: type: number nullable: true description: Unix timestamp (seconds since epoch) for the end of thereporting period. If null, data up to the current time is typically used. Should be interpreted with `utc_offset`. BaseReportRequestData: allOf: - $ref: '#/components/schemas/TimeRangeRequestData' - type: object description: Base Parameters needed to drill down the reports. properties: segments: $ref: '#/components/schemas/ReportingSegmentsFilters' stats_engine_processing: $ref: '#/components/schemas/SE_ProcSettings' GetExperienceAggregatedReportRequestData: allOf: - type: object description: Parameters needed to drill down the report. properties: goals: type: array description: 'A list of goal Id''s for which to return the reporting data. If no ID is provided, the list of goals attached to the experience is being used; ' items: type: integer nullable: true metrics: description: The list of metrics to return. If not provided, all available metrics will be returned. type: array items: $ref: '#/components/schemas/MetricTypes' nullable: true - $ref: '#/components/schemas/BaseReportRequestData' GetExperienceDailyReportRequestData: allOf: - type: object description: Parameters needed to drill down the report. properties: goal: type: number description: Goal's ID for which to return the reporting data report_type: $ref: '#/components/schemas/DailyReportTypes' metric: $ref: '#/components/schemas/DailyReportMetrics' segments: $ref: '#/components/schemas/ReportingSegmentsFilters' - $ref: '#/components/schemas/BaseReportRequestData' DailyReportTypes: type: string description: Determines how daily data is aggregated in time-series reports. enum: - cumulative - non_cumulative DailyReportMetrics: type: string description: The specific performance metric to be displayed in a daily report. enum: - conversion_rate - avg_revenue_per_visitor - avg_products_ordered_per_visitor - average_order_value - average_products_per_order GetExperienceDailyTrafficAllocationRequestData: allOf: - $ref: '#/components/schemas/TimeRangeRequestData' ExportExperienceReportRequestData: allOf: - type: object description: Parameters needed to drill down the report. properties: report_type: type: string default: csv_aggregated description: 'Type of the exported report: - csv_aggregated - export in CSV format the number of visitors and metrics values aggregated per variation for the whole reported period - csv_aggregated_tabular - export in CSV format same as above but with headings tabular for export - csv_daily - export in CSV format the number of visitors and metrics values per day, per variation for the whole reported period - csv_daily_tabular - export in CSV format same as above but with headings tabular for export ' enum: - csv_aggregated - csv_aggregated_tabular - csv_daily - csv_daily_tabular data_type: type: string default: non_cumulative description: 'Type of data the exported report (csv_daily only) ' enum: - cumulative - non_cumulative nullable: true goals: type: array description: 'A list of goal Id''s for which to return the reporting data. If no ID is provided, the list of goals attached to the experience is being used. Max 10 goals at one time available for csv_daily type. ' items: type: integer nullable: true - $ref: '#/components/schemas/BaseReportRequestData' ExperienceReportExportResponseData: type: object properties: data: description: Contains the URL from which the generated report file can be downloaded and its expiration time. type: object properties: download_url: description: A temporary, secure URL to download the generated report file (e.g., CSV, PDF). type: string expire_at: description: Unix timestamp (UTC) indicating when the `download_url` will expire and the file will no longer be accessible. type: number RemoveExperienceReportRequestData: allOf: - $ref: '#/components/schemas/BaseReportRequestData' - type: object description: Parameters needed to drill down the report. properties: events: type: array description: List of the events that would be targeted by the delete operation. If not provided, all the events would be targeted. items: oneOf: - $ref: '#/components/schemas/RemoveExperienceReportEventTypeViewExperience' - $ref: '#/components/schemas/RemoveExperienceReportEventTypeConversion' - $ref: '#/components/schemas/RemoveExperienceReportEventTypeTransaction' minItems: 1 simulate: type: boolean default: true description: When simulate - true is passed, it will only return back an object with the numbers of how many records will be deleted, instead of deleting any records required: - start_time - end_time RemoveExperienceReportResponseData: type: object properties: data: description: An array detailing the number of records for each event type that were (or would be) deleted. type: array items: $ref: '#/components/schemas/RemoveExperienceReportResponseDataItem' RemoveExperienceReportResponseDataItem: type: object properties: event: $ref: '#/components/schemas/ExperienceReportRawDataEvents' count: type: integer description: The number of records of this event type that were (or would be) deleted based on the request criteria. ExperienceAggregatedReportResponseData: type: object properties: data: $ref: '#/components/schemas/ExperienceAggregatedReport' ExperienceDailyReportResponseData: type: object properties: data: $ref: '#/components/schemas/ExperienceDailyReport' ExperienceDailyTrafficAllocationResponseData: type: object properties: data: $ref: '#/components/schemas/ExperienceDailyTrafficAllocationReport' ExperienceReportRawDataEvents: $ref: '#/components/schemas/ExportExperienceRawDataEvents' ExportExperienceRawDataEvents: description: 'Specifies the type of raw tracking events to be included in an export or targeted for removal. - `view_experience`: Events logged when a visitor is first bucketed into an experience variation. - `conversion`: Events logged when a visitor triggers a standard conversion goal. - `transaction`: Events logged when a visitor triggers a revenue goal (includes transaction details). ' type: string enum: - view_experience - conversion - transaction RemoveExperienceReportEventTypeViewExperience: description: 'Specifies deletion of ''view_experience'' events. ' type: object properties: type: type: string description: Must be 'view_experience'. enum: - view_experience required: - type RemoveExperienceReportEventTypeConversion: description: 'Specifies deletion of ''conversion'' events, optionally filtered by specific goals. ' type: object properties: type: type: string description: Must be 'conversion'. enum: - conversion goals: type: array description: '(Optional) A list of Goal IDs. If provided, only conversion events for these specific goals will be deleted. If omitted, conversion events for all goals (matching other criteria like date range/segments) might be deleted. ' items: type: integer nullable: true required: - type RemoveExperienceReportEventTypeTransaction: description: 'Specifies deletion of ''transaction'' (revenue) events, optionally filtered by specific goals and revenue amounts. ' type: object properties: type: type: string description: Must be 'transaction'. enum: - transaction goals: type: array description: '(Optional) A list of Goal IDs. If provided, only transaction events for these specific revenue goals will be deleted. ' items: type: integer nullable: true revenue_start_value: type: number description: (Optional) Delete only transactions where the revenue amount is greater than or equal to this value. nullable: true revenue_end_value: type: number description: (Optional) Delete only transactions where the revenue amount is less than or equal to this value. nullable: true required: - type ExportExperienceRawDataRequestData: allOf: - type: object description: Parameters needed to generate the export. properties: events: type: array description: List of events to export items: $ref: '#/components/schemas/ExportExperienceRawDataEvents' goals: type: array description: 'A list of goal Id''s for which to return the tracking data. If no ID is provided, the list of goals attached to the experience is being used. ' items: type: integer nullable: true - $ref: '#/components/schemas/BaseReportRequestData' ExportExperienceRawDataResponseData: type: object properties: data: description: Contains the ID of the asynchronous job processing the raw data export. type: object properties: jobId: description: 'A unique identifier for the background job that is preparing the raw data export. The user is typically notified (e.g., via email) with a download link once the job is complete. ' type: string ExperienceReportPersistentOptions: type: object properties: sections: type: array nullable: true description: 'Specifies which sections of the experience report (e.g., ''summary'', ''complete_overview'') are visible in the UI and their display order. ' items: allOf: - $ref: '#/components/schemas/BaseUiSectionPreference' - type: object properties: name: $ref: '#/components/schemas/ExperienceReportSectionNames' ExperienceReportSectionNames: type: string description: Identifiers for the different collapsible/reorderable sections within the experience report UI. enum: - summary - complete_overview - quick_overview - goal_details AccessRolesListResponseData: type: object properties: data: $ref: '#/components/schemas/AccessRolesList' AccessRolesList: type: array description: A list of access role objects, each detailing a role name and its associated permissions. items: $ref: '#/components/schemas/AccessRole' AccessRole: type: object properties: name: type: string permissions: $ref: '#/components/schemas/RolePermissions' RolePermissions: type: object properties: account: type: object properties: manage_addons: type: boolean manage_sso: type: boolean manage_api_keys: type: boolean manage_blocked_ips: type: boolean edit: type: boolean billing: type: object properties: managePlan: type: boolean manage_billing: type: boolean manage_payment: type: boolean request_payment: type: boolean feature: $ref: '#/components/schemas/CommonBasicPermissions' livedata: type: object properties: view_account_livedata: type: boolean view_project_livedata: type: boolean view_experience_livedata: type: boolean history: type: object properties: view_account_history: type: boolean view_project_history: type: boolean view_experience_history: type: boolean collaborator: type: object properties: view: type: boolean crud: type: boolean project: allOf: - $ref: '#/components/schemas/CommonBasicPermissions' - type: object properties: import: type: boolean export: type: boolean domain: $ref: '#/components/schemas/CommonBasicPermissions' tag: $ref: '#/components/schemas/CommonBasicPermissions' goal: allOf: - $ref: '#/components/schemas/CommonBasicPermissions' - type: object properties: clone: type: boolean experience: allOf: - $ref: '#/components/schemas/CommonBasicPermissions' - type: object properties: edit_running: type: boolean clone: type: boolean pauseplay: type: boolean location: allOf: - $ref: '#/components/schemas/CommonBasicPermissions' - type: object properties: edit_running: type: boolean variation: type: object properties: pauseplay: type: boolean changebaseline: type: boolean audience: allOf: - $ref: '#/components/schemas/CommonBasicPermissions' - type: object properties: edit_running: type: object report: type: object properties: view: type: boolean fulledit: type: boolean nochangeedit: type: boolean hypothesis: allOf: - $ref: '#/components/schemas/CommonBasicPermissions' - type: object properties: convert: type: boolean knowledge_base: $ref: '#/components/schemas/CommonBasicPermissions' observation: $ref: '#/components/schemas/CommonBasicPermissions' CommonBasicPermissions: type: object properties: add: type: boolean edit: type: boolean view: type: boolean delete: type: boolean AccessRoleNames: type: string description: 'The predefined names for user access roles within the Convert system. Each role grants a specific set of permissions. - `owner`: Highest level, full control over account, billing, users, and all projects. Typically the account creator. - `account_manager`: Broad administrative rights over the account, often including billing and user management, but might not be able to delete the account itself. - `admin`: Full control over projects they are assigned to, including creating/editing/deleting experiences, goals, audiences, and managing project settings. May also manage project-level collaborators. - `browse`: Read-only access. Can view experiences, reports, and settings but cannot make changes. - `edit`: Can create and modify entities like experiences, goals, audiences within assigned projects, but typically cannot activate/publish experiences or manage project settings. - `publish`: Can do everything an ''editor'' can, plus activate/pause/complete experiences. - `review`: Can view and comment, but not make direct changes. Suited for stakeholders who need to approve or provide feedback. Knowledge Base: "Collaborators - Share With Multiple Users / Accounts" (describes access levels). ' enum: - owner - account_manager - admin - browse - edit - publish - review AccessRoleNamesNoOwner: type: string description: Access roles that can be assigned to collaborators or API keys (excludes the 'owner' role, which is typically unique to the account creator). enum: - admin - account_manager - browse - edit - publish - review SdkKeysListResponseData: type: object description: Response containing a list of SDK keys defined for a specific Full Stack project, along with pagination details if applicable. properties: data: $ref: '#/components/schemas/SdkKeysList' SdkKeysList: type: array description: A list of SDK key objects. items: $ref: '#/components/schemas/SdkKey' SdkKeyStatuses: type: string enum: - enabled - disabled description: Indicates whether the SDK key is active and can be used for API authentication. When disabled, all requests using this key will be rejected. default: enabled SdkKey: type: object description: 'Defines an SDK key used by Convert''s Full Stack SDKs (e.g., Node.js, JavaScript) to securely fetch project configurations (features, experiments) and send tracking data from server-side applications or rich client-side apps. Each SDK key is typically scoped to a specific `environment` within a Full Stack project. Knowledge Base: "Full Stack Experiments on Convert", "Implementing Convert''s Full Stack JavaScript SDK: Real-World Examples". ' properties: name: type: string description: A user-defined, friendly name for the SDK key to help identify its purpose or the application/service using it (e.g., "Production Backend API", "Staging iOS App"). maxLength: 100 sdk_key: type: string description: "Unique identifier used to authenticate requests to Convert's serving API endpoints. This key is required\ \ to fetch experiments, personalizations and other serving data via the \nAPI (see /doc/serving). Generated automatically\ \ when creating a new SDK key.\n" readOnly: true sdk_secret: type: string description: "Secret key used for SDK authentication. This value is only returned in full when the SDK key is first\ \ created. \nIn subsequent GET requests, the secret will be partially redacted (e.g., \"abc12*****123\") for security\ \ purposes.\nWhen this is null, the SDK key can be used without authentication (public access).\n" nullable: true readOnly: true environment: type: string description: 'The specific environment within the Full Stack project that this SDK key is associated with (e.g., "production", "development", "staging"). The SDK will fetch configurations relevant to this environment. This must match one of the environments defined at the project level. KB: "The Environments Feature". ' status: $ref: '#/components/schemas/SdkKeyStatuses' selected_default: type: boolean description: 'If true, this SDK key is marked as the default for its environment within the project. Only one SDK key can be default per project environment. When a key is set as default, any previously default key for the same environment will be automatically unset. ' SdkKeysListPersistentOptions: type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/SdkKeysListColumnNames' SdkKeysListColumnNames: type: string description: Available columns for the sdk keys list in the UI. enum: - name - sdk_key - environment - status CreateSdkKeyRequestData: allOf: - $ref: '#/components/schemas/SdkKey' - type: object required: - name - environment description: 'Request payload for creating a new SDK key. The SDK key will be automatically generated upon creation and returned in the response. Required fields must be provided to successfully create the key. ' properties: has_secret: type: boolean description: Whether the SDK key should have a secret key. When true, a secret key will be generated and returned in the response. default: true writeOnly: true UpdateSdkKeyRequestData: allOf: - $ref: '#/components/schemas/SdkKey' - description: 'Request payload for updating an existing SDK key. This endpoint supports partial updates, allowing you to modify specific fields while keeping others unchanged. Only the fields you want to update need to be included in the request body. ' SessionsListResponseData: type: object description: Response containing a list of recorded raw visitor sessions for a project, along with pagination details. (This endpoint seems to be for general session data, distinct from Convert Signals). properties: data: $ref: '#/components/schemas/SessionsList' extra: allOf: - type: object properties: tk: type: string nullable: true description: Extra property SessionsList: type: array description: A list of raw session objects. items: $ref: '#/components/schemas/Session' Session: type: object properties: id: type: integer description: The unique numerical identifier for this raw session. readOnly: true SignalSessionsListResponseData: type: object description: "Response containing a list of Convert Signals\u2122 sessions (highlighting user frustrations), along with\ \ pagination and filtering metadata." properties: data: $ref: '#/components/schemas/SignalSessionsList' extra: allOf: - type: object properties: tk: type: string nullable: true description: Extra property - $ref: '#/components/schemas/Extra' SignalSessionsList: type: array description: "A list of Convert Signals\u2122 session objects. Each object represents a recorded session where user\ \ frustration or usability issues were detected." items: $ref: '#/components/schemas/SignalSession' SignalSession: type: object properties: id: type: string description: "The unique identifier for this Convert Signals\u2122 session recording." readOnly: true duration: type: integer description: The total duration of the recorded session in seconds. visited_pages: type: array items: type: object properties: url: type: string duration: type: integer timestamp: type: integer format: int64 visited_pages_count: type: integer description: The total number of unique pages visited during this session. entry_page: type: string description: The URL of the first page visited in this session (landing page for the session). exit_page: type: string description: The URL of the last page visited before the session ended or the visitor exited. session_start_time: type: integer format: int64 description: Unix timestamp (UTC) indicating when this session recording started. device: type: string description: The type of device used by the visitor during this session (e.g., "Desktop", "Mobile", "Tablet"). browser: type: string description: The web browser used by the visitor (e.g., "Chrome", "Firefox", "Safari"). country_code: type: string description: The two-letter ISO country code of the visitor's location, based on IP geolocation. watched: type: boolean description: True if this session recording has been watched by a user in the Convert UI. GetSessionsListRequestData: allOf: - $ref: '#/components/schemas/SessionsListFilteringOptions' SessionsListFilteringOptions: allOf: - $ref: '#/components/schemas/TimeRange' - type: object properties: tags: type: object nullable: true additionalProperties: type: string description: 'The tags object containing key-value pairs where each key is the tag name and the value is a string representing the tag''s value. ' example: property1: value1 property2: value2 GetSignalSessionsListRequestData: $ref: '#/components/schemas/SignalSessionsListFilteringOptions' SignalSessionsListFilteringOptions: allOf: - $ref: '#/components/schemas/TimeRange' - $ref: '#/components/schemas/PageNumber' - $ref: '#/components/schemas/ResultsPerPage' - $ref: '#/components/schemas/OnlyCount' - type: object properties: experience: type: object additionalProperties: false nullable: true properties: id: type: integer description: The ID of the experience to filter by variation_id: type: integer description: The ID of the variation to filter by location_id: type: integer nullable: true description: The ID of the location to filter by starred: type: string nullable: true watched: type: string nullable: true country: type: object nullable: true additionalProperties: false properties: is: type: array items: type: string isNot: type: array items: type: string os: type: object additionalProperties: false nullable: true properties: is: type: array items: type: string isNot: type: array items: type: string browser: type: object nullable: true additionalProperties: false properties: is: type: array items: type: string isNot: type: array items: type: string devices: type: object nullable: true additionalProperties: false properties: is: type: array items: type: string isNot: type: array items: type: string containsPage: type: string nullable: true notContainsPage: type: string nullable: true duration: type: object nullable: true additionalProperties: false description: 'The duration of the signal session in seconds ' properties: min: type: integer max: type: integer pageCount: type: object nullable: true additionalProperties: false properties: min: type: integer max: type: integer entryPage: type: string nullable: true exitPage: type: string nullable: true referrerURLs: type: array items: type: string nullable: true trafficChannels: type: array items: type: string nullable: true adCampaignLabels: type: array items: type: string nullable: true recordingId: type: string nullable: true SignalSessionsListPersistentOptions: allOf: - $ref: '#/components/schemas/SignalSessionsListFilteringOptions' - type: object properties: columns: type: array nullable: true description: 'Sorted list of columns to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/SignalSessionsListColumnNames' SignalSessionsListColumnNames: type: string description: "Available columns for the Convert Signals\u2122 sessions list in the UI." enum: - id - duration - visited_pages - location - date - watched GetTagsListRequestData: allOf: - $ref: '#/components/schemas/TagsListDataOptions' - $ref: '#/components/schemas/PageNumber' - type: object properties: only: description: 'Only retrieve tags with the given ids. ' type: array nullable: true items: type: integer maxItems: 100 except: description: 'Except tags with the given ids. ' type: array items: type: integer maxItems: 100 search: type: string maxLength: 100 nullable: true description: A search string that would be used to search against Tag's name TagsListResponseData: type: object description: Response containing a list of tags defined within a project, along with pagination details if applicable. properties: data: $ref: '#/components/schemas/TagsList' extra: $ref: '#/components/schemas/Extra' TagsList: type: array items: $ref: '#/components/schemas/Tag' Tag: type: object description: 'Represents a tag (keyword or label) that can be associated with various Convert entities like experiences, goals, audiences, hypotheses, and observations. Tags help organize and categorize these entities for easier filtering, searching, and management. Knowledge Base: "Adding tags to your Experiences". ' properties: id: type: integer readOnly: true description: The unique numerical identifier for the tag. name: type: string description: The user-defined name of the tag (e.g., "Q3 Campaigns", "Homepage Tests", "High Priority", "Mobile Specific"). This is the primary identifier shown in the UI. maxLength: 100 description: type: string description: (Optional) A brief explanation of the tag's purpose or the criteria for its application. maxLength: 200 nullable: true TagToCreate: allOf: - $ref: '#/components/schemas/Tag' required: - name 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' TagExpandableRequest: description: 'Represents a tag when associating it with another entity (like an experience or goal) during a create or update operation. Can be either the existing `integer` ID of the tag, or a `TagToCreate` object if a new tag should be created and associated on the fly. ' anyOf: - type: integer description: Tag ID - $ref: '#/components/schemas/TagToCreate' CreateTagRequestData: allOf: - $ref: '#/components/schemas/TagToCreate' UpdateTagRequestData: allOf: - $ref: '#/components/schemas/Tag' TagsListDataOptions: allOf: - $ref: '#/components/schemas/ResultsPerPage' BulkTagsIds: type: array description: A list of tag unique numerical identifiers to be affected by a bulk delete operation. items: type: integer minItems: 1 maxItems: 100 BulkDeleteTagRequestData: type: object description: Request body for bulk deleting multiple tags. Contains a list of tag IDs to be permanently removed. additionalProperties: false properties: id: $ref: '#/components/schemas/BulkTagsIds' required: - id AuthRequestDataBase: type: object description: Base structure for authentication requests in a cookie-based flow. required: - requestType properties: username: type: string requestType: type: string enum: - initiatePasswordAuth - provideMfaCodeAuth - confirmNewPasswordAuth InitiatePasswordAuthRequestData: allOf: - $ref: '#/components/schemas/AuthRequestDataBase' - type: object properties: requestType: type: string enum: - initiatePasswordAuth data: $ref: '#/components/schemas/PasswordAuthData' ProvideMfaCodeAuthRequestData: allOf: - $ref: '#/components/schemas/AuthRequestDataBase' - type: object properties: requestType: type: string enum: - provideMfaCodeAuth data: $ref: '#/components/schemas/MfaCodeAuthData' ConfirmNewPasswordAuthRequestData: allOf: - $ref: '#/components/schemas/AuthRequestDataBase' - type: object properties: requestType: type: string enum: - confirmNewPasswordAuth data: $ref: '#/components/schemas/NewPasswordAuthData' AuthRequestData: oneOf: - $ref: '#/components/schemas/InitiatePasswordAuthRequestData' - $ref: '#/components/schemas/ProvideMfaCodeAuthRequestData' - $ref: '#/components/schemas/ConfirmNewPasswordAuthRequestData' discriminator: propertyName: requestType mapping: initiatePasswordAuth: '#/components/schemas/InitiatePasswordAuthRequestData' provideMfaCodeAuth: '#/components/schemas/ProvideMfaCodeAuthRequestData' confirmNewPasswordAuth: '#/components/schemas/ConfirmNewPasswordAuthRequestData' LogoutRequestData: type: object description: Specifies which cookie-based sessions to terminate for the authenticated user. properties: requestType: type: string enum: - currentSession - otherSessions - allSessions AuthBaseData: type: object description: Base data included in cookie-based authentication steps. properties: username: type: string PasswordAuthData: allOf: - $ref: '#/components/schemas/AuthBaseData' - type: object description: Represents data needed when sending an auth request providing password properties: password: type: string MfaCodeAuthData: allOf: - $ref: '#/components/schemas/AuthBaseData' - type: object description: Represents data needed when sending an auth request providing password properties: mfaCode: type: string sessionToken: type: string NewPasswordAuthData: allOf: - $ref: '#/components/schemas/AuthBaseData' - type: object description: Represents data needed when sending an auth request providing password properties: newPassword: description: New user password. Maximum length is 99 characters type: string confirmNewPassword: description: New user's password confirmation, should match newPassword. Maximum length is 99 characters type: string sessionToken: type: string AuthResponse: type: object description: 'Response from a cookie-based authentication request. Indicates success (with user data and session cookie), failure (with error details), or the next required step (e.g., MFA, new password) along with a `sessionToken`. ' required: - auth-code - message - data properties: auth-code: type: string enum: - NEW_PASSWORD_REQUIRED - MFA_TOKEN_REQUIRED - NEW_AUTH_REQUIRED - SUCCESS - ERROR message: type: string data: anyOf: - $ref: '#/components/schemas/UserData' - $ref: '#/components/schemas/LoginMoreData' LoginMoreData: type: object required: - sessionToken - username description: Data returned when an authentication flow requires an additional step (e.g., MFA code input). properties: sessionToken: description: 'A temporary, secure token that must be submitted along with the next piece of authentication data (e.g., MFA code, new password). This token links the steps in a multi-stage authentication process. ' type: string username: description: The username (email) originally provided, to be re-submitted with the next authentication step. type: string UserLoginProviders: type: string description: 'The identity provider used for user login: - `convert`: Standard username/password authentication managed by Convert. - `google`: Authentication via Google Sign-In (OAuth/OIDC). ' enum: - convert - google UserData: type: object description: Detailed information about an authenticated user, including their profile, UI preferences, and security settings. properties: profileData: type: object properties: email: type: string description: The user's primary email address, used for login and communication. firstName: type: string description: The user's first name. lastName: type: string description: The user's last name. login_provider: $ref: '#/components/schemas/UserLoginProviders' user_id: type: string readOnly: true description: The unique system-generated identifier for this user within Convert. intercom_user_jwt: type: string readOnly: true description: (Internal) JWT used to authenticate the user in Intercom Messenger. reditus_user_jwt: type: string readOnly: true description: (Internal) JWT used to authenticate the user in Reditus. canny_user_jwt: type: string readOnly: true description: (Internal) JWT used to authenticate the user in Canny. canSudo: type: boolean readOnly: true description: (Internal) If true, this user has super-administrator privileges, allowing them to impersonate other users or access all accounts for support purposes. onlyCollaborator: type: boolean readOnly: true description: If true, this user does not own any accounts themselves but only has access to other accounts as a collaborator. persona: type: string readOnly: true description: (Internal) A classification of the user's persona (e.g., "Marketer", "Developer", "Agency") used by Convert to tailor the UI or offer relevant guidance. techPerson: type: boolean readOnly: true description: (Internal) If true, indicates the user is likely technically proficient, which might influence UI hints or available advanced features. preferences: $ref: '#/components/schemas/UserPreferences' isSudo: type: boolean description: (Internal) If true, indicates the user is currently operating in "sudo" (super-administrator impersonation) mode. mfa_backup_codes: type: array description: '(Not Implemented / For Future Use) A list of one-time backup codes for Multi-Factor Authentication (MFA). These would be provided when MFA is enabled and can be used if the primary MFA device is unavailable. ' ConfirmEmailRequestData: type: object description: Contains the confirmation code required to verify a new email address for a user account. required: - code properties: code: type: string description: The unique verification code sent to the user's new email address. Submitting this code confirms the email change. UserMfaSecret: type: object description: Contains the secret key required to set up Multi-Factor Authentication (MFA) with an authenticator app. properties: mfa_secret: type: string description: 'The MFA secret key (often in base32 format) generated by Convert. This secret is typically displayed as a QR code or plain text for the user to enter into their authenticator app (e.g., Google Authenticator, Authy) to start generating time-based one-time passwords (TOTPs). ' UserPreferences: type: object description: A collection of user-specific settings that customize their experience within the Convert application UI. These preferences do not impact the execution or behavior of live experiments. properties: editorSettings: type: object properties: codeOpen: type: boolean nullable: true default: false description: If true, the code editor panel in the Visual Editor is open by default. codeBoxId: type: string nullable: true description: The ID of the specific code editor tab (e.g., 'variationCode', 'variationJs', 'globalJs') that was last active or should be opened by default. enum: - variationCode - variationJs - variationCss - globalJs codeEditorMaximized: type: boolean nullable: true default: false description: If true, the code editor panel is maximized by default. codeEditorHeight: type: integer nullable: true default: 300 description: The default height (in pixels) of the code editor panel. codeLinterOn: type: boolean default: false nullable: true description: If true, the JavaScript/CSS linter in the code editors is enabled by default. displaySettings: type: object properties: accountExperiencesList: $ref: '#/components/schemas/AccountExperiencesListPersistentOptions' accountLiveDataList: $ref: '#/components/schemas/AccountLiveDataPersistentOptions' accountHistoryList: $ref: '#/components/schemas/AccountHistoryPersistentOptions' projectsList: $ref: '#/components/schemas/ProjectsListPersistentOptions' projectExperiences: $ref: '#/components/schemas/ExperiencesListPersistentOptions' projectHypotheses: $ref: '#/components/schemas/HypothesesListPersistentOptions' projectKnowledgeBases: $ref: '#/components/schemas/KnowledgeBasesListPersistentOptions' projectObservations: $ref: '#/components/schemas/ObservationsListPersistentOptions' projectGoals: $ref: '#/components/schemas/GoalsListPersistentOptions' projectAudiences: $ref: '#/components/schemas/AudiencesListPersistentOptions' projectLocations: $ref: '#/components/schemas/LocationsListPersistentOptions' projectLiveData: $ref: '#/components/schemas/ProjectLiveDataPersistentOptions' projectHistoryList: $ref: '#/components/schemas/ProjectHistoryPersistentOptions' experienceLiveData: $ref: '#/components/schemas/ExperienceLiveDataPersistentOptions' experienceHistoryList: $ref: '#/components/schemas/ExperienceHistoryPersistentOptions' experienceReport: $ref: '#/components/schemas/ExperienceReportPersistentOptions' experienceReportFirstView: $ref: '#/components/schemas/ExperienceReportFirstViewPersistentOptions' experienceReportSecondView: $ref: '#/components/schemas/ExperienceReportSecondViewPersistentOptions' projectFeatures: $ref: '#/components/schemas/FeaturesListPersistentOptions' projectSdkKeys: $ref: '#/components/schemas/SdkKeysListPersistentOptions' projectSignalSessions: $ref: '#/components/schemas/SignalSessionsListPersistentOptions' projectCompass: $ref: '#/components/schemas/CompassColumnsPersistentOptions' uiSettings: type: object nullable: true properties: hide_demo_project: type: boolean description: If true, the option to create or view a demo project is hidden for this user. onboard: type: object nullable: true additionalProperties: false properties: remind_in: type: integer nullable: true description: Unix timestamp (UTC) indicating when the next onboarding reminder or step should be displayed to the user. notificationsSeen: type: array items: type: string enum: - TODO-define-it generalSettings: type: object properties: lastOpenAccount: type: integer nullable: true description: The ID of the account that was last accessed by the user, used to default to this account on next login. lastOpenProject: type: integer nullable: true description: The ID of the project that was last accessed by the user. frontendVersion: type: string default: v0 description: (Internal) Specifies which version of the Convert application frontend UI the user is currently experiencing (e.g., for phased rollouts of new UI designs). enum: - v0 - v1 convertLabsOptIn: type: boolean default: false description: If true, the user has opted-in to access experimental or beta features ("Convert Labs") within the application. mfaEnabled: type: boolean description: True if Multi-Factor Authentication (MFA) is currently enabled for this user's account. UserProfileDataUpdate: type: object x-name-validation-pattern: "^(?!.*://)(?!.*@)(?!.*localhost\\b)(?!\\d{1,3}(\\.\\d{1,3}){3}\\b)(?!\\[[0-9a-fA-F:]+\\\ ])(?!.*xn--)(?!.*\\.[A-Za-z0-9])(?!.*\\[\\.\\])(?!.*\\[[dD][oO][tT]\\])(?!.*\\[\\.\\]\\w+)(?!.*\\[[dD][oO][tT]\\]\\\ w+)(?!.*[\uFF0E\u3002\uFF61\uFE52\uFE56\uFE51]).+$" properties: firstName: description: 'The user''s new first name. Must not contain URLs or domain-like content (e.g. `xyz.com`, `http://...`, `www.`). ' type: string maxLength: 200 pattern: "^(?!.*://)(?!.*@)(?!.*localhost\\b)(?!\\d{1,3}(\\.\\d{1,3}){3}\\b)(?!\\[[0-9a-fA-F:]+\\])(?!.*xn--)(?!.*\\\ .[A-Za-z0-9])(?!.*\\[\\.\\])(?!.*\\[[dD][oO][tT]\\])(?!.*\\[\\.\\]\\w+)(?!.*\\[[dD][oO][tT]\\]\\w+)(?!.*[\uFF0E\ \u3002\uFF61\uFE52\uFE56\uFE51]).+$" lastName: description: 'The user''s new last name. Must not contain URLs or domain-like content (e.g. `xyz.com`, `http://...`, `www.`). ' type: string maxLength: 200 pattern: "^(?!.*://)(?!.*@)(?!.*localhost\\b)(?!\\d{1,3}(\\.\\d{1,3}){3}\\b)(?!\\[[0-9a-fA-F:]+\\])(?!.*xn--)(?!.*\\\ .[A-Za-z0-9])(?!.*\\[\\.\\])(?!.*\\[[dD][oO][tT]\\])(?!.*\\[\\.\\]\\w+)(?!.*\\[[dD][oO][tT]\\]\\w+)(?!.*[\uFF0E\ \u3002\uFF61\uFE52\uFE56\uFE51]).+$" currentPassword: description: The user's current password. Required if changing email or password. type: string maxLength: 25 newPassword: description: The new password chosen by the user. Required if changing password. Max 25 chars. type: string maxLength: 25 confirmPassword: description: Confirmation of the new password. Must match `newPassword`. Required if changing password. Max 25 chars. type: string maxLength: 25 email: description: The user's new email address. Requires `currentPassword` for verification. type: string maxLength: 100 format: email mfa: oneOf: - $ref: '#/components/schemas/mfaEnableRequest' - $ref: '#/components/schemas/mfaDisableRequest' discriminator: propertyName: type mapping: enable: '#/components/schemas/mfaEnableRequest' disable: '#/components/schemas/mfaDisableRequest' mfaEnableRequest: type: object description: Request to enable Multi-Factor Authentication (MFA) for the user. properties: type: type: string enum: - enable mfaCode: description: 'The Time-based One-Time Password (TOTP) generated by the user''s authenticator app after scanning the MFA secret (obtained via `generateMfaSecret` endpoint). This code verifies the successful setup of the authenticator app. ' type: string password: description: The user's current password, required to authorize enabling MFA. type: string mfaDisableRequest: type: object description: Request to disable Multi-Factor Authentication (MFA) for the user. properties: type: type: string enum: - disable password: description: The user's current password, required to authorize disabling MFA. type: string AccountUsersAccessesListResponse: type: object description: Response containing a list of users who have collaborator access to a specific account, detailing their permissions. properties: data: $ref: '#/components/schemas/AccountUserAccessesList' AccountUserAccessesResponse: type: object description: Response detailing the access permissions for a single specified user within an account. properties: data: $ref: '#/components/schemas/AccountUserAccesses' AccountUserAccessesList: type: array description: A list of `AccountUserAccesses` objects, each representing a collaborator and their permissions. items: $ref: '#/components/schemas/AccountUserAccesses' BaseAccesses: type: object properties: accesses: type: array description: 'A list defining the user''s access to specific projects or all projects within the account. Each item specifies a `project` (ID or null for all projects) and the `role` granted. ' items: type: object properties: project: nullable: true anyOf: - type: integer nullable: true description: Project ID. If null , than access is referring to all projects inside the account - $ref: '#/components/schemas/Project' BaseAccountUserAccesses: allOf: - type: object properties: first_name: type: string description: Collaborator's first name maxLength: 200 last_name: type: string description: Collaborator's last name maxLength: 200 accesses: type: array description: List of projects the user can access items: type: object properties: api_access: description: Whether or not the user with this access can create API keys for the projects under this access type: boolean status: readOnly: true description: Status of the access, if pending, it means invitation wasn't accepted yet by the receiver allOf: - $ref: '#/components/schemas/AccessStatuses' - $ref: '#/components/schemas/BaseAccesses' AccountUserAccesses: allOf: - $ref: '#/components/schemas/BaseAccountUserAccesses' - $ref: '#/components/schemas/UserByEmail' - $ref: '#/components/schemas/UserById' - type: object properties: accesses: type: array description: List of user's accesses items: type: object properties: role: $ref: '#/components/schemas/AccessRoleNames' UserByEmail: type: object properties: email: description: The email address of the collaborator or invitee. type: string maxLength: 100 UserById: type: object properties: user_id: description: The unique system identifier for an active Convert user. Null if the user is only an invitee (pending acceptance). type: string nullable: true AccessCreateUpdateRole: type: object properties: accesses: type: array description: (Misplaced Array) Defines the role for a specific project. items: type: object properties: role: $ref: '#/components/schemas/AccessRoleNamesNoOwner' custom_message: description: (For invitations) A custom message to include in the invitation email sent to a new collaborator. type: string maxLength: 200 AccountUserAccessesCreateRequestData: allOf: - $ref: '#/components/schemas/BaseAccountUserAccesses' - $ref: '#/components/schemas/UserByEmail' - $ref: '#/components/schemas/AccessCreateUpdateRole' - $ref: '#/components/schemas/AccountUserAccessesExpandParams' - type: object required: - accesses - email UpdateAccountUserAccessesByUserId: allOf: - $ref: '#/components/schemas/UserById' - $ref: '#/components/schemas/BaseAccountUserAccesses' - $ref: '#/components/schemas/AccessCreateUpdateRole' - $ref: '#/components/schemas/AccountUserAccessesExpandParams' UpdateAccountUserAccessesByUserEmail: allOf: - $ref: '#/components/schemas/UserByEmail' - $ref: '#/components/schemas/BaseAccountUserAccesses' - $ref: '#/components/schemas/AccessCreateUpdateRole' - $ref: '#/components/schemas/AccountUserAccessesExpandParams' AccountUserAccessesUpdateRequestData: anyOf: - $ref: '#/components/schemas/UpdateAccountUserAccessesByUserId' - $ref: '#/components/schemas/UpdateAccountUserAccessesByUserEmail' DeleteAccountUserAccessesByUserId: allOf: - $ref: '#/components/schemas/UserById' - $ref: '#/components/schemas/BaseAccesses' DeleteAccountUserAccessesByUserEmail: allOf: - $ref: '#/components/schemas/UserByEmail' - $ref: '#/components/schemas/BaseAccesses' AccountUserAccessesDelete: oneOf: - $ref: '#/components/schemas/DeleteAccountUserAccessesByUserId' - $ref: '#/components/schemas/DeleteAccountUserAccessesByUserEmail' AccessStatuses: type: string readOnly: true enum: - active - pending AccountUserAccessesExpandFields: type: string enum: - accesses.project AccountUserAccessesExpandParams: type: object properties: expand: description: 'Specifies linked objects to expand in the response, e.g., ''accesses.project''. Refer to the [Expanding Fields](#tag/Expandable-Fields) section. ' type: array items: $ref: '#/components/schemas/AccountUserAccessesExpandFields' ColumnPreference: type: object description: Defines user preference for a single column in a UI list view (name and visibility). properties: visible: type: boolean description: If true, this column is visible in the user's list view. If false, it's hidden. name: type: string description: The machine-readable name or key of the column (e.g., "id", "project_name", "status"). BaseUiSectionPreference: type: object description: Defines user preference for a section in a UI view (name and visibility). properties: visible: type: boolean description: If true, this UI section is visible/expanded by default for the user. name: type: string description: The machine-readable name or key of the UI section. UserCustomization: description: A generic key-value pair for storing miscellaneous user-specific UI customizations or settings not covered by structured preferences. type: object properties: key: type: string maxLength: 20 value: nullable: true oneOf: - type: string maxLength: 20 - type: number - type: boolean required: - key - value CompassColumnsPersistentOptions: type: object properties: columns: type: array nullable: true description: 'Sorted list of tabs to be displayed in the UI ' items: allOf: - $ref: '#/components/schemas/ColumnPreference' - type: object properties: name: $ref: '#/components/schemas/CompassColumnsNames' CompassColumnsNames: type: string description: Available tabs for the compass list in the UI. enum: - observations - hypotheses - knowledge_base UserSessionEntry: type: object properties: sid: description: Session identifier. type: string authorized_type: description: Display name of type of how user was authorized. type: string enum: - session_cookie - oauth client: description: 'Name of the client that owns this session. ' type: string last_used_at: description: Last authentication time (unix timestamp). type: integer expires_at: description: Absolute session expiration (unix timestamp). type: integer created_at: description: Session creation time (unix timestamp). type: integer UserSessionsListResponseData: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UserSessionEntry' UserSessionRevokeRequestData: type: object required: - sid properties: sid: description: Session identifier returned by POST /user/sessions. type: string UserSessionRevokeResponseData: type: object required: - code - message properties: code: type: integer message: type: string UserSessionRevokeAllResponseData: type: object required: - code - message properties: code: type: integer message: type: string PlaceholdersListResponseData: type: object description: Response containing list of visitor data placeholders and extra list metadata properties: data: $ref: '#/components/schemas/PlaceholdersList' extra: $ref: '#/components/schemas/Extra' PlaceholdersList: type: array description: List of visitor data placeholders items: $ref: '#/components/schemas/VisitorDataPlaceholder' VisitorDataPlaceholder: type: object description: Base Visitor Data Placeholder Object properties: id: description: Placeholder ID readOnly: true type: integer placeholder: description: A unique per project level identifier for the placeholder. Used in {{placeholder}} syntax. type: string maxLength: 128 default_value: description: Default value to use when no personalization data is found type: string maxLength: 10000 created_at: description: Unix timestamp (UTC) indicating when the placeholder was created type: integer readOnly: true CreatePlaceholderRequestData: allOf: - $ref: '#/components/schemas/VisitorDataPlaceholder' required: - placeholder UpdatePlaceholderRequestData: type: object description: Request body for updating a visitor data placeholder. properties: default_value: description: Default value to use when no personalization data is found type: string maxLength: 10000 placeholder: description: A unique per project level identifier for the placeholder. Used in {{placeholder}} syntax. type: string maxLength: 128 GetPlaceholdersListRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/ResultsPerPage' - $ref: '#/components/schemas/PageNumber' - type: object properties: search: type: string maxLength: 200 nullable: true description: 'A search query used to filter placeholders. Matches are case-insensitive and return results where the `placeholder` value contains the given string. ' BaseDataItem: type: object description: The visitor data as key-value pairs containing placeholder data additionalProperties: true example: placeholder: testing location: New York BaseVisitorData: type: object properties: visitor_id: type: string description: The visitor ID example: '123456' data: $ref: '#/components/schemas/BaseDataItem' VisitorData: allOf: - $ref: '#/components/schemas/BaseVisitorData' - type: object properties: source: type: string description: The source of imported visitor data ImportVisitorsDataCsvRequestData: type: object properties: source: type: string readOnly: true description: The source of the visitor data default: csv file: type: string format: binary description: 'The CSV file to import. The file must be in the following format: **Required columns:** Either `visitor_id` must be present and non-empty. **Column validation:** - `visitor_id`: Must be an string when provided - Other columns: Should match placeholder names defined for the project **Example format:** ```csv visitor_id,name,email,age,location 12345,John Doe,john@example.com,30,New York 67890,Jane Smith,jane@example.com,25,Los Angeles 54321,Bob Johnson,bob@example.com,35,Chicago ``` ' required: - file ImportVisitorsDataPushSource: type: string description: The source of the visitor data - can be any string value ImportVisitorsDataPushItem: $ref: '#/components/schemas/BaseVisitorData' ImportVisitorsDataPushRequestData: type: object properties: source: $ref: '#/components/schemas/ImportVisitorsDataPushSource' data: type: array description: The visitor data list of objects. visitor_id is required for each item in the list. items: $ref: '#/components/schemas/ImportVisitorsDataPushItem' required: - source - data VisitorDataItem: allOf: - $ref: '#/components/schemas/BaseVisitorData' - type: object properties: source: type: string description: The source of imported visitor data example: csv created_at: type: integer readOnly: true description: Unix timestamp (UTC) indicating when this visitor data was created in the system. example: 1753821567 GetVisitorDataListRequestData: allOf: - $ref: '#/components/schemas/OnlyCount' - $ref: '#/components/schemas/PageNumber' - $ref: '#/components/schemas/ResultsPerPage' - type: object properties: search: type: string maxLength: 200 nullable: true description: A search string that would be used to search against visitor data VisitorDataListResponseData: type: object description: Response containing list of visitor data and extra list metadata properties: data: $ref: '#/components/schemas/VisitorDataList' extra: $ref: '#/components/schemas/Extra' VisitorDataList: type: array description: List of visitor data items items: $ref: '#/components/schemas/VisitorDataItem' CreateVisitorDataItemRequestData: allOf: - $ref: '#/components/schemas/VisitorData' required: - visitor_id - data UpdateVisitorDataItemRequestData: type: object properties: data: $ref: '#/components/schemas/BaseDataItem' required: - data