Convert
Convert is an A/B testing and experimentation platform with privacy-first analytics and integrations for marketers and developers.
1 APIs
0 Features
ExperimentationAB TestingConversion OptimizationPersonalizationAnalytics
APIs
Convert Experiences REST API v2
Convert Experiences REST API v2 manages accounts, projects, experiments, goals, audiences, locations, reports, and collaborators. Requests are signed via HMAC.
Collections
Convert API
OPENPricing Plans
Rate Limits
FinOps
Convert Finops
FINOPSResources
🔗
Website
Website
🔗
Documentation
Documentation
🔗
Plans
Plans
🔗
RateLimits
RateLimits
🔗
FinOps
FinOps
🔗
LlmsText
LlmsText
Sources
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.
Starts with username/password. If successful and MFA is not required, returns user data and sets a session cookie.
If MFA is required, or a new password needs to be set, the response will indicate the next step and provide a sessionToken.
This is primarily for UI interaction, LLMs should typically use API Key Authentication.
'
- 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.
This is part of the cookie-based authentication flow.
'
- 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.
This is part of the cookie-based authentication flow.
'
- 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).
Can also be used to log out other or all sessions for the user.
'
- 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.
'
- 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.
Enforces PKCE binding.
'
- 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.
'
- 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.
'
- 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.
'
- 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.
'
- 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).
Each role defines a set of permissions that dictate what actions a user can perform on accounts and projects.
This is useful for understanding permission levels when managing collaborators.
'
- 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).
This includes information like email, name, and UI preferences.
Note: This endpoint is for cookie-based authentication. For API key authentication, user context is tied to the key
itself.
'
- 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.
Also used to manage Multi-Factor Authentication (MFA) settings.
User preferences (like UI display settings) are managed via a separate endpoint.
'
- 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.
Used in cookie-based authentication flows.
'
- 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,
such as default column visibility in tables or editor settings. These settings do not affect experiment behavior.
'
- 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).
This secret is used to set up an authenticator app (like Google Authenticator) for generating time-based one-time passwords
(TOTPs).
'
- 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.
This is typically used for onboarding or trial experiences to showcase Convert''s features.
'
- 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,
including the current cookie-based session and any OAuth bearer-token sessions the user has approved.
'
- 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.
'
- 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.
'
- 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.
If using API key authentication, this typically returns the single account associated with the API key.
If using cookie-based authentication, it may return multiple accounts if the user is a collaborator on several.
An account is the top-level container for projects, billing, and user management.
'
- 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.
Each plan defines usage limits (e.g., tested visitors, number of projects) and available features.
'
- 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.
Useful for real-time monitoring of activity. Supports filtering by event types and specific projects.
As per the Knowledge Base, "Live Logs in Convert track how end users are interacting with web pages and experiments...at
a project and experiment level in real time."
'
- 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.
This provides an audit trail for account-level activities.
The Knowledge Base states, "The Change History shows a record of user activity for each of your projects." This extends
to account changes.
'
- 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.
Allows filtering to narrow down results. Useful for an overview of ongoing and finished optimization activities at the
account level.
'
- 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.
Read more in the section related to [Optional Fields](#tag/Optional-Fields)
'
docs: 'Retrieves detailed information about a specific account, including its settings, billing status, and usage limits.
The `include` parameter can be used to fetch additional related data, like active project counts.
'
- 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.
This can include updating company details, contact information, or billing preferences.
'
- 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.
Sub-accounts inherit certain properties and limits from the parent but can have their own users and projects.
This is typically used by agencies or larger organizations to manage client accounts or departmental usage separately.
'
- 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.
'
- 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.
Returns a client secret or token that the frontend UI uses to complete the payment setup process directly with the provider.
'
- 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.
The URL takes the customer to the Paddle billing portal where they can
check subscriptions, view or download invoices.
'
- 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.
Used internally for account management workflows.
'
- 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.
Users can specify the number of variations, the original content, an AI model framework (e.g., Cialdini, AIDA), and
a specific principle within that framework.
This helps in quickly generating creative options for A/B testing headlines, calls to action, or other textual elements.
Optionally, an OpenAI Key can be provided for using more advanced models or larger context.
'
- 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.
'
- 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.
Read more in the section related to [Expanding Fields](#tag/Expandable-Fields)
'
docs: 'Retrieves a list of all users who have collaborator access to the specified account.
For each user, it details the projects they can access and their role within those projects (e.g., Admin, Editor).
The `expand` parameter can be used to get more details about the projects.
As per the Knowledge Base, "Account owners can invite collaborators to projects and choose to give them varying privileges."
'
- 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.
This can involve changing their role for specific projects or altering which projects they can access.
Identifies the user by `user_id` (for active collaborators) or `email` (for pending invitations).
'
- 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.
The request defines the initial set of projects and the role the user will have for those projects.
The user will receive an email to accept the invitation.
'
- 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.
Identifies the user by `user_id` or `email`.
'
- 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.
This is an internal mechanism.
'
- 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.
If the user is new to Convert, this will also trigger account creation.
'
- 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.
API keys are used for server-to-server authentication, allowing applications to interact with the Convert API programmatically.
Each key can be scoped to specific projects.
'
- 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.
The key can be named for easier identification and can be restricted to a list of project IDs.
If no projects are specified, the key grants access to all projects in the account.
The API secret is only shown at the time of creation and should be stored securely.
'
- 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`.
Once deleted, the key can no longer be used to authenticate API requests.
'
- 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.
This endpoint is typically used for integrations that require access to raw session data.
Note: This is different from Convert Signals. For frustration and usability insights, see the Signal Sessions endpoint.
'
- 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.
Convert Signals™ "is a special anonymous and privacy oriented session recording feature...It shows only really clear
frustrations, errors and usability signals of real users".
Use this to identify sessions where visitors experienced issues like rage clicks, dead clicks, or scroll stalls.
Supports filtering by date, experience, variation, location, country, device, browser, and more.
'
- 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`.
'
- 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.
SDK keys are used by Convert''s Full Stack SDKs (e.g., Node.js, JavaScript) to fetch experiment configurations and track
events from server-side or client-side applications.
Each key is tied to a specific environment within the project (e.g., production, staging).
'
- 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.
This key is then used by the Convert SDKs to authenticate and fetch project configurations.
If `has_secret` is true and no `sdk_secret` is provided, a secret will be auto-generated.
The SDK secret (if generated) is only shown at the time of creation.
'
- 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.
'
- 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.
Once deleted, SDKs using this key will no longer be able to fetch configurations or track events for the associated
project and environment.
'
- 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
'
- 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
# --- truncated at 32 KB (163 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/convert/refs/heads/main/apis.yml