Convert Knowledge Bases API
The Knowledge Bases API from Convert — 7 operation(s) for knowledge bases.
OpenAPI Specification
openapi: 3.1.0
info:
title: Convert Accounts Knowledge Bases 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: Knowledge Bases
paths:
/accounts/{account_id}/projects/{project_id}/knowledge-bases:
post:
operationId: getKnowledgeBasesList
summary: List Knowledge Base entries within a project
description: 'Retrieves a list of all Knowledge Base entries for a specific project.
The Knowledge Base stores proven or disproven hypotheses and their outcomes, serving as a repository of experimental learnings.
Supports filtering by status, name, and pagination.
The Knowledge Base article "Observations Feature Guide" explains: "Knowledge Base - Convert proven hypotheses to serve as a historical record and knowledge resource."
'
tags:
- Knowledge Bases
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
description: ID of the project to which save/retrieved data is connected
in: path
required: true
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/GetKnowledgeBasesRequest'
responses:
'200':
$ref: '#/components/responses/KnowledgeBasesListResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/knowledge-bases/{knowledge_base_id}:
get:
operationId: getKnowledgeBase
summary: Get details for a specific Knowledge Base entry
description: 'Retrieves detailed information about a single Knowledge Base entry, identified by its `knowledge_base_id`.
This includes the original hypothesis name, summary of findings, status, and associated tags.
'
tags:
- Knowledge Bases
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 into which the knowledge base is stored
schema:
type: integer
- name: knowledge_base_id
in: path
required: true
description: ID of the knowledge base to be retrieve
schema:
type: integer
- name: expand
in: query
description: 'Specifies the list of fields 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/KnowledgeBasesExpandFields'
responses:
'200':
$ref: '#/components/responses/KnowledgeBaseResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/knowledge-bases/add:
post:
operationId: createKnowledgeBase
summary: Create a new Knowledge Base entry
description: 'Adds a new entry to the Knowledge Base. This is typically done by converting a ''proven'' or ''disproven'' hypothesis,
but can also be used to manually add other experimental learnings.
Requires a name, summary, and status.
'
tags:
- Knowledge Bases
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 into which the knowledge base is to be stored
schema:
type: integer
- name: expand
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)
'
in: query
required: false
schema:
type: array
items:
$ref: '#/components/schemas/KnowledgeBasesExpandFields'
requestBody:
$ref: '#/components/requestBodies/CreateKnowledgeBasesRequest'
responses:
'201':
$ref: '#/components/responses/KnowledgeBaseResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/knowledge-bases/{knowledge_base_id}/update-status:
post:
operationId: updateKnowledgeBase
summary: Update the status of a Knowledge Base entry
description: 'Changes the status of an existing Knowledge Base entry (e.g., from ''active'' to ''archived'').
'
tags:
- Knowledge Bases
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 into which the knowledge base is to be updated
schema:
type: integer
- name: knowledge_base_id
in: path
required: true
description: ID of the knowledge base to be updated
schema:
type: integer
- name: expand
in: query
description: 'Specifies the list of fields 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/KnowledgeBasesExpandFields'
requestBody:
$ref: '#/components/requestBodies/UpdateKnowledgeBasesStatusRequest'
responses:
'200':
$ref: '#/components/responses/KnowledgeBaseResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/knowledge-bases/{knowledge_base_id}/delete:
delete:
operationId: deleteKnowledgeBase
summary: Delete a Knowledge Base entry
description: 'Permanently removes a Knowledge Base entry from a project. This action is irreversible.
'
tags:
- Knowledge Bases
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 from which the knowledge base is to be deleted
schema:
type: integer
- name: knowledge_base_id
in: path
required: true
description: ID of the knowledge base to be deleted
schema:
type: integer
responses:
'200':
$ref: '#/components/responses/KnowledgeBaseResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/knowledge-bases/bulk-update:
post:
operationId: bulkKnowledgeBasesUpdate
summary: Update multiple Knowledge Base entries at once
description: 'Allows for changing the status (e.g., active, archived) of multiple Knowledge Base entries within a project simultaneously.
Requires a list of Knowledge Base entry IDs and the target status.
'
tags:
- Knowledge Bases
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
description: ID of the project to which save/retrieved data is connected
in: path
required: true
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/BulkUpdateKnowledgeBasesRequest'
responses:
'200':
$ref: '#/components/responses/BulkSuccessResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/knowledge-bases/bulk-delete:
post:
operationId: bulkKnowledgeBasesDelete
summary: Delete multiple Knowledge Base entries at once
description: 'Permanently removes multiple Knowledge Base entries from a project in a single operation.
Requires a list of Knowledge Base entry IDs. This action is irreversible.
'
tags:
- Knowledge Bases
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
description: ID of the project to which save/retrieved data is connected
in: path
required: true
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/BulkDeleteKnowledgeBasesRequest'
responses:
'200':
$ref: '#/components/responses/BulkSuccessResponse'
default:
$ref: '#/components/responses/ErrorResponse'
components:
schemas:
TrackingScriptReleaseScheduled:
allOf:
- $ref: '#/components/schemas/TrackingScriptReleaseBase'
- type: object
additionalProperties: false
properties:
type:
enum:
- scheduled
automatic_apply_on:
$ref: '#/components/schemas/TrackingScriptReleaseAutomaticApplyOn'
GA_SettingsBase:
type: object
properties:
enabled:
type: boolean
description: If true, integration with Google Analytics is enabled for this project or experience, allowing experiment data to be sent to GA.
CustomDomainOwnershipVerificationItem:
type: object
properties:
name:
type: string
description: The name of the DNS record.
type:
$ref: '#/components/schemas/DNSRecordTypes'
value:
type: string
description: The value of the DNS record.
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
SimpleGoal:
type: object
properties:
id:
description: The unique numerical identifier of the goal.
type: integer
name:
description: The user-defined, friendly name of the goal.
type: string
SimpleLocationExpandable:
anyOf:
- type: integer
description: Location ID
- $ref: '#/components/schemas/SimpleLocation'
KnowledgeBasesExpandFields:
type: string
enum:
- project
- tags
SE_ProcSettings:
description: Overall settings for the statistical engine processing results for this experience.
oneOf:
- $ref: '#/components/schemas/SE_ProcSettingsFrequentist'
- $ref: '#/components/schemas/SE_ProcSettingsBayesian'
discriminator:
propertyName: stats_type
mapping:
frequentist: '#/components/schemas/SE_ProcSettingsFrequentist'
bayesian: '#/components/schemas/SE_ProcSettingsBayesian'
BaseExperienceExpandable:
description: Represents an experience, either as its unique ID or as a simple object with its ID and name. Used when an experience is referenced by another entity and can be optionally expanded.
oneOf:
- $ref: '#/components/schemas/ExperienceId'
- $ref: '#/components/schemas/BaseSimpleExperience'
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
NumericOutlierMinMax:
allOf:
- $ref: '#/components/schemas/NumericOutlierBase'
- type: object
additionalProperties: false
properties:
detection_type:
enum:
- min_max
min:
type: number
description: Minimum value for the outlier detection, under which, the value is considered an outlier
max:
type: number
description: Maximum value for the outlier detection, over which, the value is considered an outlier
TagExpandableRequest:
description: 'Represents a tag when associating it with another entity (like an experience or goal) during a create or update operation.
Can be either the existing `integer` ID of the tag, or a `TagToCreate` object if a new tag should be created and associated on the fly.
'
anyOf:
- type: integer
description: Tag ID
- $ref: '#/components/schemas/TagToCreate'
NumericOutlierNone:
allOf:
- $ref: '#/components/schemas/NumericOutlierBase'
- type: object
additionalProperties: false
properties:
detection_type:
enum:
- none
SimpleGoalExpandable:
oneOf:
- type: integer
description: Goal ID
- $ref: '#/components/schemas/SimpleGoal'
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.
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
ProjectStatuses:
description: 'The overall status of a project:
- `active`: The project is active, and experiences within it can run and track data.
- `inactive`: The project is inactive (archived or paused). No experiences within it will run, and no new data will be tracked.
- `suspended`: The project (or account) has been suspended, typically due to billing issues or terms of service violations. Services are disabled.
'
type: string
enum:
- active
- inactive
- suspended
TagExpandable:
description: Represents a tag, either as its unique ID or as the full tag object (ID, name, description) if expanded.
oneOf:
- type: integer
description: Tag ID
- $ref: '#/components/schemas/Tag'
GA_Settings:
oneOf:
- $ref: '#/components/schemas/ProjectIntegrationGA3'
- $ref: '#/components/schemas/ProjectIntegrationGA4'
discriminator:
propertyName: type
mapping:
ga3: '#/components/schemas/ProjectIntegrationGA3'
ga4: '#/components/schemas/ProjectIntegrationGA4'
AccessRoleNames:
type: string
description: 'The predefined names for user access roles within the Convert system. Each role grants a specific set of permissions.
- `owner`: Highest level, full control over account, billing, users, and all projects. Typically the account creator.
- `account_manager`: Broad administrative rights over the account, often including billing and user management, but might not be able to delete the account itself.
- `admin`: Full control over projects they are assigned to, including creating/editing/deleting experiences, goals, audiences, and managing project settings. May also manage project-level collaborators.
- `browse`: Read-only access. Can view experiences, reports, and settings but cannot make changes.
- `edit`: Can create and modify entities like experiences, goals, audiences within assigned projects, but typically cannot activate/publish experiences or manage project settings.
- `publish`: Can do everything an ''editor'' can, plus activate/pause/complete experiences.
- `review`: Can view and comment, but not make direct changes. Suited for stakeholders who need to approve or provide feedback.
Knowledge Base: "Collaborators - Share With Multiple Users / Accounts" (describes access levels).
'
enum:
- owner
- account_manager
- admin
- browse
- edit
- publish
- review
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 th
# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/convert/refs/heads/main/openapi/convert-knowledge-bases-api-openapi.yml