Convert Domains API

openapi: 3.1.0
info:
  title: Convert Accounts Domains 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: Domains
  description: Domains define websites which will be used in experiences in your projects.
paths:
  /accounts/{account_id}/projects/{project_id}/domains:
    post:
      operationId: getDomainsList
      summary: List domains associated with a project
      description: 'Retrieves a list of all website domains configured for a specific project.

        The Convert tracking script will operate on these domains to run experiences and track visitors.

        Wildcard domains (e.g., `*.example.com`) are supported.

        As per the Knowledge Base: "Active Websites: The domains you would like to use inside the project. Make sure you always add new domains here..."

        '
      tags:
      - Domains
      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 which save/retrieved data is connected
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/GetDomainsListRequest'
      responses:
        '200':
          $ref: '#/components/responses/DomainsListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/domains/{domain_id}:
    get:
      operationId: getDomain
      summary: Get details for a specific domain in a project
      description: 'Retrieves information about a single domain associated with a project, identified by its `domain_id`.

        This includes the domain URL and whether the Convert tracking code was detected on it.

        '
      tags:
      - Domains
      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 domain is stored
        schema:
          type: integer
      - name: domain_id
        in: path
        required: true
        description: ID of the domain to be retrieved
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/DomainResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/domains/by_url:
    post:
      operationId: getDomainByUrl
      summary: Get domain details by its URL
      description: 'Retrieves information about a domain by matching its URL (exact or wildcard) instead of its ID.

        Useful if you know the domain URL but not its internal Convert ID.

        '
      tags:
      - Domains
      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 domain is stored
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/GetDomainByUrlRequest'
      responses:
        '200':
          $ref: '#/components/responses/DomainResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/domains/{domain_id}/check_code:
    post:
      operationId: checkCodeDomain
      summary: Verify Convert tracking code installation on a domain
      description: 'Checks if the Convert tracking script for the specified project is correctly installed and detectable on the given URL (which must belong to the domain identified by `domain_id`).

        Updates the `code_installed` status of the domain object.

        The Knowledge Base article "Tracking Script Installation Verification" describes this UI feature.

        '
      tags:
      - Domains
      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 domain is stored
        schema:
          type: integer
      - name: domain_id
        in: path
        required: true
        description: ID of the domain to which the given URL belongs. An error would be returned if the URL is not under this domain.
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/CheckCodeDomainRequest'
      responses:
        '200':
          $ref: '#/components/responses/DomainResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/domains/add:
    post:
      operationId: createDomain
      summary: Add a new domain to a project
      description: 'Associates a new website domain (e.g., `https://www.example.com`) with the specified project.

        The Convert tracking script for this project should then be installed on this domain to enable experiments.

        Wildcards like `https://*.example.com` can be used to include all subdomains.

        '
      tags:
      - Domains
      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 domain is to be stored
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/CreateDomainRequest'
      responses:
        '201':
          $ref: '#/components/responses/DomainResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/domains/{domain_id}/update:
    post:
      operationId: updateDomain
      summary: Update an existing domain in a project
      description: 'Modifies the URL of an existing domain associated with a project.

        '
      tags:
      - Domains
      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 domain is to be stored
        schema:
          type: integer
      - name: domain_id
        in: path
        required: true
        description: ID of the domain to be updated
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/UpdateDomainRequestData'
      responses:
        '200':
          $ref: '#/components/responses/DomainResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/domains/{domain_id}/delete:
    delete:
      operationId: deleteDomain
      summary: Remove a domain from a project
      description: 'De-associates a domain from the specified project.

        After deletion, Convert experiences will no longer run on this domain for this project.

        '
      tags:
      - Domains
      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 domain is to be stored
        schema:
          type: integer
      - name: domain_id
        in: path
        required: true
        description: ID of the domain to be delete
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/domains/bulk-delete:
    post:
      operationId: bulkDomainsDelete
      summary: Remove multiple domains from a project
      description: 'De-associates multiple domains from the specified project in a single operation.

        Requires a list of domain IDs to be removed.

        '
      tags:
      - Domains
      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/BulkDeleteDomainsRequest'
      responses:
        '200':
          $ref: '#/components/responses/BulkSuccessResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    DomainsList:
      type: array
      description: List of domains
      items:
        $ref: '#/components/schemas/Domain'
    GetDomainsListRequestData:
      allOf:
      - $ref: '#/components/schemas/OnlyCount'
      - $ref: '#/components/schemas/DomainsListDataOptions'
      - $ref: '#/components/schemas/PageNumber'
      - type: object
        properties:
          only:
            description: 'Only retrieve domains with the given ids.

              '
            type: array
            nullable: true
            items:
              type: integer
            maxItems: 100
          except:
            description: 'Except domains with the given ids.

              '
            type: array
            items:
              type: integer
            maxItems: 100
    BulkDeleteDomainRequestData:
      type: object
      description: Bulk Delete provided domains
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/BulkDomainsIds'
      required:
      - id
    Extra:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
    BulkSuccessData:
      allOf:
      - $ref: '#/components/schemas/SuccessData'
      - type: object
        properties:
          code:
            type: integer
            format: int32
          errors:
            type: array
            description: List of unprocessed entities. Would be empty, if all passed entities processed
            items:
              $ref: '#/components/schemas/BulkEntityError'
    CheckCodeDomainRequestData:
      type: object
      description: Check if tracking code is installed on the given URL;
      properties:
        url:
          type: string
          maxLength: 255
          description: 'URL on which to check the tracking code installed.

            The given URL needs to be under the domain passes as parameter or otherwise an error would be returned.

            '
    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
    PageNumber:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
          description: 'The page number for paginated results. For example, if `results_per_page` is 30, `page: 2` will retrieve items 31-60.

            Defaults to 1 if not specified.

            '
    BulkEntityError:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
          description: The unique identifier of the entity that could not be processed.
        message:
          type: string
          description: A message explaining the reason for the failure for this specific entity.
    Domain:
      type: object
      description: A website domain data.
      properties:
        id:
          type: integer
          description: Domain ID.
          readOnly: true
        url:
          type: string
          maxLength: 150
          pattern: ^(http|https)://
          description: Domain's homepage url
        code_installed:
          type: boolean
          description: Indicating whether code installed check passed sometimes in the past.
          default: false
    CreateDomainRequestData:
      allOf:
      - $ref: '#/components/schemas/DomainToCreate'
    GetDomainByUrlRequestData:
      type: object
      description: Get domain by URL request data
      properties:
        url:
          type: string
          maxLength: 255
          description: URL by which to search the domain. The match can be an exact one or an wildcard one.
    DomainsListResponseData:
      type: object
      description: Response containing a list of domains and extra domains list metadata
      properties:
        data:
          $ref: '#/components/schemas/DomainsList'
        extra:
          $ref: '#/components/schemas/Extra'
    DomainsListDataOptions:
      type: object
      description: Filter domains list.
      allOf:
      - $ref: '#/components/schemas/ResultsPerPage'
    DomainToCreate:
      required:
      - url
      allOf:
      - $ref: '#/components/schemas/Domain'
    BulkDomainsIds:
      type: array
      description: The list of domains id to delete
      items:
        type: integer
      minItems: 1
      maxItems: 100
    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
    UpdateDomainRequestData:
      allOf:
      - $ref: '#/components/schemas/Domain'
    OnlyCount:
      type: object
      properties:
        onlyCount:
          type: boolean
          description: 'If set to `true` in a list request, the response will only contain the total count of matching items (`extra.pagination.items_count`)

            and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

            '
    ResultsPerPage:
      type: object
      properties:
        results_per_page:
          type: integer
          nullable: true
          minimum: 0
          maximum: 50
          default: 30
          description: 'Specifies the maximum number of items to return in a single page of results.

            Used for pagination. Default is 30, maximum is 50.

            '
    SuccessData:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
  responses:
    SuccessResponse:
      description: 'A generic success response, typically used for operations that don''t return specific data (like deletions or some updates). The `code` is usually 200, and `message` confirms the successful action.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessData'
    ErrorResponse:
      description: 'Indicates an error occurred while processing the request. The `code` provides an HTTP status code, `message` offers a human-readable explanation or an array of validation errors, and `fields` (if present) specifies which input fields were problematic.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorData'
    BulkSuccessResponse:
      description: 'Indicates the outcome of a bulk operation (e.g., bulk update or delete). Provides a general success `message` and an `errors` array listing any entities that could not be processed, along with the reason for failure for each.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BulkSuccessData'
    DomainsListResponse:
      description: A list of website domains associated with a project. Each entry includes the domain `id`, `url`, and a flag `code_installed` indicating if the Convert tracking script was detected.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DomainsListResponseData'
    DomainResponse:
      description: Details for a single domain associated with a project, including its `id`, `url`, and `code_installed` status.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Domain'
  requestBodies:
    CheckCodeDomainRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CheckCodeDomainRequestData'
      description: Contains the specific `url` (which must fall under the path-parameter `domain_id`) on which to check for the presence and correct installation of the Convert tracking script.
    UpdateDomainRequestData:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateDomainRequestData'
      required: true
    GetDomainByUrlRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetDomainByUrlRequestData'
      description: Contains the `url` (which can be an exact match or include wildcards like `*.example.com`) to search for among the project's associated domains.
    CreateDomainRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateDomainRequestData'
      required: true
    GetDomainsListRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetDomainsListRequestData'
      description: Optional filters for listing domains within a project, primarily pagination parameters (`page`, `results_per_page`).
    BulkDeleteDomainsRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BulkDeleteDomainRequestData'
  securitySchemes:
    requestSigning:
      type: apiKey
      x-name-applicationId: Convert-Application-ID
      x-name-expire: Expire
      name: Authorization
      in: header
      description: 'See **[API Key Authentication](#tag/API-KEY-Authentication)** for more information.

        '
    secretKey:
      type: http
      scheme: bearer
      description: 'See **[API Key Authentication](#tag/API-KEY-Authentication)** for more information.

        '
    cookieAuthentication:
      type: apiKey
      in: cookie
      name: sid
      description: Cookie authentication is used against Convert's own IdentityProvider  or third party identity providers and is described more in the "[Cookie Authentication](#tag/Cookie-Authentication)" section
x-tagGroups:
- name: Client Authentication
  tags:
  - API KEY Authentication
  - Cookie Authentication
  - OAuth Authorization
- name: Common Parameters
  tags:
  - Optional Fields
  - Expandable Fields
- name: Requests
  tags:
  - User
  - Accounts
  - AI content
  - Collaborators
  - API Keys
  - Projects
  - SDK Keys
  - Experiences
  - Experience Variations
  - Experience Sections
  - Section Versions
  - Version Changes
  - Experiences Reports
  - Experiences Heatmaps
  - Goals
  - Hypotheses
  - Knowledge Bases
  - Observations
  - Locations
  - Audiences
  - Domains
  - Cdn Images
  - Files
  - Tags
  - Features
  - Visitor Insights
  - Visitors Data
  - Visitor Data Placeholders
  - OAuth