> ## Documentation Index
> Fetch the complete documentation index at: https://docs.naturalead.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create A/B Test

> Creates a new A/B test in draft status. The test must include at least
two variants, each referencing a valid agent configuration with a traffic
weight. Requires `ab_testing:manage` permission.




## OpenAPI

````yaml POST /api/ab-tests
openapi: 3.1.0
info:
  title: Naturalead A/B Testing API
  version: 1.0.0
  description: >
    API for managing A/B tests in the Naturalead platform. A/B tests allow you

    to compare multiple AI agent configurations by splitting lead traffic across

    variants with configurable weights. All endpoints require API key
    authentication

    and are scoped to the caller's account.
servers:
  - url: '{baseUrl}'
    description: API server
    variables:
      baseUrl:
        default: http://localhost:3001
security:
  - BearerAuth: []
tags:
  - name: A/B Testing
    description: A/B test CRUD, status management, and results
paths:
  /api/ab-tests:
    post:
      tags:
        - A/B Testing
      summary: Create A/B test
      description: >
        Creates a new A/B test in draft status. The test must include at least

        two variants, each referencing a valid agent configuration with a
        traffic

        weight. Requires `ab_testing:manage` permission.
      operationId: createAbTest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAbTestRequest'
      responses:
        '201':
          description: A/B test created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AbTest'
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CreateAbTestRequest:
      type: object
      description: Request body for creating a new A/B test.
      properties:
        name:
          type: string
          description: A/B test display name
        description:
          type: string
          description: Optional description of the test hypothesis
        variants:
          type: array
          items:
            $ref: '#/components/schemas/Variant'
          minItems: 2
          description: At least two agent configuration variants to compare
      required:
        - name
        - variants
    AbTest:
      type: object
      description: An A/B test comparing multiple agent configurations.
      properties:
        _id:
          type: string
          description: Unique A/B test identifier
        accountId:
          type: string
          description: Account that owns this A/B test
        name:
          type: string
          description: A/B test display name
        description:
          type: string
          description: Optional description of the test hypothesis
        status:
          type: string
          enum:
            - draft
            - running
            - paused
            - completed
          description: Current test lifecycle status
        variants:
          type: array
          items:
            $ref: '#/components/schemas/Variant'
          minItems: 2
          description: Agent configuration variants being compared
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - _id
        - accountId
        - name
        - status
        - variants
        - createdAt
        - updatedAt
    Variant:
      type: object
      description: A single variant in an A/B test, referencing an agent configuration.
      properties:
        agentConfigId:
          type: string
          description: Reference to the agent configuration for this variant
        weight:
          type: number
          description: Traffic weight for this variant (e.g., 50 for 50%)
          minimum: 1
          maximum: 100
      required:
        - agentConfigId
        - weight
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
  responses:
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: At least two variants are required
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Failed to process request
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Bearer token using an API key (format: nl_live_* or nl_test_*).

````