Convert Features API

openapi: 3.1.0
info:
  title: Convert Accounts Features 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: Features
  description: Features can be created only under **Fullstack** Projects
paths:
  /accounts/{account_id}/projects/{project_id}/features:
    post:
      operationId: getFeaturesList
      summary: List features within a Full Stack project
      description: 'Retrieves a list of all features defined for a specific Full Stack project.

        Features are used for feature flagging and server-side experimentation, allowing control over functionality and variables.

        Supports filtering by name, key, status, and pagination.

        The Knowledge Base article "Full Stack Experiments on Convert" provides context.

        '
      tags:
      - Features
      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/GetFeaturesListRequest'
      responses:
        '200':
          $ref: '#/components/responses/FeaturesListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/features/{feature_id}:
    get:
      operationId: getFeature
      summary: Get details for a specific feature
      description: 'Retrieves detailed information about a single feature within a Full Stack project, identified by its `feature_id`.

        This includes its name, key, status, description, and defined variables (with their types and default values).

        '
      tags:
      - Features
      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
      - name: feature_id
        in: path
        required: true
        description: ID of the feature to be retrieved
        schema:
          type: integer
      - name: include
        description: 'Specifies the list of optional fields which would be included in the response.


          Otherwise, the fields that can be passed through this parameter would not be included in the response.


          Read more in the section related to [Optional Fields](#tag/Optional-Fields)

          '
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/FeatureOptionalFields'
      responses:
        '200':
          $ref: '#/components/responses/FeatureResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/features/{feature_key}:
    get:
      operationId: getFeatureByKey
      summary: Get feature details by its unique key
      description: 'Retrieves detailed information about a single feature, identified by its user-defined `feature_key`.

        Useful if you have a human-readable key for a feature. Otherwise, similar to getting a feature by ID.

        '
      tags:
      - Features
      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
      - name: feature_key
        in: path
        required: true
        description: Key of the feature to be retrieved
        schema:
          type: string
      - name: include
        description: 'Specifies the list of optional fields which would be included in the response.


          Otherwise, the fields that can be passed through this parameter would not be included in the response.


          Read more in the section related to [Optional Fields](#tag/Optional-Fields)

          '
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/FeatureOptionalFields'
      responses:
        '200':
          $ref: '#/components/responses/FeatureResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/features/add:
    post:
      operationId: createFeature
      summary: Create a new feature for a Full Stack project
      description: 'Defines a new feature within a Full Stack project.

        Requires a name, a unique key, and a list of variables associated with the feature.

        Each variable has a key, type (string, boolean, integer, float, json), and a default value.

        Features are used in Full Stack experiments to control different code paths or configurations.

        '
      tags:
      - Features
      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 feature is to be stored
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/CreateFeatureRequest'
      responses:
        '201':
          $ref: '#/components/responses/FeatureResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/features/{feature_id}/update:
    post:
      operationId: updateFeature
      summary: Update an existing feature
      description: 'Modifies the configuration of an existing feature in a Full Stack project.

        This can include changing its name, description, status (active/archived), or its associated variables (adding, removing, or modifying variables and their default values).

        '
      tags:
      - Features
      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
      - name: feature_id
        in: path
        required: true
        description: ID of the feature to be updated
        schema:
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/UpdateFeatureRequest'
      responses:
        '200':
          $ref: '#/components/responses/FeatureResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/features/{feature_id}/delete:
    delete:
      operationId: deleteFeature
      summary: Delete a feature
      description: 'Permanently removes a feature from a Full Stack project. This action is irreversible.

        If the feature is in use by active experiments, consider its impact before deletion.

        '
      tags:
      - Features
      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
      - name: feature_id
        in: path
        required: true
        description: ID of the feature to be deleted
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/features/bulk-update:
    post:
      operationId: bulkFeaturesUpdate
      summary: Update multiple features at once
      description: 'Allows for changing the status (e.g., active, archived) of multiple features within a Full Stack project simultaneously.

        Requires a list of feature IDs and the target status.

        '
      tags:
      - Features
      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/BulkUpdateFeaturesRequest'
      responses:
        '200':
          $ref: '#/components/responses/BulkSuccessResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/features/bulk-delete:
    post:
      operationId: bulkFeaturesDelete
      summary: Delete multiple features at once
      description: 'Permanently removes multiple features from a Full Stack project in a single operation.

        Requires a list of feature IDs. This action is irreversible.

        '
      tags:
      - Features
      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/BulkDeleteFeaturesRequest'
      responses:
        '200':
          $ref: '#/components/responses/BulkSuccessResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  responses:
    FeatureResponse:
      description: Detailed information for a single feature in a Full Stack project, including its name, key, status, description, and an array of its `variables` (each with a key, type, and default value).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Feature'
    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'
    FeaturesListResponse:
      description: A list of features defined within a Full Stack project. Each feature entry includes its ID, name, key, status, and potentially usage statistics if requested.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FeaturesListResponseData'
    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'
  schemas:
    FeaturesList:
      type: array
      description: A list of feature objects.
      items:
        $ref: '#/components/schemas/Feature'
    FeatureVariableBase:
      type: object
      description: Base properties for a variable within a feature. Each variable has a key, a type, and a default value.
      properties:
        key:
          type: string
          description: 'A unique, machine-readable string key for this variable within the feature (e.g., "buttonColor", "discountPercentage", "showHeader").

            This key is used by SDKs to retrieve the variable''s value for the active variation.

            '
          maxLength: 32
        type:
          type: string
          description: 'The data type of the variable. This determines the kind of values it can hold and how it''s treated by the SDKs.

            - `json`: A JSON object or array.

            - `string`: A text string.

            - `boolean`: A true/false value.

            - `float`: A floating-point number.

            - `integer`: A whole number.

            '
        default_value:
          description: 'The default value for this variable. This value is used if the feature is not part of an active experiment for a user, or if no specific value is set for the variation a user is bucketed into.

            The type of `default_value` must match the specified `type` of the variable.

            '
          nullable: true
      required:
      - key
      - type
    Extra:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
    FeatureVariableNumeric:
      allOf:
      - $ref: '#/components/schemas/FeatureVariableBase'
      - type: object
        properties:
          type:
            enum:
            - float
            - integer
          default_value:
            type: number
            nullable: true
    GetFeaturesListRequestData:
      allOf:
      - $ref: '#/components/schemas/OnlyCount'
      - $ref: '#/components/schemas/FeaturesListFilteringOptions'
      - $ref: '#/components/schemas/PageNumber'
      - type: object
        properties:
          include:
            description: Specifies the list of fields to be included in the response, which otherwise would not be sent.
            type: array
            items:
              $ref: '#/components/schemas/FeatureOptionalFields'
    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'
    Feature:
      type: object
      description: 'Represents a feature flag or a set of configurable variables within a Full Stack project.

        Features are used in ''a/b_fullstack'' or ''feature_rollout'' experiences to control application behavior or content dynamically, often from the server-side or within client-side applications using an SDK.

        Each feature has a unique `key` for programmatic access and a list of `variables` whose values can be altered per experience variation.

        Knowledge Base: "Full Stack Experiments on Convert".

        '
      properties:
        id:
          description: The unique numerical identifier for the feature.
          type: integer
          readOnly: true
        name:
          description: A user-defined, friendly name for the feature (e.g., "New Checkout Process", "Beta User Dashboard"). This name appears in the Convert UI.
          type: string
          maxLength: 100
        status:
          $ref: '#/components/schemas/FeatureStatuses'
        key:
          description: 'A unique, machine-readable string key for this feature (e.g., "new_checkout_flow", "beta_dashboard_enabled").

            This key is used by the SDKs to identify and retrieve the feature''s configuration and variable values.

            It''s typically auto-generated from the name if not specified, but can be user-defined.

            '
          type: string
          maxLength: 32
        stats:
          $ref: '#/components/schemas/FeatureStats'
        description:
          description: An optional, more detailed explanation of the feature's purpose, what it controls, or its intended use cases.
          type: string
          maxLength: 200
        variables:
          type: array
          description: 'An array of `FeatureVariable` objects that define the configurable parameters associated with this feature.

            For example, a feature "Button Customization" might have variables like "buttonColor" (string), "buttonText" (string), and "isEnabled" (boolean).

            The values of these variables can be different for each variation of an experience that uses this feature.

            '
          items:
            $ref: '#/components/schemas/FeatureVariable'
    BulkFeaturesIds:
      type: array
      description: A list of feature unique numerical identifiers to be affected by a bulk operation.
      items:
        type: integer
      minItems: 1
      maxItems: 100
    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.

            '
    FeatureVariable:
      oneOf:
      - $ref: '#/components/schemas/FeatureVariableString'
      - $ref: '#/components/schemas/FeatureVariableBool'
      - $ref: '#/components/schemas/FeatureVariableNumeric'
      discriminator:
        propertyName: type
        mapping:
          boolean: '#/components/schemas/FeatureVariableBool'
          float: '#/components/schemas/FeatureVariableNumeric'
          json: '#/components/schemas/FeatureVariableString'
          integer: '#/components/schemas/FeatureVariableNumeric'
          string: '#/components/schemas/FeatureVariableString'
    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.
    FeatureVariableBool:
      allOf:
      - $ref: '#/components/schemas/FeatureVariableBase'
      - type: object
        properties:
          type:
            enum:
            - boolean
          default_value:
            type: boolean
            nullable: true
    UpdateFeatureRequestData:
      allOf:
      - type: object
        properties:
          id:
            description: Feature ID
            type: integer
      - $ref: '#/components/schemas/Feature'
    FeatureStatuses:
      type: string
      description: 'The current status of a feature:

        - `active`: The feature is active and can be used in Full Stack experiments. Its variables can be controlled by experiences.

        - `archived`: The feature is archived and no longer available for new experiments. Existing experiments using it might behave based on last known configuration or default values.

        '
      enum:
      - active
      - archived
      default: active
    CreateFeatureRequestData:
      allOf:
      - $ref: '#/components/schemas/Feature'
      required:
      - name
      - variables
    FeatureVariableString:
      allOf:
      - $ref: '#/components/schemas/FeatureVariableBase'
      - type: object
        properties:
          type:
            enum:
            - json
            - string
          default_value:
            type: string
            nullable: true
    SortDirection:
      type: object
      properties:
        sort_direction:
          type: string
          nullable: true
          default: desc
          description: 'The direction for sorting the list results, based on the `sort_by` field.

            - `asc`: Ascending order (e.g., A-Z, 1-10, oldest to newest).

            - `desc`: Descending order (e.g., Z-A, 10-1, newest to oldest).

            Defaults to `desc` (newest/highest first) if not specified.

            '
          enum:
          - asc
          - desc
    FeatureOptionalFields:
      type: string
      enum:
      - stats
    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
    BulkUpdateFeatureRequestData:
      type: object
      description: Request body for bulk updating the status of multiple features.
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/BulkFeaturesIds'
        status:
          $ref: '#/components/schemas/FeatureStatuses'
      required:
      - id
      - status
    FeatureStats:
      type: object
      readOnly: true
      properties:
        times_used:
          type: integer
          description: The number of currently active experiences (e.g., 'a/b_fullstack', 'feature_rollout') that are using this feature to control variations.
    FeaturesListResponseData:
      type: object
      description: Response containing a list of features defined within a Full Stack project, along with pagination details if applicable.
      properties:
        data:
          $ref: '#/components/schemas/FeaturesList'
        extra:
          $ref: '#/components/schemas/Extra'
    BulkDeleteFeatureRequestData:
      type: object
      description: Request body for bulk deleting multiple features. Contains a list of feature IDs to be permanently removed.
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/BulkFeaturesIds'
      required:
      - id
    FeaturesListFilteringOptions:
      allOf:
      - $ref: '#/components/schemas/ResultsPerPage'
      - $ref: '#/components/schemas/SortDirection'
      - type: object
        properties:
          search:
            type: string
            maxLength: 100
            description: A search string that would be used to search against Feature's id, name, key and description
            nullable: true
          only:
            description: 'Only retrieve features with the given ids.

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

              '
            type: array
            items:
              type: integer
            maxItems: 100
          sort_by:
            type: string
            description: 'A value to sort features by specific field


              Defaults to **id** if not provided

              '
            enum:
            - id
            - name
            - key
            - status
            nullable: true
            default: id
    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
  requestBodies:
    BulkUpdateFeaturesRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BulkUpdateFeatureRequestData'
      description: Contains a list of feature `id`s and the target `status` (e.g., 'active', 'archived') to apply to all of them.
      required: true
    UpdateFeatureRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateFeatureRequestData'
      required: true
    CreateFeatureRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateFeatureRequestData'
      required: true
    BulkDeleteFeaturesRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BulkDeleteFeatureRequestData'
    GetFeaturesListRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetFeaturesListRequestData'
  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