openapi: 3.1.0
info:
title: Convert Accounts Cookie Authentication 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: Cookie Authentication
description: 'In order to use the Convert app, user has two options to authenticate requests:
* Provide authorization token with each request works best for backend systems
* Authenticate once using username/password/IDP provider and than send session token together with each request
These endpoints will handle second case.
**IMPORTANT:** currently this is available only for Convert.com''s own clients, all other third party clients need to authenticate using API KEY Authentication
'
paths:
/auth:
post:
operationId: doAuth
summary: Authenticate user session (Cookie Based)
description: 'Initiates or continues a cookie-based authentication flow.
Starts with username/password. If successful and MFA is not required, returns user data and sets a session cookie.
If MFA is required, or a new password needs to be set, the response will indicate the next step and provide a sessionToken.
This is primarily for UI interaction, LLMs should typically use API Key Authentication.
'
tags:
- Cookie Authentication
requestBody:
$ref: '#/components/requestBodies/AuthRequest'
responses:
'200':
$ref: '#/components/responses/AuthResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/auth/forgotpassword:
post:
operationId: requestForgotPassword
summary: Request password reset
description: 'Sends an email with a password reset link to the user associated with the provided email address, if an account exists.
This is part of the cookie-based authentication flow.
'
tags:
- Cookie Authentication
requestBody:
$ref: '#/components/requestBodies/ForgotPasswordRequest'
responses:
'200':
$ref: '#/components/responses/SuccessResponse'
/auth/confirmpasswordreset:
post:
operationId: confirmPasswordReset
summary: Confirm new password after reset request
description: 'Completes the password reset process. The user provides the new password and the confirmation code received via email.
This is part of the cookie-based authentication flow.
'
tags:
- Cookie Authentication
requestBody:
$ref: '#/components/requestBodies/ResetPasswordConfirmRequest'
responses:
'200':
$ref: '#/components/responses/AuthResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/auth/logout:
post:
operationId: doLogout
summary: Log out user session
description: 'Invalidates the current authenticated user session (cookie-based).
Can also be used to log out other or all sessions for the user.
'
tags:
- Cookie Authentication
requestBody:
$ref: '#/components/requestBodies/LogoutRequest'
responses:
'200':
$ref: '#/components/responses/SuccessResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/auth/status:
get:
operationId: getAuthStatus
summary: Check authentication status
description: 'Verifies if the current cookie-based session is still valid and authenticated.
'
tags:
- Cookie Authentication
responses:
'200':
$ref: '#/components/responses/SuccessResponse'
default:
$ref: '#/components/responses/ErrorResponse'
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'
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
ForgotPasswordRequestData:
type: object
properties:
username:
description: The username or email address associated with the account for which password reset is requested.
type: string
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
MfaCodeAuthData:
allOf:
- $ref: '#/components/schemas/AuthBaseData'
- type: object
description: Represents data needed when sending an auth request providing password
properties:
mfaCode:
type: string
sessionToken:
type: string
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
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'
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
LocationsListColumnNames:
type: string
description: Available columns for the locations list in the UI.
enum:
- name
- id
- usage
- status
- key
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'
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
LogoutRequestData:
type: object
description: Specifies which cookie-based sessions to terminate for the authenticated user.
properties:
requestType:
type: string
enum:
- currentSession
- otherSessions
- allSessions
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
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
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").
ExperienceReportSecondViewColumnNames:
type: string
description: Available columns for the variations-by-goals view in the experience report UI.
enum:
- variation_name
- improvement
- conversions
- visitors
- conversion_rate
- confidence
- confidence_interval
- observed_power
- status
- expected
- risk
- traffic
- average_order_value
- average_products_per_order
AccountLiveDataPersistentOptions:
allOf:
- $ref: '#/components/schemas/AccountLiveDataFilteringOptions'
- $ref: '#/components/schemas/LiveDataAutoRefreshSettings'
- type: object
properties:
columns:
type: array
description: 'Sorted list of columns to be displayed in the UI
'
items:
allOf:
- $ref: '#/components/schemas/ColumnPreference'
- type: object
properties:
name:
$ref: '#/components/schemas/AccountLiveDataColumnNames'
AccountExperiencesListPersistentOptions:
allOf:
- $ref: '#/components/schemas/AccountExperiencesListFilteringOptions'
- type: object
properties:
columns:
nullable: true
type: array
description: 'Sorted list of columns to be displayed in the UI
'
items:
allOf:
- $ref: '#/components/schemas/ColumnPreference'
- type: object
properties:
name:
$ref: '#/components/schemas/AccountExperiencesListColumnNames'
ChangeHistoryExpandFields:
type: string
enum:
- project
UTC_Offset:
type: integer
description: 'The time offset from Coordinated Universal Time (UTC) in seconds.
For example, UTC-5 (EST) would be -18000. UTC+2 would be 7200.
Used for interpreting or displaying date/time information according to a specific timezone.
'
default: 0
minimum: -43200
maximum: 50400
PasswordAuthData:
allOf:
- $ref: '#/components/schemas/AuthBaseData'
- type: object
description: Represents data needed when sending an auth request providing password
properties:
password:
type: string
ProjectHistoryPersistentOptions:
allOf:
- $ref: '#/components/schemas/ProjectHistoryFilteringOptions'
- type: object
properties:
columns:
type: array
nullable: true
description: 'Sorted list of columns to be displayed in the UI
'
items:
allOf:
- $ref: '#/components/schemas/ColumnPreference'
- type: object
properties:
name:
$ref: '#/components/schemas/ProjectHistoryColumnNames'
UserPreferences:
type: object
description: A collection of user-specific settings that customize their experience within the Convert application UI. These preferences do not impact the execution or behavior of live experiments.
properties:
editorSettings:
type: object
properties:
codeOpen:
type: boolean
nullable: true
default: false
description: If true, the code editor panel in the Visual Editor is open by default.
codeBoxId:
type: string
nullable: true
description: The ID of the specific code editor tab (e.g., 'variationCode', 'variationJs', 'globalJs') that was last active or should be opened by default.
enum:
- variationCode
- variationJs
- variationCss
- globalJs
codeEditorMaximized:
type: boolean
nullable: true
default: false
description: If true, the code editor panel is maximized by default.
codeEditorHeight:
type: integer
nullable: true
default: 300
description: The default height (in pixels) of the code editor panel.
codeLinterOn:
type: boolean
default: false
nullable: true
description: If true, the JavaScript/CSS linter in the code editors is enabled by default.
displaySettings:
type: object
properties:
accountExperiencesList:
$ref: '#/components/schemas/AccountExperiencesListPersistentOptions'
accountLiveDataList:
$ref: '#/components/schemas/AccountLiveDataPersistentOptions'
accountHistoryList:
$ref: '#/components/schemas/AccountHistoryPersistentOptions'
projectsList:
$ref: '#/components/schemas/ProjectsListPersistentOptions'
projectExperiences:
$ref: '#/components/schemas/ExperiencesListPersistentOptions'
projectHypotheses:
$ref: '#/components/schemas/HypothesesListPersistentOptions'
projectKnowledgeBases:
$ref: '#/components/schemas/KnowledgeBasesListPersistentOptions'
projectObservations:
$ref: '#/components/schemas/ObservationsListPersistentOptions'
projectGoals:
$ref: '#/components/schemas/GoalsListPersistentOptions'
projectAudiences:
$ref: '#/components/schemas/AudiencesListPersistentOptions'
projectLocations:
$ref: '#/components/schemas/LocationsListPersistentOptions'
projectLiveData:
$ref: '#/components/schemas/ProjectLiveDataPersistentOptions'
projectHistoryList:
$ref: '#/components/schemas/ProjectHistoryPersistentOptions'
experienceLiveData:
$ref: '#/components/schemas/ExperienceLiveDataPersistentOptions'
experienceHistoryList:
$ref: '#/components/schemas/ExperienceHistoryPersistentOptions'
experienceReport:
$ref: '#/components/schemas/ExperienceReportPersistentOptions'
experienceReportFirstView:
$ref: '#/components/schemas/ExperienceReportFirstViewPersistentOptions'
experienceReportSecondView:
$ref: '#/components/schemas/ExperienceReportSecondViewPersistentOptions'
projectFeatures:
$ref: '#/components/schemas/FeaturesListPersistentOptions'
projectSdkKeys:
$ref: '#/components/schemas/SdkKeysListPersistentOptions'
projectSignalSessions:
$ref: '#/components/schemas/SignalSessionsListPersistentOptions'
projectCompass:
$ref: '#/components/schemas/CompassColumnsPersistentOptions'
uiSettings:
type: object
nullable: true
properties:
hide_demo_project:
type: boolean
description: If true, the option to create or view a demo project is hidden for this user.
onboard:
type: object
nullable: true
additionalProperties: false
properties:
remind_in:
type: integer
nullable: true
description: Unix timestamp (UTC) indicating when the next onboarding reminder or step should be displayed to the user.
notificationsSeen:
type: array
items:
type: string
enum:
- TODO-define-it
generalSettings:
type: object
properties:
lastOpenAccount:
type: integer
nullable: true
description: The ID of the acco
# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/convert/refs/heads/main/openapi/convert-cookie-authentication-api-openapi.yml