openapi: 3.1.0
info:
title: Convert Accounts User API
description: 'Move your app forward with the Convert API. The Convert API allows
you to manage your Convert Experiences projects using code. The REST API is
an interface for managing and extending functionality of Convert. For
example, instead of creating and maintaining projects using the Convert
Experiences web dashboard you can create an experiment programmatically.
Additionally, if you prefer to run custom analysis on experiment results you
can leverage the API to pull data from Convert Experiences into your own
workflow. If you do not have a Convert account already, sign up for a free
developer account at https://www.convert.com/api/.
*[Convert API V1](/doc/v1) is still available and documentation can be found [here](/doc/v1) but using it is highly discouraged
as it will be phased out in the future*
'
version: 2.0.0
servers:
- url: https://api.convert.com/api/v2
description: Live API server
- url: https://apidev.convert.com/api/v2
description: DEV API server
- url: http://apidev.convert.com:5000/api/v2
description: DEV mocked API server
tags:
- name: User
description: Authenticated user related endpoints
paths:
/access-roles:
get:
operationId: getAccessRoles
summary: List available user access roles
description: 'Retrieves a list of all predefined access roles within the Convert system (e.g., Owner, Admin, Editor, Reviewer, Browse).
Each role defines a set of permissions that dictate what actions a user can perform on accounts and projects.
This is useful for understanding permission levels when managing collaborators.
'
tags:
- User
responses:
'200':
$ref: '#/components/responses/AccessRolesListResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/user:
get:
operationId: getUserData
summary: Get current authenticated user's details
description: 'Retrieves the profile data, preferences, and settings for the currently authenticated user (via cookie).
This includes information like email, name, and UI preferences.
Note: This endpoint is for cookie-based authentication. For API key authentication, user context is tied to the key itself.
'
tags:
- User
responses:
'200':
$ref: '#/components/responses/UserDataResponse'
put:
operationId: updateUserProfileData
summary: Update current user's profile
description: 'Allows the authenticated user (via cookie) to update their profile information, such as name, email, or password.
Also used to manage Multi-Factor Authentication (MFA) settings.
User preferences (like UI display settings) are managed via a separate endpoint.
'
tags:
- User
requestBody:
$ref: '#/components/requestBodies/UserUpdateProfileDataRequest'
responses:
'200':
$ref: '#/components/responses/UserDataResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/user/confirm-email:
post:
operationId: confirmEmail
summary: Confirm user email address change
description: 'Finalizes an email address change request by submitting the confirmation code sent to the new email address.
Used in cookie-based authentication flows.
'
tags:
- User
requestBody:
$ref: '#/components/requestBodies/ConfirmEmailRequest'
responses:
'200':
$ref: '#/components/responses/UserDataResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/user/preferences:
post:
operationId: updateUserPreferences
summary: Update user's UI preferences
description: 'Allows the authenticated user (via cookie) to update their preferences for the Convert application UI,
such as default column visibility in tables or editor settings. These settings do not affect experiment behavior.
'
tags:
- User
requestBody:
$ref: '#/components/requestBodies/UserUpdatePreferencesRequest'
responses:
'200':
$ref: '#/components/responses/UserDataResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/user/mfa-secret:
post:
operationId: generateMfaSecret
summary: Generate MFA secret for authenticator app
description: 'Generates a new Multi-Factor Authentication (MFA) secret for the authenticated user (cookie-based).
This secret is used to set up an authenticator app (like Google Authenticator) for generating time-based one-time passwords (TOTPs).
'
tags:
- User
responses:
'200':
$ref: '#/components/responses/UserMfaSecretResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/user/accept-demo-project:
post:
operationId: acceptDemoProject
summary: Accept and create a demo project for the user
description: 'Allows a user to accept the creation of a pre-configured demo project in their account.
This is typically used for onboarding or trial experiences to showcase Convert''s features.
'
tags:
- User
responses:
'200':
$ref: '#/components/responses/SuccessResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/user/sessions:
post:
operationId: listUserSessions
summary: List authorized sessions for the current user
description: 'Cookie-authenticated endpoint that returns all active authorized sessions for the current user,
including the current cookie-based session and any OAuth bearer-token sessions the user has approved.
'
tags:
- User
responses:
'200':
$ref: '#/components/responses/UserSessionsListResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/user/sessions/revoke:
post:
operationId: revokeUserSession
summary: Revoke User session
description: 'Cookie-authenticated endpoint that revokes a single session (cookie-based or OAuth) for the current user, identified by its sid.
'
tags:
- User
requestBody:
$ref: '#/components/requestBodies/UserSessionRevokeRequest'
responses:
'200':
$ref: '#/components/responses/UserSessionRevokeResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/user/sessions/revoke-all:
post:
operationId: revokeAllUserSessions
summary: Revoke all User sessions
description: 'Cookie-authenticated endpoint that revokes every active session (cookie-based and OAuth) for the current user.
'
tags:
- User
responses:
'200':
$ref: '#/components/responses/UserSessionRevokeAllResponse'
default:
$ref: '#/components/responses/ErrorResponse'
components:
schemas:
ProjectLiveDataPersistentOptions:
allOf:
- $ref: '#/components/schemas/ProjectLiveFilteringOptions'
- $ref: '#/components/schemas/LiveDataAutoRefreshSettings'
- type: object
properties:
columns:
type: array
nullable: true
description: 'Sorted list of columns to be displayed in the UI
'
items:
allOf:
- $ref: '#/components/schemas/ColumnPreference'
- type: object
properties:
name:
$ref: '#/components/schemas/ProjectLiveDataColumnNames'
AccountHistoryColumnNames:
type: string
description: Available columns for the account change history log in the UI.
enum:
- timestamp
- project_id
- event
- object
- method
- more_info
ReportingSegmentsCountry:
type: string
description: 'The two-letter ISO 3166-1 alpha-2 country code of the visitor, determined by IP geolocation.
Used for segmenting reports by country to analyze geographical performance.
Knowledge Base: "How Do I Target by Geographic Location Like City, Region or Country?".
'
maxLength: 2
minLength: 2
FeaturesListPersistentOptions:
allOf:
- $ref: '#/components/schemas/FeaturesListFilteringOptions'
- type: object
properties:
columns:
type: array
nullable: true
description: 'Sorted list of columns to be displayed in the UI
'
items:
allOf:
- $ref: '#/components/schemas/ColumnPreference'
- type: object
properties:
name:
$ref: '#/components/schemas/FeaturesListColumnNames'
CommonBasicPermissions:
type: object
properties:
add:
type: boolean
edit:
type: boolean
view:
type: boolean
delete:
type: boolean
ExperienceHistoryObjects:
type: string
enum:
- report
- variation
- change
LocationStatuses:
type: string
description: 'The current status of a location:
- `active`: The location is active and can be used for targeting experiences.
- `archived`: The location is archived and no longer available for new experiences, but its definition is preserved. Archived locations can often be cloned.
Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."
'
enum:
- active
- archived
default: active
CompassColumnsNames:
type: string
description: Available tabs for the compass list in the UI.
enum:
- observations
- hypotheses
- knowledge_base
TrackingScriptReleaseTypes:
type: string
description: 'Defines the update strategy for the project''s Convert tracking script:
- `manual`: (Default) The project remains on its current script version. Updates to newer versions must be initiated manually by an administrator. Allows for controlled rollouts and rollbacks to the immediate previous version.
- `latest`: The project''s tracking script will automatically update to the newest stable version as soon as Convert releases it. Ensures access to the latest features and fixes with minimal intervention.
- `scheduled`: Updates to the latest script version are automatically applied at a predefined day and time of the week, allowing updates during off-peak hours.
KB: "Tracking Script Version Management".
'
enum:
- manual
- latest
- scheduled
SignalSessionsListPersistentOptions:
allOf:
- $ref: '#/components/schemas/SignalSessionsListFilteringOptions'
- type: object
properties:
columns:
type: array
nullable: true
description: 'Sorted list of columns to be displayed in the UI
'
items:
allOf:
- $ref: '#/components/schemas/ColumnPreference'
- type: object
properties:
name:
$ref: '#/components/schemas/SignalSessionsListColumnNames'
LiveDataEventTypes:
type: string
enum:
- view_experience
- conversion
- transaction
ReportingSegmentsSource:
type: string
description: 'The traffic source that brought the visitor to the site (e.g., ''google'', ''facebook.com'', ''direct'', ''newsletter'').
Derived from `utm_source` URL parameters or the HTTP referrer. Enables report segmentation by traffic source.
Knowledge Base: "How Do You Fill Medium, Keyword and Source Name?".
'
enum:
- campaign
- search
- referral
- direct
- ai_tool
KnowledgeBasesListFilteringOptions:
allOf:
- $ref: '#/components/schemas/ResultsPerPage'
- $ref: '#/components/schemas/SortDirection'
- type: object
properties:
sort_by:
type: string
nullable: true
default: name
description: 'A value to sort knowledge bases by specific field(s)
Defaults to **name** if not provided
'
enum:
- name
- updated_at
- status
search:
type: string
maxLength: 200
nullable: true
description: A search string that would be used to search against knowledge bases name
status:
type: array
nullable: true
description: The status of the knowledge bases you'd like to be returned; one of the below can be provided
items:
$ref: '#/components/schemas/KnowledgeBaseStatuses'
tags:
type: array
nullable: true
description: The list of tag ID's used to filter the list of returned knowledge bases
items:
type: integer
only:
description: 'Only retrieve knowledge bases with the given ids.
'
type: array
nullable: true
items:
type: integer
maxItems: 100
except:
description: 'Except knowledge bases with the given ids.
'
type: array
items:
type: integer
maxItems: 100
HypothesesListPersistentOptions:
allOf:
- $ref: '#/components/schemas/HypothesesListFilteringOptions'
- type: object
properties:
columns:
type: array
nullable: true
description: 'Sorted list of columns to be displayed in the UI
'
items:
allOf:
- $ref: '#/components/schemas/ColumnPreference'
- type: object
properties:
name:
$ref: '#/components/schemas/HypothesesListColumnNames'
ProjectsListColumnNames:
type: string
description: Available columns for the projects list in the UI.
enum:
- id
- project_name
- project_type
- active_tests
- used_visitors
- status
ReportingSegmentsFilters:
type: object
description: 'A collection of filters used to segment experience report data based on various visitor attributes and traffic sources.
Applying these filters allows for deeper analysis of how different user groups interact with experience variations.
Knowledge Base: "Using Basic and Advanced Post segmentation".
'
properties:
devices:
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsDeviceCategories'
nullable: true
browsers:
description: Filter report data for visitors using one or more specified web browsers.
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsBrowser'
nullable: true
countries:
description: Filter report data for visitors from one or more specified countries (using 2-letter ISO codes).
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsCountry'
nullable: true
visitor_types:
description: Filter report data for 'new' or 'returning' visitors.
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsVisitorType'
nullable: true
campaigns:
description: Filter report data for visitors attributed to one or more specified marketing campaign names (from `utm_campaign`).
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsCampaign'
nullable: true
custom_segments:
description: Filter report data for visitors belonging to one or more specified custom Convert Audience segments (by segment ID).
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsCustomSegment'
nullable: true
sources:
description: Filter report data for visitors from one or more specified traffic sources (e.g., 'direct', 'search', 'referral').
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsSource'
nullable: true
UserSessionEntry:
type: object
properties:
sid:
description: Session identifier.
type: string
authorized_type:
description: Display name of type of how user was authorized.
type: string
enum:
- session_cookie
- oauth
client:
description: 'Name of the client that owns this session.
'
type: string
last_used_at:
description: Last authentication time (unix timestamp).
type: integer
expires_at:
description: Absolute session expiration (unix timestamp).
type: integer
created_at:
description: Session creation time (unix timestamp).
type: integer
ConfirmEmailRequestData:
type: object
description: Contains the confirmation code required to verify a new email address for a user account.
required:
- code
properties:
code:
type: string
description: The unique verification code sent to the user's new email address. Submitting this code confirms the email change.
ProjectsListPersistentOptions:
allOf:
- $ref: '#/components/schemas/ProjectsListFilteringOptions'
- type: object
properties:
columns:
type: array
nullable: true
description: 'Sorted list of columns to be displayed in the UI
'
items:
allOf:
- $ref: '#/components/schemas/ColumnPreference'
- type: object
properties:
name:
$ref: '#/components/schemas/ProjectsListColumnNames'
ExperienceLiveDataPersistentOptions:
allOf:
- $ref: '#/components/schemas/ExperienceLiveDataFilteringOptions'
- $ref: '#/components/schemas/LiveDataAutoRefreshSettings'
- type: object
properties:
columns:
type: array
nullable: true
description: 'Sorted list of columns to be displayed in the UI
'
items:
allOf:
- $ref: '#/components/schemas/ColumnPreference'
- type: object
properties:
name:
$ref: '#/components/schemas/ExperienceLiveDataColumnNames'
AudiencesListFilteringOptions:
allOf:
- $ref: '#/components/schemas/ResultsPerPage'
- $ref: '#/components/schemas/SortDirection'
- type: object
properties:
status:
type: array
nullable: true
description: List of audience statuses to be returned
items:
$ref: '#/components/schemas/AudienceStatuses'
search:
type: string
maxLength: 200
nullable: true
description: a search string that would be used to search against audience's name or description
is_default:
type: boolean
nullable: true
description: 'A flag to filter audiences by default status
If set to true, only default audiences will be returned, if not set, all audiences will be returned
'
sort_by:
type: string
nullable: true
default: id
description: 'A value to sort audiences by specific field
Defaults to **id** if not provided
'
enum:
- id
- type
- name
- usage
- status
- key
type:
allOf:
- $ref: '#/components/schemas/AudienceTypes'
nullable: true
experiences:
type: array
nullable: true
description: List of experiences to be returned
items:
type: integer
maxItems: 100
usage:
type: string
nullable: true
description: It indicates wherever retrieved audiences are used or not inside experiences
enum:
- used
- not_used
ErrorData:
type: object
properties:
code:
type: integer
format: int32
message:
oneOf:
- type: string
- type: array
items:
type: string
fields:
oneOf:
- type: string
- type: array
items:
type: string
GoalsListPersistentOptions:
allOf:
- $ref: '#/components/schemas/GoalsListFilteringOptions'
- type: object
properties:
columns:
type: array
nullable: true
description: 'Sorted list of columns to be displayed in the UI
'
items:
allOf:
- $ref: '#/components/schemas/ColumnPreference'
- type: object
properties:
name:
$ref: '#/components/schemas/GoalsListColumnNames'
LiveDataAutoRefreshSettings:
type: object
properties:
auto_refresh:
type: object
nullable: true
properties:
speed:
type: integer
minimum: 0
maximum: 5
enabled:
type: boolean
mfaDisableRequest:
type: object
description: Request to disable Multi-Factor Authentication (MFA) for the user.
properties:
type:
type: string
enum:
- disable
password:
description: The user's current password, required to authorize disabling MFA.
type: string
LocationsListColumnNames:
type: string
description: Available columns for the locations list in the UI.
enum:
- name
- id
- usage
- status
- key
RolePermissions:
type: object
properties:
account:
type: object
properties:
manage_addons:
type: boolean
manage_sso:
type: boolean
manage_api_keys:
type: boolean
manage_blocked_ips:
type: boolean
edit:
type: boolean
billing:
type: object
properties:
managePlan:
type: boolean
manage_billing:
type: boolean
manage_payment:
type: boolean
request_payment:
type: boolean
feature:
$ref: '#/components/schemas/CommonBasicPermissions'
livedata:
type: object
properties:
view_account_livedata:
type: boolean
view_project_livedata:
type: boolean
view_experience_livedata:
type: boolean
history:
type: object
properties:
view_account_history:
type: boolean
view_project_history:
type: boolean
view_experience_history:
type: boolean
collaborator:
type: object
properties:
view:
type: boolean
crud:
type: boolean
project:
allOf:
- $ref: '#/components/schemas/CommonBasicPermissions'
- type: object
properties:
import:
type: boolean
export:
type: boolean
domain:
$ref: '#/components/schemas/CommonBasicPermissions'
tag:
$ref: '#/components/schemas/CommonBasicPermissions'
goal:
allOf:
- $ref: '#/components/schemas/CommonBasicPermissions'
- type: object
properties:
clone:
type: boolean
experience:
allOf:
- $ref: '#/components/schemas/CommonBasicPermissions'
- type: object
properties:
edit_running:
type: boolean
clone:
type: boolean
pauseplay:
type: boolean
location:
allOf:
- $ref: '#/components/schemas/CommonBasicPermissions'
- type: object
properties:
edit_running:
type: boolean
variation:
type: object
properties:
pauseplay:
type: boolean
changebaseline:
type: boolean
audience:
allOf:
- $ref: '#/components/schemas/CommonBasicPermissions'
- type: object
properties:
edit_running:
type: object
report:
type: object
properties:
view:
type: boolean
fulledit:
type: boolean
nochangeedit:
type: boolean
hypothesis:
allOf:
- $ref: '#/components/schemas/CommonBasicPermissions'
- type: object
properties:
convert:
type: boolean
knowledge_base:
$ref: '#/components/schemas/CommonBasicPermissions'
observation:
$ref: '#/components/schemas/CommonBasicPermissions'
AccountExperiencesListFilteringOptions:
type: object
allOf:
- $ref: '#/components/schemas/ResultsPerPage'
- $ref: '#/components/schemas/SortDirection'
- type: object
properties:
projects:
type: array
nullable: true
description: 'Project IDs list to be used to filter experiences
'
items:
type: integer
sort_by:
type: string
nullable: true
default: id
description: 'A value used to sort experiences by specific field
Defaults to **id** if not provided
'
enum:
- id
- conversions
- improvement
- name
- start_time
- end_time
- status
- project_id
- primary_goal
search:
type: string
nullable: true
description: A search string that would be used to search against Experience's name and description
type:
type: array
nullable: true
description: The type of the experiences to be returned; either of the below can be provided
items:
$ref: '#/components/schemas/ExperienceTypes'
UserSessionRevokeAllResponseData:
type: object
required:
- code
- message
properties:
code:
type: integer
message:
type: string
ExperienceReportSecondViewPersistentOptions:
allOf:
- type: object
properties:
columns:
type: array
nullable: true
description: 'Sorted list of columns to be displayed in the UI
'
items:
allOf:
- $ref: '#/components/schemas/ColumnPreference'
- type: object
properties:
name:
$ref: '#/components/schemas/ExperienceReportSecondViewColumnNames'
ExperienceHistoryColumnNames:
type: string
description: Available columns for the experience change history log in the UI.
enum:
- timestamp
- event
- object
- object_id
- method
- more_info
HypothesisStatuses:
description: 'The current stage or outcome of a hypothesis in its lifecycle:
- `draft`: The hypothesis is still being formulated or refined; not yet ready for testing.
- `completed`: The hypothesis definition is finalized and it''s ready to be linked to an experiment or tested.
- `applied`: The hypothesis is currently being tested in one or more active experiences.
- `proven`: Testing has concluded, and the hypothesis was validated (i.e., the proposed change led to a positive, statistically significant outcome). Can be moved to Knowledge Base.
- `disproven`: Testing has concluded, and the hypothesis was invalidated (i.e., the proposed change did not lead to the expected positive outcome or had a negative impact). Can be moved to Knowledge Base.
- `archived`: The hypothesis is no longer active or relevant for current testing but is kept for historical records.
KB: "Hypotheses (Compass)" - "Status of Hypothesis".
'
type: string
enum:
- applied
- archived
- completed
- draft
- proven
- disproven
ObservationsListColumnNames:
type: string
description: Available columns for the observations list in the UI.
enum:
- name
- created_by
- created_at
- updated_at
- status
LocationsListFilteringOptions:
allOf:
- $ref: '#/components/schemas/ResultsPerPage'
- $ref: '#/components/schemas/SortDirection'
- type: object
properties:
status:
type: array
nullable: true
description: List of Location statuses to be returned
items:
$ref: '#/components/schemas/LocationStatuses'
is_default:
type: boolean
nullable: true
description: 'It indicates wherever retrieved locations are default or not
If not provided, it will return all locations. If not provided, it will return all locations
'
search:
type: string
maxLength: 200
nullable: true
description: a search string that would be used to search against Location's name or description
sort_by:
type: string
nullable: true
default: id
description: 'A value to sort Location by specific field
Defaults to **id** if not provided
'
enum:
- id
- name
- usage
- status
- key
usage:
type: string
nullable: true
description: It indicates wherever retrieved locations are used or not inside experiences
enum:
- used
- not_used
ColumnPreference:
type: object
description: Defines user preference for a single column in a UI list view (name and visibility).
properties:
visible:
type: boolean
description: If true, this column is visible in the user's list view. If false, it's hidden.
name:
type: string
description: The machine-readable name or key of the column (e.g., "id", "project_name", "status").
ObservationStatuses:
description: 'The current status of an observation in its lifecycle:
- `active`: The observation is current, under consideration, or being actively discussed. This is the default for new observations.
- `archived`: The observation has been reviewed and is no longer actively being pursued (e.g., deemed not actionable, superseded, or already addressed). It''s kept for historical records.
Knowledge Base: "Observations Feature Guide" - "Status Management".
'
type: string
enum:
- active
- archived
default: active
ExperienceReportSecondViewColumnNames:
type: string
description: Available columns for the variations-by-goals view in the experience report UI.
enum:
- variation_name
- improvement
- conversions
- visitors
- conversion_rate
- confidence
- confidence_interval
# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/convert/refs/heads/main/openapi/convert-user-api-openapi.yml