Convert Projects API

openapi: 3.1.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:
    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.
    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
    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'
    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
    LiveDataEventTypes:
      type: string
      enum:
      - view_experience
      - conversion
      - transaction
    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'
    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
    LiveDataEventsListResponseData:
      type: object
      description: Response containing a list of recent live tracking events for a project or account.
      properties:
        data:
          $ref: '#/components/schemas/LiveDataEventsList'
    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
    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
    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.
    ImportProjectDataSuccess:
      allOf:
      - $ref: '#/components/schemas/SuccessData'
      - type: object
        properties:
          imported:
            type: object
            description: List of imported objects
            properties:
              experiences:
                type: array
                description: List of created experiences. Empty if nothing imported
                items:
                  type: integer
              audiences:
                type: array
                description: List of created audiences. Empty if nothing imported
                items:
                  type: integer
              locations:
                type: array
                description: List of created locations. Empty if nothing imported
                items:
                  type: integer
              goals:
                type: array
                description: List of created goals. Empty if nothing imported
                items:
                  type: integer
              hypothesis:
                type: array
                description: List of created hypothesis. Empty if nothing imported
                items:
                  type: integer
    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
    ProjectsExportResponseFile:
      type: object
      description: Represents the structure of the JSON file exported for a project, containing all its configurations (experiences, goals, audiences, etc.).
    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
    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 

# --- 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