Once you start using Convert Experiences, you will have a growing number of experiences to manage. Projects help you keep everything organized across multiple sites. Each project has its own tracking code, set of experiences, and set of collaborators. For example, if you run experiences on multiple domains, you can assign a unique project for each domain. Read here some things you need to know about how a project behaves.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/convert-projects-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Convert Accounts Projects 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: Projects
description: Once you start using Convert Experiences, you will have a growing number of experiences to manage. Projects help you keep everything organized across multiple sites. Each project has its own tracking code, set of experiences, and set of collaborators. For example, if you run experiences on multiple domains, you can assign a unique project for each domain. Read <a href="https://support.convert.com/hc/en-us/articles/205150985-What-is-a-Project-">here</a> some things you need to know about how a project behaves.
paths:
/accounts/{account_id}/projects:
post:
operationId: getProjectsList
summary: List projects within an account
description: 'Retrieves a list of all projects belonging to the specified account that the authenticated user has access to.
Supports filtering by project status, name/description search, and pagination.
A project in Convert is a container for organizing experiences (A/B tests, personalizations), goals, audiences, and associated domains.
As per the Knowledge Base: "Each project has its own tracking code, set of experiences, and set of collaborators."
'
tags:
- Projects
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/GetProjectsListRequest'
responses:
'200':
$ref: '#/components/responses/ProjectsListResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/change-history:
post:
operationId: getProjectHistory
summary: Get change history for a specific project
tags:
- Projects
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
in: path
required: true
description: ID of the project to be retrieved
schema:
type: integer
description: 'Retrieves a historical log of changes made within a specific project.
This includes modifications to experiences, goals, audiences, locations, and project settings.
Provides an audit trail for project-level activities, filterable by date, user, and event type.
The Knowledge Base states: "Convert logs most actions that can be made in a Project; for example: creating an experiment, modifying a variation, adding and removing audiences, and more."
'
requestBody:
$ref: '#/components/requestBodies/GetProjectHistoryRequest'
responses:
'200':
$ref: '#/components/responses/ChangeHistoryListResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}:
get:
operationId: getProject
summary: Get details for a specific project
description: 'Retrieves comprehensive details for a single project, identified by its `project_id`.
This includes its name, type (web or fullstack), global JavaScript, settings (like time zone, jQuery inclusion), integrations, and optionally, associated domains and usage statistics.
The `include` parameter can fetch related data like `domains` or `stats.usage`. The `expand` parameter can provide full objects for linked entities.
'
tags:
- Projects
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
in: path
required: true
description: ID of the project to be retrieved
schema:
type: integer
- name: include
in: query
required: false
description: 'Specifies the list of fields to be included in the response, which otherwise would not be sent.
Read more in the section related to [Optional Fields](#tag/Optional-Fields)
'
schema:
type: array
items:
$ref: '#/components/schemas/ProjectIncludeFields'
- name: expand
in: query
required: false
description: 'Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.
Read more in the section related to [Expanding Fields](#tag/Expandable-Fields)
'
schema:
type: array
items:
$ref: '#/components/schemas/ProjectExpandFields'
responses:
'200':
$ref: '#/components/responses/ProjectResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/add:
post:
operationId: createProject
summary: Create a new project
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
tags:
- Projects
requestBody:
$ref: '#/components/requestBodies/CreateProjectRequest'
responses:
'201':
$ref: '#/components/responses/ProjectResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/update:
post:
operationId: updateProject
summary: Update an existing project
description: 'Modifies the settings of an existing project.
This can include changing its name, global JavaScript, time zone, active domains, integration settings, or GDPR compliance options.
The list of domains provided in the request will replace the existing list.
'
tags:
- Projects
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
in: path
required: true
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/UpdateProjectRequest'
responses:
'201':
$ref: '#/components/responses/ProjectResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/delete:
delete:
operationId: deleteProject
summary: Delete a project
description: 'Permanently removes an existing project and all its associated data (experiences, goals, audiences, reports) from the specified account.
This action is irreversible.
The Knowledge Base warns: "When a project is deleted all data will be purged from our servers within 7 days and is unrecoverable after that time."
'
tags:
- Projects
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
in: path
description: ID of the project to be deleted
required: true
schema:
type: integer
responses:
'200':
$ref: '#/components/responses/SuccessResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/livedata:
post:
operationId: getProjectLiveData
summary: Get live tracking events for a specific project
description: 'Retrieves the last 100 tracking events (e.g., experiment views, goal conversions) specifically for the given project.
Useful for real-time monitoring of a single project''s activity. Supports filtering by event types, experiences, and goals.
As per the Knowledge Base: "Live Logs in Convert track how end users are interacting with web pages and experiments...at a project and experiment level in real time."
'
tags:
- Projects
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
in: path
required: true
description: ID of the project for which live data is returned
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/GetProjectLiveDataRequest'
responses:
'200':
$ref: '#/components/responses/LiveDataEventsListResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/bulk-update:
post:
operationId: bulkUpdateProjects
summary: Update multiple projects at once
description: 'Allows for updating settings (like tracking script version) for multiple projects simultaneously within an account.
Requires a list of project IDs and the settings to apply.
'
tags:
- Projects
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data.
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/BulkUpdateProjectsRequest'
responses:
'200':
$ref: '#/components/responses/BulkSuccessResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/generate-debug-token:
get:
operationId: generateDebugToken
summary: Generate a debug token for a project
description: 'Creates a temporary debug token for a project. This token can be used with the Convert tracking script
(e.g., via the `convert-debug-token` header or query parameter) to preview draft or paused experiences,
or to force specific variations for QA purposes without affecting live experiment data.
The token has a limited time-to-live (TTL).
'
tags:
- Projects
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
in: path
required: true
description: ID of the project
schema:
type: integer
responses:
'200':
$ref: '#/components/responses/SuccessGeneratedDebugToken'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/export:
post:
operationId: exportProject
summary: Export project data as JSON
description: 'Generates a JSON file containing all configuration data for a specific project.
This includes its experiences, goals, audiences, locations, hypotheses, and project settings.
Useful for backing up project configurations or migrating them to another Convert account or instance.
The Knowledge Base mentions this feature for "Save and Migrate Project Settings" and "Template Creation".
'
tags:
- Projects
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
in: path
required: true
description: ID of the project
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/ExportProjectRequest'
responses:
'201':
$ref: '#/components/responses/ProjectExportResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/import-project:
post:
operationId: importProject
summary: Import project data from a JSON file
description: 'Creates a new project or updates an existing one by importing data from a JSON file (previously exported from Convert).
This allows for restoring backups or replicating project setups.
The Knowledge Base mentions this for "Save and Migrate Project Settings" and "Template Creation".
'
tags:
- Projects
parameters:
- name: account_id
in: path
required: true
description: ID of the account where the project will be stored.
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/ImportProjectRequest'
responses:
'201':
$ref: '#/components/responses/SuccessResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/import-project-data:
post:
operationId: importProjectData
summary: Import associated data into an existing project
description: 'Imports associated data (like experiences, goals, audiences) from a JSON file into an already existing project.
This is useful for selectively adding or updating components within a project from an export.
The Knowledge Base mentions "Selective Import/Export: Choose to export/import entire projects or only selected goals, audiences, and locations."
'
tags:
- Projects
parameters:
- name: account_id
in: path
required: true
description: ID of the account where the project is stored.
schema:
type: integer
- name: project_id
in: path
required: true
description: ID of the project to which details will be attached.
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/ImportProjectRequest'
responses:
'201':
$ref: '#/components/responses/ImportProjectDataSuccessResponse'
default:
$ref: '#/components/responses/ErrorResponse'
components:
schemas:
SE_ProcTypes:
type: string
description: 'The statistical methodology used for analyzing experiment results and determining winners.
- `frequentist`: Traditional hypothesis testing approach using p-values and confidence intervals (e.g., T-tests). KB: "Statistical Methods Used".
- `bayesian`: Bayesian statistical approach providing probabilities of one variation being better than another (e.g., Chance to Win). KB: "Statistical Models in Convert.com''s A/B Testing Platform".
'
enum:
- frequentist
- bayesian
Pagination:
type: object
properties:
current_page:
description: The current page number being displayed from the paginated set.
type: integer
minimum: 1
items_count:
description: The total number of items available across all pages for the current filter criteria.
type: integer
minimum: 0
items_per_page:
description: The number of items included in the current page of results (matches `results_per_page` from the request).
type: integer
minimum: 0
pages_count:
description: The total number of pages available for the current filter criteria and `results_per_page` setting.
type: integer
minimum: 0
ChangeHistoryObjects:
type: string
enum:
- audience
- feature
- domain
- goal
- hypothesis
- experience
- tag
- location
DomainToCreate:
required:
- url
allOf:
- $ref: '#/components/schemas/Domain'
IntegrationGA3:
type: object
properties:
type:
enum:
- ga3
property_UA:
type: string
maxLength: 150
nullable: true
description: The Universal Analytics Property ID (e.g., "UA-XXXXXXXX-Y") to which Convert experiment data will be sent.
LiveDataEventsListResponseData:
type: object
description: Response containing a list of recent live tracking events for a project or account.
properties:
data:
$ref: '#/components/schemas/LiveDataEventsList'
TrackingScriptReleaseLatest:
allOf:
- $ref: '#/components/schemas/TrackingScriptReleaseBase'
- type: object
additionalProperties: false
properties:
type:
enum:
- latest
SimpleLocation:
type: object
properties:
id:
type: integer
description: The unique numerical identifier of the location.
readOnly: true
name:
type: string
description: The user-defined, friendly name of the location.
maxLength: 100
ReportingSegmentsCustomSegment:
description: 'The numerical ID of a custom Convert Audience (of type ''segmentation'') that the visitor is a member of.
Allows report segmentation based on predefined custom segments (e.g., "High-Value Customers", "Engaged Users").
Knowledge Base: "Create Custom Segments".
'
type: integer
BulkProjectIds:
type: array
description: A list of project unique numerical identifiers to be affected by a bulk operation.
items:
type: integer
minItems: 1
maxItems: 100
SimpleExperienceFlat:
type: object
properties:
id:
description: The unique numerical identifier of the experience.
type: integer
variation:
$ref: '#/components/schemas/SimpleExperienceVariationExpandable'
ImportProjectRequestData:
allOf:
- type: object
properties:
file:
type: string
format: json
description: 'The JSON file containing project data to be imported.
'
required:
- file
BaseProject:
type: object
properties:
global_javascript:
type: string
nullable: true
description: 'Custom JavaScript code that will be included on all pages where this project''s tracking script is installed.
This script runs before any experience-specific code, making it suitable for global helper functions, third-party integrations setup (like analytics), or defining global variables.
KB: "Project, Experience, Variation Javascript" - "Global Project JavaScript".
'
name:
type: string
maxLength: 200
description: A user-defined, friendly name for the project (e.g., "Main Website Optimization", "Q3 Marketing Campaigns", "Mobile App Features").
project_type:
type: string
description: 'The type of project, determining its capabilities and how it''s used:
- `web`: For traditional website A/B testing, MVT, Split URL, personalization, and deploys using the client-side JavaScript tracking snippet.
- `fullstack`: For server-side experiments, feature flagging, and mobile app testing using Convert''s Full Stack SDKs.
KB: "Full Stack Experiments on Convert".
'
enum:
- web
- fullstack
default: web
reporting_settings:
allOf:
- type: object
description: Project settings used for reporting
properties:
tested_visitors_quota:
type: integer
minimum: 0
description: Maximum number of tested visitors that is allowed to go through this project in a billing cycle. After that number has been reached, no experiences that have influence over tested visitors will run in this project.
currency_symbol:
type: string
description: Currency symbol used in the reporting.
maxLength: 10
blocked_ips:
type: object
nullable: true
properties:
single:
type: array
description: List of single ip addresses blocked.
items:
type: object
minProperties: 1
properties:
value:
type: string
format: ip-address
name:
type: string
nullable: true
maxLength: 64
required:
- value
range:
type: array
description: List of ip addresses range.
items:
type: object
minProperties: 1
properties:
start:
type: string
format: ip-address
description: Starts from ip.
end:
type: string
format: ip-address
description: Ends with ip.
name:
type: string
nullable: true
maxLength: 64
required:
- start
- end
description: A list of blocked IPs that are not allowed to be counted in the reports
stop_tracking_goals_after_days:
type: string
description: 'Defines goals tracking life time: goals won''t be tracking after specified days unless used in active experiments.'
enum:
- 'OFF'
- 1 day
- 15 days
- 30 days
- 60 days
smart_recommendations:
type: boolean
default: true
description: 'Whether to run or not Smart Recommendations.
'
keep_running_until_confidence:
type: boolean
description: 'If true, experiments do not auto-complete when planned sample size (100% progress) is reached alone.
They only auto-complete when both planned sample size is reached and the confidence threshold is met.
If false, experiments complete automatically when planned sample size is reached, regardless of confidence level.
Default depends on automation toggle: when keep_winner or stop_loser is enabled, default is true; otherwise false.
'
- $ref: '#/components/schemas/ExperienceReportingSettings'
settings:
type: object
description: General operational settings for the project.
properties:
allow_crossdomain_tracking:
type: boolean
description: 'If true, enables automatic passing of Convert tracking cookies (`_conv_v`, `_conv_s`) as URL parameters when visitors navigate between different domains listed in this project''s `Active Websites`.
Essential for maintaining consistent visitor identity and experiment bucketing across multiple domains (e.g., main site to a separate checkout domain).
KB: "Cookies and Cross-Domain Testing".
'
allow_gdpr:
type: boolean
description: 'If true, displays GDPR-related warnings in the Convert UI for settings or features that might have privacy implications (e.g., using certain audience conditions, enabling cross-domain tracking).
KB: "GDPR warnings".
'
data_anonymization:
type: boolean
description: 'If true, masks the names of experiences, variations, segments, and goals in the public JavaScript tracking snippet and in data sent to some third-party integrations.
Instead of names, their numerical IDs are used. Enhances privacy by preventing public disclosure of experiment details.
KB: "Prevent Experiment Details Data Leak with Data Anonymization".
'
do_not_track:
type: string
enum:
- 'OFF'
- EU ONLY
- EEA ONLY
- Worldwide
description: 'Configures if and how the project respects the "Do Not Track" (DNT) browser setting sent by visitors.
- `OFF`: DNT signals are ignored.
- `EU ONLY`: Respects DNT for visitors from EU countries.
- `EEA ONLY`: Respects DNT for visitors from European Economic Area countries.
- `Worldwide`: Respects DNT for all visitors globally.
If respected, the Convert script may not load or track for visitors with DNT enabled.
KB: "Respect Browser Do Not Track Setting".
'
global_privacy_control:
type: string
enum:
- 'OFF'
- EU ONLY
- EEA ONLY
- Worldwide
description: 'Configures if and how the project respects Global Privacy Control (GPC) signals sent by visitors'' browsers.
Options are similar to `do_not_track`. If respected, data collection and tracking may be limited.
KB: "Respect Browser Do Not Track Setting" - "Global Privacy Control (GPC)".
'
include_jquery:
type: boolean
description: '(For legacy tracking script) If true, Convert''s tracking script will include its own version of the jQuery library.
If your website already loads jQuery, set this to false to avoid loading it twice and improve page performance. Ensure your site''s jQuery loads before the Convert script.
KB: "Do not include jQuery into the tracking scripts".
'
include_jquery_v1:
type: boolean
default: false
description: '(For new v1 tracking script) If true, includes a jQuery-compatible API within the Convert script, even though the core script is jQuery-independent.
Set to true if your variation code or global JS relies on `convert.$()` syntax and your site doesn''t globally provide jQuery.
The new script itself does not require jQuery to function.
'
disable_spa_functionality:
type: boolean
default: false
description: 'If true, disables Convert''s built-in optimizations and automatic handling for Single Page Applications (SPAs).
Most SPAs work well with default SPA functionality enabled. Only disable if encountering specific conflicts or issues.
KB: "SPA Optimizations", "Running Experiments on Single Page Apps".
'
do_not_track_referral:
type: boolean
default: false
description: 'If true, Convert will not store referral data (like HTTP referrer or UTM parameters) in visitor cookies for use across subsequent pages or sessions.
Referral data will still be used for targeting on the initial page view where it''s present.
'
time_zone:
type: string
description: 'The primary timezone for this project (e.g., "America/New_York", "Europe/London", "UTC").
This timezone is used for scheduling experiences, interpreting time-based audience conditions (like ''hour of day - project_tz''), and displaying timestamps in reports.
'
utc_offset:
$ref: '#/components/schemas/UTC_Offset'
time_format:
type: string
description: Preferred time format for display within the Convert application UI for this project (12-hour or 24-hour).
enum:
- 12h
- 24h
debug_token:
$ref: '#/components/schemas/GenerateDebugTokenData'
disable_default_config:
type: boolean
default: false
description: '(For Full Stack projects) If true, disables the default public configuration endpoint for this project.
Access to project configuration via SDKs would then strictly require an authenticated SDK key. Enhances security for Full Stack projects.
'
include_experience_collaborators:
type: boolean
default: false
description: 'If true, experience details retrieved via API will include information about the experience owner and collaborators.
KB: "Assign Visible Owners and Collaborators to Experiences".
'
version:
type: string
maxLength: 50
nullable: true
readOnly: true
description: 'An internal version identifier for the project''s configuration.
This version string changes whenever a modification is made that affects the tracking script''s content (e.g., updating an experience, goal, or project setting).
Format: [ISO_datetime]-[incremental_number].
'
legacy_script:
type: boolean
default: false
description: 'If true, this project is configured to use Convert''s legacy tracking script.
If false, it uses the newer, more performant v1 tracking script.
New projects default to `false`. Existing projects retain their current script setting.
KB: "How to Install the Main Tag / Convert Tracking Code / JavaScript" - "The Tracking Script vs Legacy Tracking Script".
'
ignore_unused_locations:
type: boolean
default: false
description: 'If true, locations that are not currently associated with any active experiences will be excluded from the tracking script data downloaded by visitors.
This can help reduce snippet size and improve performance.
KB: "Benefits of Archiving Unused Goals, Locations, and Audiences." (Related concept for goals).
'
personalization:
type: object
nullable: true
description: Personalization settings.
properties:
enabled:
type: boolean
default: false
description: Indicates whether personalization is enabled for this project.
tracking_script:
type: object
description: 'Settings related to the management and versioning of the Convert tracking script for this project.
Allows choosing a release strategy (manual, latest, scheduled) and viewing available/applied script versions.
KB: "Tracking Script Version Management".
'
additionalProperties: false
nullable: true
properties:
# --- truncated at 32 KB (116 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/convert/refs/heads/main/openapi/convert-projects-api-openapi.yml