{ "opencollection": "1.0.0", "info": { "name": "Convert API", "version": "2.0.0" }, "items": [ { "info": { "name": "Cookie Authentication", "type": "folder" }, "items": [ { "info": { "name": "Authenticate user session (Cookie Based)", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/auth", "body": { "type": "json", "data": "{}" } }, "docs": "Initiates or continues a cookie-based authentication flow.\nStarts with username/password. If successful and MFA is not required, returns user data and sets a session cookie.\nIf MFA is required, or a new password needs to be set, the response will indicate the next step and provide a sessionToken.\nThis is primarily for UI interaction, LLMs should typically use API Key Authentication.\n" }, { "info": { "name": "Request password reset", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/auth/forgotpassword", "body": { "type": "json", "data": "{}" } }, "docs": "Sends an email with a password reset link to the user associated with the provided email address, if an account exists.\nThis is part of the cookie-based authentication flow.\n" }, { "info": { "name": "Confirm new password after reset request", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/auth/confirmpasswordreset", "body": { "type": "json", "data": "{}" } }, "docs": "Completes the password reset process. The user provides the new password and the confirmation code received via email.\nThis is part of the cookie-based authentication flow.\n" }, { "info": { "name": "Log out user session", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/auth/logout", "body": { "type": "json", "data": "{}" } }, "docs": "Invalidates the current authenticated user session (cookie-based).\nCan also be used to log out other or all sessions for the user.\n" }, { "info": { "name": "Check authentication status", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/auth/status" }, "docs": "Verifies if the current cookie-based session is still valid and authenticated.\n" } ] }, { "info": { "name": "OAuth Authorization", "type": "folder" }, "items": [ { "info": { "name": "Exchange OAuth code for session token", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/auth/oauth/token", "body": { "type": "json", "data": "{}" } }, "docs": "Public endpoint used by OAuth clients to exchange a one-time authorization code for a scoped bearer session token.\nEnforces PKCE binding.\n" } ] }, { "info": { "name": "OAuth", "type": "folder" }, "items": [ { "info": { "name": "List OAuth clients", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/auth/oauth/clients" }, "docs": "Cookie-authenticated endpoint that lists OAuth clients for the current user.\n" }, { "info": { "name": "Create an OAuth client", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/auth/oauth/clients", "body": { "type": "json", "data": "{}" } }, "docs": "Cookie-authenticated endpoint to register a new OAuth client.\n" }, { "info": { "name": "Update an OAuth client", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/auth/oauth/clients/:id/update", "params": [ { "name": "id", "value": "", "type": "path", "description": "OAuth client id." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Cookie-authenticated endpoint to update an existing OAuth client.\n" }, { "info": { "name": "Delete an OAuth client", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/auth/oauth/clients/:client_id", "params": [ { "name": "client_id", "value": "", "type": "path", "description": "OAuth client id." } ] }, "docs": "Cookie-authenticated endpoint to delete an OAuth client and all its sessions.\n" } ] }, { "info": { "name": "User", "type": "folder" }, "items": [ { "info": { "name": "List available user access roles", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/access-roles" }, "docs": "Retrieves a list of all predefined access roles within the Convert system (e.g., Owner, Admin, Editor, Reviewer, Browse).\nEach role defines a set of permissions that dictate what actions a user can perform on accounts and projects.\nThis is useful for understanding permission levels when managing collaborators.\n" }, { "info": { "name": "Get current authenticated user's details", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/user" }, "docs": "Retrieves the profile data, preferences, and settings for the currently authenticated user (via cookie).\nThis includes information like email, name, and UI preferences.\nNote: This endpoint is for cookie-based authentication. For API key authentication, user context is tied to the key itself.\n" }, { "info": { "name": "Update current user's profile", "type": "http" }, "http": { "method": "PUT", "url": "https://api.convert.com/api/v2/user", "body": { "type": "json", "data": "{}" } }, "docs": "Allows the authenticated user (via cookie) to update their profile information, such as name, email, or password.\nAlso used to manage Multi-Factor Authentication (MFA) settings.\nUser preferences (like UI display settings) are managed via a separate endpoint.\n" }, { "info": { "name": "Confirm user email address change", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/user/confirm-email", "body": { "type": "json", "data": "{}" } }, "docs": "Finalizes an email address change request by submitting the confirmation code sent to the new email address.\nUsed in cookie-based authentication flows.\n" }, { "info": { "name": "Update user's UI preferences", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/user/preferences", "body": { "type": "json", "data": "{}" } }, "docs": "Allows the authenticated user (via cookie) to update their preferences for the Convert application UI,\nsuch as default column visibility in tables or editor settings. These settings do not affect experiment behavior.\n" }, { "info": { "name": "Generate MFA secret for authenticator app", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/user/mfa-secret" }, "docs": "Generates a new Multi-Factor Authentication (MFA) secret for the authenticated user (cookie-based).\nThis secret is used to set up an authenticator app (like Google Authenticator) for generating time-based one-time passwords (TOTPs).\n" }, { "info": { "name": "Accept and create a demo project for the user", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/user/accept-demo-project" }, "docs": "Allows a user to accept the creation of a pre-configured demo project in their account.\nThis is typically used for onboarding or trial experiences to showcase Convert's features.\n" }, { "info": { "name": "List authorized sessions for the current user", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/user/sessions" }, "docs": "Cookie-authenticated endpoint that returns all active authorized sessions for the current user,\nincluding the current cookie-based session and any OAuth bearer-token sessions the user has approved.\n" }, { "info": { "name": "Revoke User session", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/user/sessions/revoke", "body": { "type": "json", "data": "{}" } }, "docs": "Cookie-authenticated endpoint that revokes a single session (cookie-based or OAuth) for the current user, identified by its sid.\n" }, { "info": { "name": "Revoke all User sessions", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/user/sessions/revoke-all" }, "docs": "Cookie-authenticated endpoint that revokes every active session (cookie-based and OAuth) for the current user.\n" } ] }, { "info": { "name": "Accounts", "type": "folder" }, "items": [ { "info": { "name": "List accounts accessible to the user", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts" }, "docs": "Retrieves a list of all accounts the authenticated user has access to.\nIf using API key authentication, this typically returns the single account associated with the API key.\nIf using cookie-based authentication, it may return multiple accounts if the user is a collaborator on several.\nAn account is the top-level container for projects, billing, and user management.\n" }, { "info": { "name": "List available billing plans", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/billing-plans" }, "docs": "Retrieves a list of all active billing plans that an account can subscribe to.\nEach plan defines usage limits (e.g., tested visitors, number of projects) and available features.\n" }, { "info": { "name": "Get live tracking events for an account", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/livedata", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account to be retrieved" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves the last 100 tracking events (e.g., experiment views, goal conversions) across all projects within the specified account.\nUseful for real-time monitoring of activity. Supports filtering by event types and specific projects.\nAs 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.\"\n" }, { "info": { "name": "Get change history for an account", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/change-history", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a historical log of changes made within the specified account, such as modifications to account settings or billing.\nThis provides an audit trail for account-level activities.\nThe Knowledge Base states, \"The Change History shows a record of user activity for each of your projects.\" This extends to account changes.\n" }, { "info": { "name": "List active and completed experiences for an account", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/experiences", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of all active and completed experiences (A/B tests, personalizations, etc.) across all projects within the specified account.\nAllows filtering to narrow down results. Useful for an overview of ongoing and finished optimization activities at the account level.\n" }, { "info": { "name": "Get details for a specific account", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/details", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "include", "value": "", "type": "query", "description": "Specifies the list of fields to be included in the response, which otherwise would not be sent.\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" } ] }, "docs": "Retrieves detailed information about a specific account, including its settings, billing status, and usage limits.\nThe `include` parameter can be used to fetch additional related data, like active project counts.\n" }, { "info": { "name": "Update details for a specific account", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/details", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies the settings or billing information for a specific account.\nThis can include updating company details, contact information, or billing preferences.\n" }, { "info": { "name": "Create a new sub-account", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/sub-accounts/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the parent account under which the sub-account is being created." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new sub-account under the specified parent main account.\nSub-accounts inherit certain properties and limits from the parent but can have their own users and projects.\nThis is typically used by agencies or larger organizations to manage client accounts or departmental usage separately.\n" }, { "info": { "name": "Request add-ons for an account", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/addons", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account for which the addons will be requested" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Allows requesting specific add-on features or services for an account, such as premium support tiers or specialized training.\n" }, { "info": { "name": "Initiate payment method setup", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/payment-setup", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account for which the payment setup will be started" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Starts a secure session with the payment provider (e.g., Stripe) to set up or update an account's payment method.\nReturns a client secret or token that the frontend UI uses to complete the payment setup process directly with the provider.\n" }, { "info": { "name": "Get billing portal URL", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/billing-portal", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" } ] }, "docs": "Returns an authenticated Paddle billing portal URL for the given account.\n\nThe URL takes the customer to the Paddle billing portal where they can\ncheck subscriptions, view or download invoices.\n" }, { "info": { "name": "Get users for billing plan setup notification", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/plan_setup/users", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account for which the plan setup users will be returned" } ] }, "docs": "Retrieves a list of users associated with an account, typically for the purpose of notifying them about billing plan setup or changes.\nUsed internally for account management workflows.\n" } ] }, { "info": { "name": "AI content", "type": "folder" }, "items": [ { "info": { "name": "Generate text variations using AI", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/ai/text", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account under which the api call executes" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Leverages Generative AI to create alternative text versions (variants) for a given piece of content.\nUsers can specify the number of variations, the original content, an AI model framework (e.g., Cialdini, AIDA), and a specific principle within that framework.\nThis helps in quickly generating creative options for A/B testing headlines, calls to action, or other textual elements.\nOptionally, an OpenAI Key can be provided for using more advanced models or larger context.\n" }, { "info": { "name": "Generate code variation using AI", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/ai/code", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account under which the api call executes" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Leverages Generative AI to improve provided code.\n" } ] }, { "info": { "name": "Collaborators", "type": "folder" }, "items": [ { "info": { "name": "List users and their access permissions for an account", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/users-accesses", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ] }, "docs": "Retrieves a list of all users who have collaborator access to the specified account.\nFor each user, it details the projects they can access and their role within those projects (e.g., Admin, Editor).\nThe `expand` parameter can be used to get more details about the projects.\nAs per the Knowledge Base, \"Account owners can invite collaborators to projects and choose to give them varying privileges.\"\n" }, { "info": { "name": "Update a user's access permissions for an account", "type": "http" }, "http": { "method": "PUT", "url": "https://api.convert.com/api/v2/accounts/:account_id/users-accesses/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies the access rights of an existing collaborator for the specified account.\nThis can involve changing their role for specific projects or altering which projects they can access.\nIdentifies the user by `user_id` (for active collaborators) or `email` (for pending invitations).\n" }, { "info": { "name": "Invite a new collaborator to an account", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/users-accesses/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Sends an invitation to a user (identified by email) to become a collaborator on the specified account.\nThe request defines the initial set of projects and the role the user will have for those projects.\nThe user will receive an email to accept the invitation.\n" }, { "info": { "name": "Remove a collaborator's access from an account", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/users-accesses/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Revokes a user's collaborator access to specified projects within an account, or entirely from the account.\nIdentifies the user by `user_id` or `email`.\n" }, { "info": { "name": "Check partner status for extended API access", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/check-partner", "body": { "type": "json", "data": "{}" } }, "docs": "Verifies if the provided email belongs to a registered partner, potentially enabling extended API functionalities.\nThis is an internal mechanism.\n" }, { "info": { "name": "Accept a collaborator invitation", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/auth/accept-invitation", "body": { "type": "json", "data": "{}" } }, "docs": "Allows a user to accept an invitation to collaborate on an account using a unique hash token received via email.\nIf the user is new to Convert, this will also trigger account creation.\n" } ] }, { "info": { "name": "API Keys", "type": "folder" }, "items": [ { "info": { "name": "List API keys for an account", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/api-keys", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" } ] }, "docs": "Retrieves a list of all API keys configured for the specified account.\nAPI keys are used for server-to-server authentication, allowing applications to interact with the Convert API programmatically.\nEach key can be scoped to specific projects.\n" }, { "info": { "name": "Create a new API key for an account", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/api-keys/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Generates a new API key and secret for the specified account.\nThe key can be named for easier identification and can be restricted to a list of project IDs.\nIf no projects are specified, the key grants access to all projects in the account.\nThe API secret is only shown at the time of creation and should be stored securely.\n" }, { "info": { "name": "Delete an API key", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/api-keys/:key_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "key_id", "value": "", "type": "path", "description": "ID of the API key to be deleted" } ] }, "docs": "Permanently revokes an API key, identified by its `key_id`.\nOnce deleted, the key can no longer be used to authenticate API requests.\n" } ] }, { "info": { "name": "Visitor Insights", "type": "folder" }, "items": [ { "info": { "name": "List recorded visitor sessions for a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/sessions", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of recorded visitor sessions for a specific project.\nThis endpoint is typically used for integrations that require access to raw session data.\nNote: This is different from Convert Signals. For frustration and usability insights, see the Signal Sessions endpoint.\n" }, { "info": { "name": "List Convert Signals™ (visitor frustration sessions)", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/signal_sessions", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of Convert Signals™ sessions for a project.\nConvert Signals™ \"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" }, { "info": { "name": "Delete a specific Convert Signals™ session", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/signal_sessions/:signal_session_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "signal_session_id", "value": "", "type": "path", "description": "ID of the signal session to be deleted" } ] }, "docs": "Permanently removes a recorded Convert Signals™ session, identified by its `signal_session_id`.\n" } ] }, { "info": { "name": "SDK Keys", "type": "folder" }, "items": [ { "info": { "name": "List SDK keys for a project", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/sdk-keys", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" } ] }, "docs": "Retrieves a list of SDK keys associated with a specific project.\nSDK 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.\nEach key is tied to a specific environment within the project (e.g., production, staging).\n" }, { "info": { "name": "Create a new SDK key for a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/sdk-keys/create", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Generates a new SDK key and, optionally, a secret for a specified project and environment.\nThis key is then used by the Convert SDKs to authenticate and fetch project configurations.\nIf `has_secret` is true and no `sdk_secret` is provided, a secret will be auto-generated.\nThe SDK secret (if generated) is only shown at the time of creation.\n" }, { "info": { "name": "Update SDK Key", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/sdk-keys/:sdk_key/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "sdk_key", "value": "", "type": "path", "description": "ID of the SDK key to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Partially update an SDK key, modifying only the specific fields provided in the request.\n" }, { "info": { "name": "Delete an SDK key", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/sdk-keys/:sdk_key/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "sdk_key", "value": "", "type": "path", "description": "ID of the SDK key to be deleted" } ] }, "docs": "Permanently revokes an SDK key, identified by its `sdk_key` value.\nOnce deleted, SDKs using this key will no longer be able to fetch configurations or track events for the associated project and environment.\n" } ] }, { "info": { "name": "Visitors Data", "type": "folder" }, "items": [ { "info": { "name": "Get Visitors Data", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/visitors-data", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Get visitors data for a project\n" }, { "info": { "name": "Create Visitor Data Item", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/visitors-data/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new visitor data item. Fails if visitor_id already exists." }, { "info": { "name": "Get Visitor Data Item", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/visitors-data/:visitor_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "visitor_id", "value": "", "type": "path", "description": "The visitor identifier for visitor data operations" } ] }, "docs": "Returns a single visitor data item by visitor_id." }, { "info": { "name": "Update Visitor Data Item", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/visitors-data/:visitor_id/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "visitor_id", "value": "", "type": "path", "description": "The visitor identifier for visitor data operations" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates an existing visitor data item by visitor_id." }, { "info": { "name": "Delete Visitor Data Item", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/visitors-data/:visitor_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "visitor_id", "value": "", "type": "path", "description": "The visitor identifier for visitor data operations" } ] }, "docs": "Deletes a visitor data item identified by visitor_id." }, { "info": { "name": "Import Visitors Data Csv", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/visitors-data/import", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" } ], "body": { "type": "multipart-form", "data": [] } }, "docs": "Imports visitors data into the project from a CSV file\n" }, { "info": { "name": "Import Visitors Data Push", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/visitors-data/push", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" } ], "body": { "type": "json", "data": "{}" } }, "docs": "push endpoint for visitors data import from the third party service\n" } ] }, { "info": { "name": "Visitor Data Placeholders", "type": "folder" }, "items": [ { "info": { "name": "List Placeholders", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/visitors-data/placeholders", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Returns a list of visitors data placeholders defined in the project" }, { "info": { "name": "Create Placeholder", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/visitors-data/placeholders/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new visitors data placeholder" }, { "info": { "name": "Update Placeholder", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/visitors-data/placeholders/:placeholderId/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "placeholder_id", "value": "", "type": "path", "description": "ID of the placeholder to be retrieved/updated/deleted" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates an existing visitors data placeholder" }, { "info": { "name": "Delete Placeholder", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/visitors-data/placeholders/:placeholderId/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "placeholder_id", "value": "", "type": "path", "description": "ID of the placeholder to be retrieved/updated/deleted" } ] }, "docs": "Deletes a visitors data placeholder" }, { "info": { "name": "Get Placeholder", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/visitors-data/placeholders/:placeholder_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "placeholder_id", "value": "", "type": "path", "description": "ID of the placeholder to be retrieved/updated/deleted" } ] }, "docs": "Returns a single visitors data placeholder by ID." } ] }, { "info": { "name": "Projects", "type": "folder" }, "items": [ { "info": { "name": "List projects within an account", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of all projects belonging to the specified account that the authenticated user has access to.\nSupports filtering by project status, name/description search, and pagination.\nA project in Convert is a container for organizing experiences (A/B tests, personalizations), goals, audiences, and associated domains.\nAs per the Knowledge Base: \"Each project has its own tracking code, set of experiences, and set of collaborators.\"\n" }, { "info": { "name": "Get change history for a specific project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/change-history", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a historical log of changes made within a specific project.\nThis includes modifications to experiences, goals, audiences, locations, and project settings.\nProvides an audit trail for project-level activities, filterable by date, user, and event type.\nThe 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.\"\n" }, { "info": { "name": "Get details for a specific project", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "include", "value": "", "type": "query", "description": "Specifies the list of fields to be included in the response, which otherwise would not be sent.\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ] }, "docs": "Retrieves comprehensive details for a single project, identified by its `project_id`.\nThis includes its name, type (web or fullstack), global JavaScript, settings (like time zone, jQuery inclusion), integrations, and optionally, associated domains and usage statistics.\nThe `include` parameter can fetch related data like `domains` or `stats.usage`. The `expand` parameter can provide full objects for linked entities.\n" }, { "info": { "name": "Create a new project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Create a new project" }, { "info": { "name": "Update an existing project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies the settings of an existing project.\nThis can include changing its name, global JavaScript, time zone, active domains, integration settings, or GDPR compliance options.\nThe list of domains provided in the request will replace the existing list.\n" }, { "info": { "name": "Delete a project", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be deleted" } ] }, "docs": "Permanently removes an existing project and all its associated data (experiences, goals, audiences, reports) from the specified account.\nThis action is irreversible.\nThe 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.\"\n" }, { "info": { "name": "Get live tracking events for a specific project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/livedata", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project for which live data is returned" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves the last 100 tracking events (e.g., experiment views, goal conversions) specifically for the given project.\nUseful for real-time monitoring of a single project's activity. Supports filtering by event types, experiences, and goals.\nAs 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.\"\n" }, { "info": { "name": "Update multiple projects at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/bulk-update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Allows for updating settings (like tracking script version) for multiple projects simultaneously within an account.\nRequires a list of project IDs and the settings to apply.\n" }, { "info": { "name": "Generate a debug token for a project", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/generate-debug-token", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project" } ] }, "docs": "Creates a temporary debug token for a project. This token can be used with the Convert tracking script\n(e.g., via the `convert-debug-token` header or query parameter) to preview draft or paused experiences,\nor to force specific variations for QA purposes without affecting live experiment data.\nThe token has a limited time-to-live (TTL).\n" }, { "info": { "name": "Export project data as JSON", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/export", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Generates a JSON file containing all configuration data for a specific project.\nThis includes its experiences, goals, audiences, locations, hypotheses, and project settings.\nUseful for backing up project configurations or migrating them to another Convert account or instance.\nThe Knowledge Base mentions this feature for \"Save and Migrate Project Settings\" and \"Template Creation\".\n" }, { "info": { "name": "Import project data from a JSON file", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/import-project", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account where the project will be stored." } ], "body": { "type": "multipart-form", "data": [] } }, "docs": "Creates a new project or updates an existing one by importing data from a JSON file (previously exported from Convert).\nThis allows for restoring backups or replicating project setups.\nThe Knowledge Base mentions this for \"Save and Migrate Project Settings\" and \"Template Creation\".\n" }, { "info": { "name": "Import associated data into an existing project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/import-project-data", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account where the project is stored." }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which details will be attached." } ], "body": { "type": "multipart-form", "data": [] } }, "docs": "Imports associated data (like experiences, goals, audiences) from a JSON file into an already existing project.\nThis is useful for selectively adding or updating components within a project from an export.\nThe Knowledge Base mentions \"Selective Import/Export: Choose to export/import entire projects or only selected goals, audiences, and locations.\"\n" } ] }, { "info": { "name": "Domains", "type": "folder" }, "items": [ { "info": { "name": "List domains associated with a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/domains", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of all website domains configured for a specific project.\nThe Convert tracking script will operate on these domains to run experiences and track visitors.\nWildcard domains (e.g., `*.example.com`) are supported.\nAs per the Knowledge Base: \"Active Websites: The domains you would like to use inside the project. Make sure you always add new domains here...\"\n" }, { "info": { "name": "Get details for a specific domain in a project", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/domains/:domain_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the domain is stored" }, { "name": "domain_id", "value": "", "type": "path", "description": "ID of the domain to be retrieved" } ] }, "docs": "Retrieves information about a single domain associated with a project, identified by its `domain_id`.\nThis includes the domain URL and whether the Convert tracking code was detected on it.\n" }, { "info": { "name": "Get domain details by its URL", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/domains/by_url", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the domain is stored" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves information about a domain by matching its URL (exact or wildcard) instead of its ID.\nUseful if you know the domain URL but not its internal Convert ID.\n" }, { "info": { "name": "Verify Convert tracking code installation on a domain", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/domains/:domain_id/check_code", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the domain is stored" }, { "name": "domain_id", "value": "", "type": "path", "description": "ID of the domain to which the given URL belongs. An error would be returned if the URL is not under this domain." } ], "body": { "type": "json", "data": "{}" } }, "docs": "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`).\nUpdates the `code_installed` status of the domain object.\nThe Knowledge Base article \"Tracking Script Installation Verification\" describes this UI feature.\n" }, { "info": { "name": "Add a new domain to a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/domains/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the domain is to be stored" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Associates a new website domain (e.g., `https://www.example.com`) with the specified project.\nThe Convert tracking script for this project should then be installed on this domain to enable experiments.\nWildcards like `https://*.example.com` can be used to include all subdomains.\n" }, { "info": { "name": "Update an existing domain in a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/domains/:domain_id/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the domain is to be stored" }, { "name": "domain_id", "value": "", "type": "path", "description": "ID of the domain to be updated" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies the URL of an existing domain associated with a project.\n" }, { "info": { "name": "Remove a domain from a project", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/domains/:domain_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the domain is to be stored" }, { "name": "domain_id", "value": "", "type": "path", "description": "ID of the domain to be delete" } ] }, "docs": "De-associates a domain from the specified project.\nAfter deletion, Convert experiences will no longer run on this domain for this project.\n" }, { "info": { "name": "Remove multiple domains from a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/domains/bulk-delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "De-associates multiple domains from the specified project in a single operation.\nRequires a list of domain IDs to be removed.\n" } ] }, { "info": { "name": "Experiences", "type": "folder" }, "items": [ { "info": { "name": "List experiences within a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of all experiences (A/B tests, MVT, Split URL, Deployments, etc.) within a specific project.\nSupports filtering by status, type, tags, and other criteria. Pagination is also supported.\nThe `include` parameter can fetch related data like `variations` or `goals`. The `expand` parameter can provide full objects for linked entities.\nThe Knowledge Base article \"The Experience Overview Screen\" describes the UI equivalent.\n" }, { "info": { "name": "Get details for a specific experience", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id", "headers": [ { "name": "report_token", "value": "" } ], "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the experience to be retrieved" }, { "name": "include", "value": "", "type": "query", "description": "Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ] }, "docs": "Retrieves comprehensive details for a single experience, identified by its `experience_id`.\nThis includes its configuration (name, type, URL, status), associated audiences, locations, goals, variations, and integration settings.\nThe `include` and `expand` parameters allow fetching more detailed related data.\nThe Knowledge Base article \"Experience Summary\" describes the UI equivalent of this data.\n" }, { "info": { "name": "Get experience details by its unique key", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_key", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_key", "value": "", "type": "path", "description": "The key of the experience to be retrieved" }, { "name": "include", "value": "", "type": "query", "description": "Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ] }, "docs": "Retrieves comprehensive details for a single experience, identified by its user-defined `experience_key` instead of its numerical ID.\nThis is useful when you have a human-readable key for an experience.\nFunctionality and parameters are otherwise similar to getting an experience by ID.\n" }, { "info": { "name": "Create a new experience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "include", "value": "", "type": "query", "description": "Specifies the list of optional objects which would be included in the response.\n\nRead more in the section related to [Expanding Fields](#tag/Optional-Fields)\n" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new experience (e.g., A/B test, Split URL test, MVT, Deploy, A/A test, Multi-page Funnel) within a project.\nRequires defining the experience name, type, status (usually 'draft'), and the URL for the Visual Editor or original page.\nVariations, audiences, locations, goals, and other settings can be specified during creation.\nThe Knowledge Base article \"Create a New Experience\" outlines the UI process.\n" }, { "info": { "name": "Clone an existing experience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/clone", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the experience to be cloned" }, { "name": "include", "value": "", "type": "query", "description": "Specifies the list of optional objects which would be included in the response.\n\nRead more in the section related to [Expanding Fields](#tag/Optional-Fields)\n" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new experience as an identical copy of an existing one (specified by `experience_id`).\nThis is useful for iterating on a previous test or using an existing experience as a template.\nThe cloned experience starts in 'draft' status and does not copy historical report data.\nThe Knowledge Base article \"How to Clone an Experiment?\" describes this.\n" }, { "info": { "name": "Update an existing experience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the updated experience" }, { "name": "include", "value": "", "type": "query", "description": "Specifies the list of optional objects which would be included in the response.\n\nRead more in the section related to [Expanding Fields](#tag/Optional-Fields)\n" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies the configuration of an existing experience.\nThis 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.\nThe 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.\n" }, { "info": { "name": "Delete an experience", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the experience to be delete" } ] }, "docs": "Permanently removes an existing experience and all its associated data from the project.\nThis action is irreversible. It's generally recommended to archive experiences instead of deleting them to preserve historical data.\nThe Knowledge Base article \"How Do I Archive / Delete an Experience?\" highlights this.\n" }, { "info": { "name": "Manage report access token for an experience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/report_token", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the Experience" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Generates, regenerates, or deletes a unique token that allows read-only access to an experience's report.\nThis is useful for sharing report data with stakeholders who do not have a Convert account or full project access.\nThe token has an expiration time.\n" }, { "info": { "name": "Get live tracking events for a specific experience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/livedata", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the experience is stored" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the Experience" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves the last 100 tracking events (views, conversions, revenue) specifically for the given experience.\nUseful for real-time monitoring and QA of a single active experience. Supports filtering by event type and goals.\nThe Knowledge Base article \"Live Logs for Projects and Experiments in Convert\" describes this feature.\n" }, { "info": { "name": "Get change history for a specific experience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/change-history", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the Experience" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a historical log of all changes made to a specific experience.\nThis includes modifications to its settings, variations, audiences, goals, status, etc.\nProvides an audit trail for the lifecycle of an experience, filterable by date and user.\nThe Knowledge Base article \"Track User Changes with Change History\" details this.\n" }, { "info": { "name": "Trigger screenshot generation for experience variations", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/trigger-screenshots", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the Experience" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Initiates the process of generating or regenerating screenshots for the variations of a specified experience.\nThese screenshots are displayed in the Convert UI to help visualize the changes made in each variation.\nThe Knowledge Base article \"Whitelist IPs for Screenshot Previews\" is related as it lists IPs our service uses.\n" }, { "info": { "name": "Update multiple experiences at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/bulk-update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Allows for changing the status (e.g., activate, pause, archive) of multiple experiences within a project simultaneously.\nRequires a list of experience IDs and the target status.\nThe Knowledge Base article \"Bulk Actions on Experiences\" describes this UI feature.\n" }, { "info": { "name": "Delete multiple experiences at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/bulk-delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Permanently removes multiple experiences from a project in a single operation.\nRequires a list of experience IDs. This action is irreversible.\nThe Knowledge Base article \"Bulk Actions on Experiences\" describes this UI feature.\n" } ] }, { "info": { "name": "Experiences Reports", "type": "folder" }, "items": [ { "info": { "name": "Get report settings for an experience", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/report_settings", "headers": [ { "name": "report_token", "value": "" } ], "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the experience" } ] }, "docs": "Retrieves the specific reporting settings for an experience. This includes configurations like confidence level,\nstatistical methodology (Frequentist/Bayesian), MAB strategy, primary metric, and outlier detection rules.\nThese settings govern how experiment results are calculated and displayed.\nThe Knowledge Base article \"Experiment Report\" (Stats Settings section) covers these.\n" }, { "info": { "name": "Get aggregated performance report for an experience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/aggregated_report", "headers": [ { "name": "report_token", "value": "" } ], "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the experience" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves the main performance report for a specific experience.\nThis report shows aggregated data for each variation, including visitor counts, conversions, conversion rates, improvement percentages,\nand statistical confidence (or chance to win for Bayesian). Data is provided for all goals attached to the experience.\nSupports filtering by date range and segments.\nThe Knowledge Base article \"Experiment Report\" details the metrics shown.\n" }, { "info": { "name": "Get daily performance report for an experience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/daily_report", "headers": [ { "name": "report_token", "value": "" } ], "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the experience" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a day-by-day breakdown of performance metrics (visitors, conversions, conversion rate, etc.) for a specific experience and goal.\nThis allows trend analysis and observation of how an experiment performs over time.\nSupports filtering by date range and segments, and can show cumulative or non-cumulative data.\nThe Knowledge Base article \"Experiment Report\" (Graphs section) visualizes this type of data.\n" }, { "info": { "name": "Get daily traffic allocation report for an MAB experience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/daily_traffic_allocation", "headers": [ { "name": "report_token", "value": "" } ], "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the experience" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves the day-by-day traffic allocation percentages for each variation in an experience that uses Multi-Armed Bandit (MAB) or auto-allocation.\nThis shows how Convert dynamically shifted traffic towards better-performing variations over time.\nThe Knowledge Base article \"Multi-Armed Bandit (MAB) & Auto-Allocation in Convert\" explains this feature.\n" }, { "info": { "name": "Reset report data for an experience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/reset_report", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the experience" } ] }, "docs": "Clears all accumulated visitor and conversion data for an experience's report, effectively resetting its statistics to zero.\nThe 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.\nThe 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\".\n" }, { "info": { "name": "Export an experience report (CSV/PDF)", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/export_report", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the experience" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Generates an export of an experience's performance report in either CSV (aggregated or daily) or PDF format.\nReturns a downloadable link for the generated file. Useful for offline analysis or sharing with stakeholders.\nThe Knowledge Base article \"Experiment Report\" (Export & Download section) describes this.\n" }, { "info": { "name": "Export raw tracking data for an experience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/export_raw_data", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the experience" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Initiates a job to export the raw, event-level tracking data for a specific experience.\nThis data includes individual visitor bucketing events, conversions, and transactions.\nThe export is typically delivered as a link via email due to potential size.\nUseful for in-depth custom analysis or importing into external data warehouses.\nThe Knowledge Base article \"Experiment Report\" (Export & Download section) mentions this.\n" }, { "info": { "name": "Remove specific data from an experience report", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/remove_report_data", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the experience" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Allows for targeted deletion of report data for an experience based on date range and event type (view_experience, conversion, transaction).\nFor conversion and transaction events, specific goals can be targeted.\nIf `simulate` is true, returns a count of records that would be deleted without actual deletion. Otherwise, performs permanent deletion.\nThe Knowledge Base article \"Remove Report Data Feature\" details this.\n" } ] }, { "info": { "name": "Experiences Heatmaps", "type": "folder" }, "items": [ { "info": { "name": "Get heatmap background image", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/heatmaps/:heatmap_id/background", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the experience" }, { "name": "heatmap_id", "value": "", "type": "path", "description": "ID of the heatmap." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves the background image for a specific heatmap and device.\n" }, { "info": { "name": "Get heatmap overlay (interaction) image", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/heatmaps/:heatmap_id/overlay", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the experience" }, { "name": "heatmap_id", "value": "", "type": "path", "description": "ID of the heatmap." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves the overlay image for a specific heatmap, device, and interaction type.\n" } ] }, { "info": { "name": "Experience Variations", "type": "folder" }, "items": [ { "info": { "name": "Update an experience variation", "type": "http" }, "http": { "method": "PUT", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/variations/:variation_id/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the updated experience" }, { "name": "variation_id", "value": "", "type": "path", "description": "The ID of the variation to be updated" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies an existing variation within an experience.\nThis can include changing its name, description, traffic distribution, status (running/stopped), or the actual changes (CSS, JS, HTML modifications) it applies.\nThe Knowledge Base article \"How do I edit my variations?\" covers the UI aspect.\n" }, { "info": { "name": "Delete an experience variation", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/variations/:variation_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the experience to which the variation belongs" }, { "name": "variation_id", "value": "", "type": "path", "description": "The ID of the variation to be deleted" } ] }, "docs": "Permanently removes a variation from an experience.\nNote: Deleting variations from an active or previously active experiment can impact statistical validity and is generally discouraged.\nIt's often better to stop traffic to a variation.\nThe 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.\"\n" }, { "info": { "name": "Get screenshot for an experience variation", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/variations/:variation_id/screenshot", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the experience to which the variation belongs" }, { "name": "variation_id", "value": "", "type": "path", "description": "The ID of the variation to be deleted" }, { "name": "size", "value": "", "type": "query", "description": "The size of the returned image, if omitted will return full size" }, { "name": "force_download", "value": "", "type": "query", "description": "Flag used to force download instead of inline response" } ] }, "docs": "Retrieves the screenshot image for a specific variation, base64 encoded.\nScreenshots help visualize the changes applied by a variation and are shown in the Convert UI.\nCan request a full-size image or a thumbnail.\nThe Knowledge Base article \"Whitelist IPs for Screenshot Previews\" is related.\n" }, { "info": { "name": "Upload a screenshot for an experience variation", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/variations/:variation_id/screenshot", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the experience to which the variation belongs" }, { "name": "variation_id", "value": "", "type": "path", "description": "The ID of the variation to be deleted" }, { "name": "size", "value": "", "type": "query", "description": "The size of the returned image, if omitted will return full size" }, { "name": "force_download", "value": "", "type": "query", "description": "Flag used to force download instead of inline response" } ], "body": { "type": "multipart-form", "data": [] } }, "docs": "Allows uploading a custom screenshot image for a specific variation.\nThis can be useful if automatic screenshot generation fails or if a specific view needs to be captured.\nThe uploaded image will be displayed in the Convert UI for this variation.\n" }, { "info": { "name": "Convert a winning variation into a new experience (Deploy or A/B)", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/variations/:variation_id/convert", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the experience to which the variation belongs" }, { "name": "variation_id", "value": "", "type": "path", "description": "The ID of the variation to be converted" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Takes a variation (often a winning one from an A/B test) and creates a new, separate experience from it.\nThis new experience can be a 'Deploy' (to roll out the change to a specific audience) or another 'A/B' test (to further iterate).\nThis is a common step after an A/B test concludes with a winner.\nThe Knowledge Base article \"What about Deployments?\" mentions: \"Create a new Deploy from a Variation or Winning Variation from another Experiment\".\n" } ] }, { "info": { "name": "Version Changes", "type": "folder" }, "items": [ { "info": { "name": "Get details of a specific change in a variation", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/changes/:change_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the experience" }, { "name": "change_id", "value": "", "type": "path", "description": "ID of the experience change to get/update" } ] }, "docs": "Retrieves the details of a single change applied within an experience's variation.\nA change can be CSS modifications, JavaScript code, HTML insertions, or configurations for Split URL redirects or Full Stack features.\nThe `data` field structure depends on the `type` of the change.\n" }, { "info": { "name": "Update a specific change in a variation", "type": "http" }, "http": { "method": "PUT", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/changes/:change_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "ID of the experience" }, { "name": "change_id", "value": "", "type": "path", "description": "ID of the experience change to get/update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies the content or settings of an existing change within an experience's variation.\nFor example, updating the JavaScript code, CSS rules, or redirect pattern for a change.\nThe structure of the `data` field in the request body must match the `type` of the change being updated.\n" } ] }, { "info": { "name": "Experience Sections", "type": "folder" }, "items": [ { "info": { "name": "List sections of a multivariate (MVT) experience", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/sections", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the experience of which to return sections list" }, { "name": "include", "value": "", "type": "query", "description": "Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ] }, "docs": "Retrieves the list of sections defined for a multivariate (MVT) experience.\nIn 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).\nVariations in an MVT are combinations of one version from each section.\nThe Knowledge Base article \"Creating a Multivariate Experiment\" explains sections.\n" }, { "info": { "name": "Add a new section to an MVT experience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/sections/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the experience where section will be created" }, { "name": "include", "value": "", "type": "query", "description": "Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new section within a multivariate (MVT) experience.\nA section represents an element or area of the page to be tested with multiple alternatives (versions).\nRequires defining the section name and its initial versions with their respective changes.\n" }, { "info": { "name": "Update an existing section in an MVT experience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/sections/:section_id/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the given experience" }, { "name": "section_id", "value": "", "type": "path", "description": "The ID of the updated section" }, { "name": "include", "value": "", "type": "query", "description": "Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies an existing section within a multivariate (MVT) experience.\nThis can include changing the section's name or updating its versions and their associated changes.\nThe entire list of versions for the section must be provided; versions not included will be removed.\n" }, { "info": { "name": "Update all sections for an MVT experience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/sections/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the exeprience for which to update sections" }, { "name": "include", "value": "", "type": "query", "description": "Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Replaces all existing sections and their versions for a multivariate (MVT) experience with the provided list.\nIf a section or version from the existing configuration is not included in the request, it will be removed.\nThe order of sections, versions, and changes is important and will be preserved.\nThis is a comprehensive update for the entire MVT structure.\n" } ] }, { "info": { "name": "Section Versions", "type": "folder" }, "items": [ { "info": { "name": "Add a new version to an MVT section", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/sections/:section_id/versions/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the given experience" }, { "name": "section_id", "value": "", "type": "path", "description": "The ID of the section under which to create the version" }, { "name": "include", "value": "", "type": "query", "description": "Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new version (alternative) within a specific section of a multivariate (MVT) experience.\nRequires defining the version name and its associated changes (CSS, JS, etc.).\n" }, { "info": { "name": "Update a version within an MVT section", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/sections/:section_id/versions/:version_id/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the given experience" }, { "name": "section_id", "value": "", "type": "path", "description": "The ID of the section under which the updated version exists" }, { "name": "version_id", "value": "", "type": "path", "description": "The ID of the updated version" }, { "name": "include", "value": "", "type": "query", "description": "Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies an existing version within a specific section of a multivariate (MVT) experience.\nThis can include changing the version's name or updating its associated changes.\n" }, { "info": { "name": "Delete a version from an MVT section", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/experiences/:experience_id/sections/:section_id/versions/:version_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "experience_id", "value": "", "type": "path", "description": "The ID of the given experience" }, { "name": "section_id", "value": "", "type": "path", "description": "The ID of the section under which the updated version exists" }, { "name": "version_id", "value": "", "type": "path", "description": "The ID of the updated version" } ] }, "docs": "Permanently removes a version from a specific section of a multivariate (MVT) experience.\nDeleting versions can affect the combinations tested and the statistical validity of an active MVT.\n" } ] }, { "info": { "name": "Cdn Images", "type": "folder" }, "items": [ { "info": { "name": "List uploaded images for a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/images", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of images that have been uploaded to the Convert CDN for a specific project.\nThese images can be used in experience variations. Supports pagination.\nThe Knowledge Base article \"Image Upload Guidelines for Convert Visual Editor\" mentions image upload limits.\n" }, { "info": { "name": "Upload an image to the project's CDN storage", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/images/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" } ], "body": { "type": "multipart-form", "data": [] } }, "docs": "Upload an image to the project's CDN storage" }, { "info": { "name": "Delete an image from the project's CDN storage", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/images/:image_key/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "image_key", "value": "", "type": "path", "description": "The key of the image file to be deleted" } ] }, "docs": "Delete an image from the project's CDN storage" } ] }, { "info": { "name": "Files", "type": "folder" }, "items": [ { "info": { "name": "Upload a generic file to project storage", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/files/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" } ], "body": { "type": "multipart-form", "data": [] } }, "docs": "Upload a generic file to project storage" }, { "info": { "name": "Get content of an uploaded file", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/files/:file_key", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "file_key", "value": "", "type": "path", "description": "The key of the file to retrieve" } ] }, "docs": "Retrieves the content of a previously uploaded file, identified by its `file_key`.\nThe file content is returned base64 encoded.\n" }, { "info": { "name": "Delete an uploaded file from project storage", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/files/:file_key/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to be retrieved" }, { "name": "file_key", "value": "", "type": "path", "description": "The key of the file to be deleted" } ] }, "docs": "Delete an uploaded file from project storage" } ] }, { "info": { "name": "Goals", "type": "folder" }, "items": [ { "info": { "name": "List goals within a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/goals", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of all conversion goals defined for a specific project.\nGoals are used to measure the success of experiences (e.g., purchases, sign-ups, page views).\nSupports filtering by status, type, name, and pagination.\nThe Knowledge Base article \"Goals\" describes various goal types like 'Visit a specific page', 'Revenue goal', 'Click on a link', etc.\n" }, { "info": { "name": "Get details for a specific goal", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/goals/:goal_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "goal_id", "value": "", "type": "path", "description": "ID of the goal to be retrieved" }, { "name": "include", "value": "", "type": "query", "description": "Specifies the list of optional fields which would be included in the response.\n\nOtherwise, the fields that can be passed through this parameter would not be included in the response.\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" } ] }, "docs": "Retrieves detailed information about a single conversion goal, identified by its `goal_id`.\nThis 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.\nThe `include` parameter can fetch additional data like usage statistics.\n" }, { "info": { "name": "Get goal details by its unique key", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/goals/:goal_key", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "goal_key", "value": "", "type": "path", "description": "Key of the goal to be retrieved" }, { "name": "include", "value": "", "type": "query", "description": "Specifies the list of optional fields which would be included in the response.\n\nOtherwise, the fields that can be passed through this parameter would not be included in the response.\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" } ] }, "docs": "Retrieves detailed information about a single conversion goal, identified by its user-defined `goal_key`.\nUseful if you have a human-readable key for a goal. Otherwise, similar to getting a goal by ID.\n" }, { "info": { "name": "Create a new conversion goal", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/goals/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the goal is to be stored" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Defines a new conversion goal within a project.\nRequires specifying the goal name and type (e.g., 'visits_page', 'revenue', 'clicks_link', 'submits_form', 'code_trigger').\nDepending 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.\nThe Knowledge Base article \"Goals\" (Use a goal template section) lists various types.\n" }, { "info": { "name": "Update an existing conversion goal", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/goals/:goal_id/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "goal_id", "value": "", "type": "path", "description": "ID of the goal to be updated" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies the configuration of an existing conversion goal.\nThis can include changing its name, type, status (active/archived), or specific settings like the target URL or triggering rules.\n" }, { "info": { "name": "Delete a conversion goal", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/goals/:goal_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "goal_id", "value": "", "type": "path", "description": "ID of the goal to be deleted" } ] }, "docs": "Permanently removes a conversion goal from a project.\nThis action is irreversible. If the goal is in use by active experiences, consider archiving it instead.\n" }, { "info": { "name": "Update multiple goals at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/goals/bulk-update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Allows for changing the status (e.g., active, archived) of multiple goals within a project simultaneously.\nRequires a list of goal IDs and the target status.\n" }, { "info": { "name": "Delete multiple goals at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/goals/bulk-delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Permanently removes multiple goals from a project in a single operation.\nRequires a list of goal IDs. This action is irreversible.\n" }, { "info": { "name": "Clone an existing conversion goal", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/goals/:goal_id/clone", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "goal_id", "value": "", "type": "path", "description": "ID of the goal to be deleted" }, { "name": "include", "value": "", "type": "query", "description": "Specifies the list of optional fields which would be included in the response.\n\nOtherwise, the fields that can be passed through this parameter would not be included in the response.\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" } ] }, "docs": "Creates a new goal as an identical copy of an existing one (specified by `goal_id`).\nUseful for creating a similar goal with minor modifications or for templating.\n" } ] }, { "info": { "name": "Tags", "type": "folder" }, "items": [ { "info": { "name": "List tags within a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/tags", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of all tags defined for a specific project.\nTags are keywords used to categorize and organize experiences, goals, audiences, etc., for easier management and filtering.\nThe Knowledge Base article \"Adding tags to your Experiences\" explains their use.\n" }, { "info": { "name": "Get details for a specific tag", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/tags/:tag_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the tag is stored" }, { "name": "tag_id", "value": "", "type": "path", "description": "ID of the tag to be retrieve" } ] }, "docs": "Retrieves information about a single tag, identified by its `tag_id`.\nThis includes its name and description.\n" }, { "info": { "name": "Create a new tag", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/tags/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the tag is to be stored" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Defines a new tag within a project. Requires a tag name and an optional description.\nTags can then be applied to experiences, goals, etc., to help organize them.\n" }, { "info": { "name": "Update an existing tag", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/tags/:tag_id/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the tag is to be stored" }, { "name": "tag_id", "value": "", "type": "path", "description": "ID of the tag to be updated" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies the name or description of an existing tag.\n" }, { "info": { "name": "Delete a tag", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/tags/:tag_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project from which the tag is to be deleted" }, { "name": "tag_id", "value": "", "type": "path", "description": "ID of the tag to be deleted" } ] }, "docs": "Permanently removes a tag from a project.\nThis does not delete the items (experiences, goals, etc.) that were associated with the tag, but simply removes the tag association.\n" }, { "info": { "name": "Delete multiple tags at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/tags/bulk-delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Permanently removes multiple tags from a project in a single operation.\nRequires a list of tag IDs.\n" } ] }, { "info": { "name": "Hypotheses", "type": "folder" }, "items": [ { "info": { "name": "List hypotheses within a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/hypotheses", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of all hypotheses defined for a specific project.\nA hypothesis is an assumption about a proposed change and its expected impact, forming the basis for an experiment.\nSupports filtering by status, score, name, and pagination.\nThe 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.\"\n" }, { "info": { "name": "Get details for a specific hypothesis", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/hypotheses/:hypothesis_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the hypothesis is stored" }, { "name": "hypothesis_id", "value": "", "type": "path", "description": "ID of the hypothesis to be retrieve" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ] }, "docs": "Retrieves detailed information about a single hypothesis, identified by its `hypothesis_id`.\nThis includes its name, objective, prioritization score (PIE or ICE), status, associated experiences, and tags.\n" }, { "info": { "name": "Create a new hypothesis", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/hypotheses/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the hypothesis is to be stored" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Defines a new hypothesis within a project.\nRequires 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.\nThe Knowledge Base article \"Hypotheses (Compass)\" details the PIE (Potential, Importance, Ease) and ICE (Impact, Confidence, Ease) models.\n" }, { "info": { "name": "Update an existing hypothesis", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/hypotheses/:hypothesis_id/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the hypothesis is to be updated" }, { "name": "hypothesis_id", "value": "", "type": "path", "description": "ID of the hypothesis to be updated" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies the details of an existing hypothesis, such as its name, objective, prioritization scores, status, or associated experiences and tags.\n" }, { "info": { "name": "Update the status of a hypothesis", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/hypotheses/:hypothesis_id/update-status", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the hypothesis is stored" }, { "name": "hypothesis_id", "value": "", "type": "path", "description": "ID of the hypothesis to be updated" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Changes the status of an existing hypothesis (e.g., from 'draft' to 'completed', 'applied', 'proven', 'disproven', or 'archived').\nThis helps track the lifecycle of a hypothesis from idea to tested outcome.\n" }, { "info": { "name": "Convert a proven/disproven hypothesis to a Knowledge Base entry", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/hypotheses/:hypothesis_id/convert", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the hypothesis is going to be converted" }, { "name": "hypothesis_id", "value": "", "type": "path", "description": "ID of the hypothesis to be converted" } ] }, "docs": "Moves a hypothesis (typically one that is 'proven' or 'disproven' after testing) into the Knowledge Base.\nThis archives the learnings from the hypothesis for future reference and organizational learning.\nThe Knowledge Base article \"Hypotheses (Compass)\" mentions: \"Proven hypotheses can then be moved to the Knowledge Base\".\n" }, { "info": { "name": "Delete a hypothesis", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/hypotheses/:hypothesis_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project from which the hypothesis is to be deleted" }, { "name": "hypothesis_id", "value": "", "type": "path", "description": "ID of the hypothesis to be deleted" } ] }, "docs": "Permanently removes a hypothesis from a project. This action is irreversible.\n" }, { "info": { "name": "Update multiple hypotheses at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/hypotheses/bulk-update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Allows for changing the status of multiple hypotheses within a project simultaneously.\nRequires a list of hypothesis IDs and the target status.\n" }, { "info": { "name": "Delete multiple hypotheses at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/hypotheses/bulk-delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Permanently removes multiple hypotheses from a project in a single operation.\nRequires a list of hypothesis IDs. This action is irreversible.\n" } ] }, { "info": { "name": "Knowledge Bases", "type": "folder" }, "items": [ { "info": { "name": "List Knowledge Base entries within a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/knowledge-bases", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of all Knowledge Base entries for a specific project.\nThe Knowledge Base stores proven or disproven hypotheses and their outcomes, serving as a repository of experimental learnings.\nSupports filtering by status, name, and pagination.\nThe Knowledge Base article \"Observations Feature Guide\" explains: \"Knowledge Base - Convert proven hypotheses to serve as a historical record and knowledge resource.\"\n" }, { "info": { "name": "Get details for a specific Knowledge Base entry", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/knowledge-bases/:knowledge_base_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the knowledge base is stored" }, { "name": "knowledge_base_id", "value": "", "type": "path", "description": "ID of the knowledge base to be retrieve" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ] }, "docs": "Retrieves detailed information about a single Knowledge Base entry, identified by its `knowledge_base_id`.\nThis includes the original hypothesis name, summary of findings, status, and associated tags.\n" }, { "info": { "name": "Create a new Knowledge Base entry", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/knowledge-bases/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the knowledge base is to be stored" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Adds a new entry to the Knowledge Base. This is typically done by converting a 'proven' or 'disproven' hypothesis,\nbut can also be used to manually add other experimental learnings.\nRequires a name, summary, and status.\n" }, { "info": { "name": "Update the status of a Knowledge Base entry", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/knowledge-bases/:knowledge_base_id/update-status", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the knowledge base is to be updated" }, { "name": "knowledge_base_id", "value": "", "type": "path", "description": "ID of the knowledge base to be updated" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Changes the status of an existing Knowledge Base entry (e.g., from 'active' to 'archived').\n" }, { "info": { "name": "Delete a Knowledge Base entry", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/knowledge-bases/:knowledge_base_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project from which the knowledge base is to be deleted" }, { "name": "knowledge_base_id", "value": "", "type": "path", "description": "ID of the knowledge base to be deleted" } ] }, "docs": "Permanently removes a Knowledge Base entry from a project. This action is irreversible.\n" }, { "info": { "name": "Update multiple Knowledge Base entries at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/knowledge-bases/bulk-update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Allows for changing the status (e.g., active, archived) of multiple Knowledge Base entries within a project simultaneously.\nRequires a list of Knowledge Base entry IDs and the target status.\n" }, { "info": { "name": "Delete multiple Knowledge Base entries at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/knowledge-bases/bulk-delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Permanently removes multiple Knowledge Base entries from a project in a single operation.\nRequires a list of Knowledge Base entry IDs. This action is irreversible.\n" } ] }, { "info": { "name": "Observations", "type": "folder" }, "items": [ { "info": { "name": "List observations within a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/observations", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of all observations recorded for a specific project.\nObservations are initial insights, ideas, or user behaviors noted by the team, which can later be developed into hypotheses.\nSupports filtering by status, name, tags, and pagination.\nThe Knowledge Base article \"Observations Feature Guide\" explains: \"Observations - Document initial insights directly.\"\n" }, { "info": { "name": "Get details for a specific observation", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/observations/:observation_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the observation is stored" }, { "name": "observation_id", "value": "", "type": "path", "description": "ID of the observation to be retrieve" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ] }, "docs": "Retrieves detailed information about a single observation, identified by its `observation_id`.\nThis includes its name, description, reference URL, status, associated tags, and any attachments (images/files).\n" }, { "info": { "name": "Create a new observation", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/observations/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the observation is to be stored" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Records a new observation within a project.\nRequires a name, and can include a description, reference URL, status, tags, and attachments (images/files).\nObservations are the first step in the ideation process, leading to hypotheses.\nThe Knowledge Base article \"Observations Feature Guide\" details this: \"Observations serve as the starting point in documenting insights.\"\n" }, { "info": { "name": "Update an existing observation", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/observations/:observation_id/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the observation is to be updated" }, { "name": "observation_id", "value": "", "type": "path", "description": "ID of the observation to be updated" }, { "name": "expand", "value": "", "type": "query", "description": "Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.\n\nRead more in the section related to [Expanding Fields](#tag/Expandable-Fields)\n" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies the details of an existing observation, such as its name, description, URL, status, tags, or attachments.\n" }, { "info": { "name": "Delete an observation", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/observations/:observation_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project from which the observation is to be deleted" }, { "name": "observation_id", "value": "", "type": "path", "description": "ID of the observation to be deleted" } ] }, "docs": "Permanently removes an observation from a project. This action is irreversible.\n" }, { "info": { "name": "Update multiple observations at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/observations/bulk-update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Allows for changing the status (e.g., active, archived) of multiple observations within a project simultaneously.\nRequires a list of observation IDs and the target status.\n" }, { "info": { "name": "Delete multiple observations at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/observations/bulk-delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Permanently removes multiple observations from a project in a single operation.\nRequires a list of observation IDs. This action is irreversible.\n" } ] }, { "info": { "name": "Locations", "type": "folder" }, "items": [ { "info": { "name": "List locations within a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/locations", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of all locations defined for a specific project.\nLocations define *where* on a website an experience will run, based on URL patterns, page tags, or JavaScript conditions.\nSupports filtering by status, name, and pagination.\nThe Knowledge Base article \"Locations\" explains: \"Locations conditions include the pages on which the experiment will run.\"\n" }, { "info": { "name": "Get details for a specific location", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/locations/:location_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the Location is stored" }, { "name": "location_id", "value": "", "type": "path", "description": "ID of the Location to be retrieved" }, { "name": "include", "value": "", "type": "query", "description": "Specifies the list of fields to be included in the response, which otherwise would not be sent.\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" } ] }, "docs": "Retrieves detailed information about a single location, identified by its `location_id`.\nThis includes its name, status, triggering rules (e.g., URL matches, JS conditions), and the type of trigger (e.g., upon_run, manual, dom_element).\nThe `include` parameter can fetch additional data like usage statistics.\n" }, { "info": { "name": "Create a new location", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/locations/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the location is to be stored" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Defines a new location within a project.\nRequires a name and a set of rules (e.g., URL contains 'product/', JS condition `window.userType === 'premium'`).\nAlso requires specifying the trigger type (e.g., 'upon_run' to activate when rules match on page load, or 'manual' to activate via JavaScript call).\nThe Knowledge Base article \"Creating Effective Experiences: A Guide to Location Setup\" describes different trigger options.\n" }, { "info": { "name": "Update an existing location", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/locations/:location_id/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the location is stored" }, { "name": "location_id", "value": "", "type": "path", "description": "ID of the location to be updated" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies the configuration of an existing location.\nThis can include changing its name, status (active/archived), triggering rules, or trigger type.\n" }, { "info": { "name": "Delete a location", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/locations/:location_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "location_id", "value": "", "type": "path", "description": "ID of the location to be deleted" } ] }, "docs": "Permanently removes a location from a project. This action is irreversible.\nIf the location is in use by active experiences, consider archiving it instead or unlinking it from experiences first.\n" }, { "info": { "name": "Update multiple locations at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/locations/bulk-update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Allows for changing the status (e.g., active, archived) of multiple locations within a project simultaneously.\nRequires a list of location IDs and the target status.\n" }, { "info": { "name": "Delete multiple locations at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/locations/bulk-delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Permanently removes multiple locations from a project in a single operation.\nRequires a list of location IDs. This action is irreversible.\n" }, { "info": { "name": "List predefined location templates (presets)", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/locations-presets", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ] }, "docs": "Retrieves a list of predefined location templates (presets) available for use.\nThese presets offer common targeting configurations (e.g., \"All Pages\", \"Homepage\") to speed up location setup.\nThe Knowledge Base article \"Creating Effective Experiences: A Guide to Location Setup\" mentions \"Saved Locations\" which are user-created, these are system presets.\n" }, { "info": { "name": "Clone an existing location", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/locations/:location_id/clone", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "location_id", "value": "", "type": "path", "description": "ID of the location to be deleted" }, { "name": "include", "value": "", "type": "query", "description": "Specifies the list of fields to be included in the response, which otherwise would not be sent.\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" } ] }, "docs": "Creates a new location as an identical copy of an existing one (specified by `location_id`).\nUseful for creating a similar location with minor modifications or for templating.\n" } ] }, { "info": { "name": "Audiences", "type": "folder" }, "items": [ { "info": { "name": "List audiences within a project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/audiences", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of all audiences defined for a specific project.\nAudiences segment visitors based on criteria like behavior, demographics, traffic source, or custom data, to target experiences.\nSupports filtering by status, type, name, and pagination.\nThe 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\".\n" }, { "info": { "name": "Get details for a specific audience", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/audiences/:audience_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the audience is stored" }, { "name": "audience_id", "value": "", "type": "path", "description": "ID of the audience to be retrieved" }, { "name": "include", "value": "", "type": "query", "description": "Specifies the list of fields to be included in the response, which otherwise would not be sent.\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" } ] }, "docs": "Retrieves detailed information about a single audience, identified by its `audience_id`.\nThis 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).\nThe `include` parameter can fetch additional data like usage statistics.\n" }, { "info": { "name": "Create a new audience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/audiences/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the audience is to be stored" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Defines a new audience within a project.\nRequires a name, type (permanent, transient, segmentation), and a set of rules defining the audience criteria.\nRules 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.\nThe Knowledge Base article \"Define an Advanced Audience\" lists many available conditions.\n" }, { "info": { "name": "Update an existing audience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/audiences/:audience_id/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the audience is stored" }, { "name": "audience_id", "value": "", "type": "path", "description": "ID of the audience to be updated" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies the configuration of an existing audience.\nThis can include changing its name, type, status (active/archived), or the rules defining its criteria.\n" }, { "info": { "name": "Delete an audience", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/audiences/:audience_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "audience_id", "value": "", "type": "path", "description": "ID of the audience to be deleted" } ] }, "docs": "Permanently removes an audience from a project. This action is irreversible.\nIf the audience is in use by active experiences, consider archiving it instead or unlinking it from experiences first.\n" }, { "info": { "name": "Update multiple audiences at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/audiences/bulk-update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Allows for changing the status (e.g., active, archived) of multiple audiences within a project simultaneously.\nRequires a list of audience IDs and the target status.\n" }, { "info": { "name": "Delete multiple audiences at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/audiences/bulk-delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Permanently removes multiple audiences from a project in a single operation.\nRequires a list of audience IDs. This action is irreversible.\n" }, { "info": { "name": "List predefined audience templates (presets)", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/audiences-presets", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ] }, "docs": "Retrieves a list of predefined audience templates (presets) available for use.\nThese presets offer common targeting configurations (e.g., \"New Visitors\", \"Mobile Users\", \"Visitors from Google\") to speed up audience setup.\nThe Knowledge Base article \"Define an Audience from the Templates\" describes this.\n" }, { "info": { "name": "Clone an existing audience", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/audiences/:audience_id/clone", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "audience_id", "value": "", "type": "path", "description": "ID of the audience to be deleted" }, { "name": "include", "value": "", "type": "query", "description": "Specifies the list of fields to be included in the response, which otherwise would not be sent.\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" } ] }, "docs": "Creates a new audience as an identical copy of an existing one (specified by `audience_id`).\nUseful for creating a similar audience with minor modifications or for templating.\n" } ] }, { "info": { "name": "Features", "type": "folder" }, "items": [ { "info": { "name": "List features within a Full Stack project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/features", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Retrieves a list of all features defined for a specific Full Stack project.\nFeatures are used for feature flagging and server-side experimentation, allowing control over functionality and variables.\nSupports filtering by name, key, status, and pagination.\nThe Knowledge Base article \"Full Stack Experiments on Convert\" provides context.\n" }, { "info": { "name": "Get details for a specific feature", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/features/:feature_id", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "feature_id", "value": "", "type": "path", "description": "ID of the feature to be retrieved" }, { "name": "include", "value": "", "type": "query", "description": "Specifies the list of optional fields which would be included in the response.\n\nOtherwise, the fields that can be passed through this parameter would not be included in the response.\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" } ] }, "docs": "Retrieves detailed information about a single feature within a Full Stack project, identified by its `feature_id`.\nThis includes its name, key, status, description, and defined variables (with their types and default values).\n" }, { "info": { "name": "Get feature details by its unique key", "type": "http" }, "http": { "method": "GET", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/features/:feature_key", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "feature_key", "value": "", "type": "path", "description": "Key of the feature to be retrieved" }, { "name": "include", "value": "", "type": "query", "description": "Specifies the list of optional fields which would be included in the response.\n\nOtherwise, the fields that can be passed through this parameter would not be included in the response.\n\nRead more in the section related to [Optional Fields](#tag/Optional-Fields)\n" } ] }, "docs": "Retrieves detailed information about a single feature, identified by its user-defined `feature_key`.\nUseful if you have a human-readable key for a feature. Otherwise, similar to getting a feature by ID.\n" }, { "info": { "name": "Create a new feature for a Full Stack project", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/features/add", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project into which the feature is to be stored" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Defines a new feature within a Full Stack project.\nRequires a name, a unique key, and a list of variables associated with the feature.\nEach variable has a key, type (string, boolean, integer, float, json), and a default value.\nFeatures are used in Full Stack experiments to control different code paths or configurations.\n" }, { "info": { "name": "Update an existing feature", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/features/:feature_id/update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "feature_id", "value": "", "type": "path", "description": "ID of the feature to be updated" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Modifies the configuration of an existing feature in a Full Stack project.\nThis can include changing its name, description, status (active/archived), or its associated variables (adding, removing, or modifying variables and their default values).\n" }, { "info": { "name": "Delete a feature", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/features/:feature_id/delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" }, { "name": "feature_id", "value": "", "type": "path", "description": "ID of the feature to be deleted" } ] }, "docs": "Permanently removes a feature from a Full Stack project. This action is irreversible.\nIf the feature is in use by active experiments, consider its impact before deletion.\n" }, { "info": { "name": "Update multiple features at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/features/bulk-update", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Allows for changing the status (e.g., active, archived) of multiple features within a Full Stack project simultaneously.\nRequires a list of feature IDs and the target status.\n" }, { "info": { "name": "Delete multiple features at once", "type": "http" }, "http": { "method": "POST", "url": "https://api.convert.com/api/v2/accounts/:account_id/projects/:project_id/features/bulk-delete", "params": [ { "name": "account_id", "value": "", "type": "path", "description": "ID of the account that owns the retrieved/saved data" }, { "name": "project_id", "value": "", "type": "path", "description": "ID of the project to which save/retrieved data is connected" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Permanently removes multiple features from a Full Stack project in a single operation.\nRequires a list of feature IDs. This action is irreversible.\n" } ] } ], "bundled": true }