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

# Create an experiment.



## OpenAPI

````yaml /openapi/adm.openapi.en-dev.json post /api/manager/experiments
openapi: 3.1.0
info:
  description: >
    ## Introduction

    The Data Management APIs comprehensively oversees the **diverse data** used
    by advertising and recommendation systems, ensuring that the Decision API
    runs accurately and efficiently.


    From registering, updating, and deleting campaigns and placements to **log
    and statistics analysis**, it provides the insights necessary for effective
    system operation.


    The resulting data and metrics are used by the Decision API to **optimize ad
    and content decisions**, ultimately boosting the overall performance of the
    advertising and recommendation system.
  title: Data Management APIs
  version: dev
servers: []
security: []
tags:
  - description: >-
      Authentication endpoints. All roles (admin, operator, advertiser) use
      these to log in, refresh tokens, and manage their own credentials.
    name: Auth
  - description: >-
      Advertiser account management. Operators and admins onboard advertisers,
      manage their budgets, and deactivate accounts. Advertisers can only read
      their own profile and balance — they cannot create, delete, or modify
      another advertiser's account.
    name: Advertisers
  - description: >-
      Internal user (operator / admin) account management. Admin only. Covers
      creating operator accounts, changing roles, toggling activation status,
      and hard-deleting accounts. Operators have no access to this resource.
    name: Users
  - description: >-
      The AdUnit Management API provides comprehensive functionalities for
      managing ad units and related resources. AdUnits are organized in a
      hierarchical path structure derived from their code and parent path. Only
      admin and operator roles have access — advertisers cannot access raw
      inventory. References:
      [Placement](https://docs.aiderx.io/guides/about-a2/en/placement)
    name: AdUnit
  - description: >-
      Ad catalog management. CRUD for ad catalogs plus public shared-view access
      via a share link.
    name: Ad Catalogs
  - description: >-
      Ad source (demand partner) management. CRUD for external ad sources that
      supply demand to ad units.
    name: AdSource
  - description: >-
      Allocation management. An allocation binds a line item to a serving target
      such as an ad unit. Covers CRUD, status counts, and single-allocation
      lookup.
    name: Allocations
  - description: >-
      Associated items pool (admin). Bulk upsert/delete and lookup of
      associated-items pools used by the recommendation pipeline.
    name: AssociatedItemsPool
  - description: >-
      Custom targeting segment management. CRUD and bulk operations for custom
      targeting segments.
    name: Custom Targeting Segment
  - description: Audit log access. Read the system audit log of administrative actions.
    name: Audit Logs
  - description: >-
      Creative block list. List, block, and unblock creatives to exclude them
      from serving.
    name: Blocked Creative
  - description: Catalog item management. List and update catalog (product/data) items.
    name: Catalogs
  - description: >-
      Creative asset management. Operators and admins manage creatives;
      advertisers see only their own. Deletion is blocked while any line-item
      association (LICA) still exists.
    name: Creatives
  - description: >-
      Dashboard aggregates. Summary data, inventory, and line-item metric
      rollups for the console dashboard.
    name: Dashboard
  - description: Experiment management. CRUD for A/B and optimization experiments.
    name: Experiment
  - description: >-
      External creative inspection. Read-only access to creatives ingested from
      external demand sources.
    name: External Creative
  - description: >-
      Third-party integration management. Manage integration sources (external
      data/serving connectors), probe connectivity, and read public
      (sensitive-config-redacted) configs.
    name: Integration
  - description: >-
      Line Item–Creative Associations (LICA). Associates creatives with line
      items, including batch create and delete (max 100, partial failure
      allowed) and dashboard counts.
    name: LICAs
  - description: License information. Read available license features and usage metrics.
    name: License
  - description: >-
      Line item management within an order. Covers create, update, delete, batch
      operations (max 100, partial failure allowed), and status transitions. A
      line item defines budget, goal, schedule, and targeting under its parent
      order.
    name: LineItems
  - description: Media library. List, upload, and delete media files used by creatives.
    name: Media Library
  - description: >-
      Metric query endpoints. Retrieve aggregated metrics for ad units,
      creatives, line items, and related entities.
    name: Metric
  - description: >-
      Advertiser order management. Operators and admins create and manage orders
      that group line items under a single budget; advertisers can read their
      own. Includes batch operations (max 100) and draft-only deletion rules.
    name: Orders
  - description: >-
      Placement management. A placement maps ad units to a serving surface.
      Endpoints cover CRUD and replacing the ad units bound to a placement.
    name: Placements
  - description: >-
      System settings. Read and update system configuration, including site
      logo, public URL, TLS, and access-token regeneration.
    name: Settings
  - description: System resources. Public static resources such as the site logo.
    name: System
  - description: >-
      Operational/developer control endpoints. Low-level ext patches and health
      checks intended for internal operation, not general API consumers.
    name: developer
  - description: >-
      Operational allocation control. Update allocation ext or force-update
      status (admin only).
    name: developer/control/allocations
  - description: >-
      Ad-serving monitoring (operational). Read ad-serving status, ad-unit
      monitoring history, and alerts.
    name: developer/monitoring
  - description: Internal health and probe endpoints.
    name: internal
  - description: >-
      Manager-level utility endpoints (e.g. service health) not tied to a
      specific resource.
    name: manager
  - description: Manage mappings between ad units, native formats, and native styles.
    name: Ad Unit Native Style
  - description: Manage custom targeting keys, including lifecycle and bulk operations.
    name: Custom Targeting Key
  - description: >-
      Manage values belonging to custom targeting keys, including lifecycle and
      bulk operations.
    name: Custom Targeting Value
  - description: Manage native formats and the fields that define each format.
    name: Native Format
  - description: List templates available for native styles.
    name: Native Style Template
  - description: Manage native rendering styles.
    name: Native Style
paths:
  /api/manager/experiments:
    post:
      tags:
        - Experiment
      summary: Create an experiment.
      operationId: handle_create_experiment_api_manager_experiments_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExperimentCreate'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperimentResponse'
          description: Successful Response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPExceptionResponse'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - HTTPBearer: []
components:
  schemas:
    ExperimentCreate:
      example:
        buckets:
          - name: control
            ratio: 0.5
          - name: variant
            ratio: 0.5
        end_date: '2026-05-31T23:59:59+09:00'
        name: 배너 소재 A/B 테스트
        start_date: '2026-05-01T00:00:00+09:00'
        status: active
        target_id: <placement_id>
        target_type: placement
      properties:
        buckets:
          items:
            $ref: '#/components/schemas/BucketCreate'
          maxItems: 15
          minItems: 1
          title: Buckets
          type: array
        end_date:
          description: End date of the experiment (UTC).
          format: date-time
          title: End Date
          type: string
        ext:
          anyOf:
            - {}
            - type: 'null'
          description: Extension field for additional experiment-specific data.
          title: Ext
        name:
          description: Human-readable name of the experiment.
          title: Name
          type: string
        start_date:
          description: Start date of the experiment (UTC).
          format: date-time
          title: Start Date
          type: string
        status:
          $ref: '#/components/schemas/ExperimentStatus'
          default: inactive
          description: Lifecycle status of the experiment.
        target_id:
          description: Identifier of the target entity.
          format: uuid
          title: Target Id
          type: string
        target_type:
          $ref: '#/components/schemas/ExperimentTargetType'
          description: Type of the target entity (ad unit or placement).
      required:
        - buckets
        - end_date
        - name
        - start_date
        - target_id
        - target_type
      title: ExperimentCreate
      type: object
    ExperimentResponse:
      description: Response schema for experiment records.
      properties:
        buckets:
          default: []
          description: Buckets defining traffic splits and line item assignments.
          items:
            $ref: '#/components/schemas/ExperimentBucket'
          maxItems: 15
          minItems: 1
          title: Buckets
          type: array
        created_at:
          format: date-time
          title: Created At
          type: string
        end_date:
          description: End date of the experiment (UTC).
          format: date-time
          title: End Date
          type: string
        ext:
          anyOf:
            - {}
            - type: 'null'
          description: Extension field for additional experiment-specific data.
          title: Ext
        id:
          description: Unique identifier for the experiment (UUID v4).
          format: uuid
          title: Id
          type: string
        name:
          description: Human-readable name of the experiment.
          title: Name
          type: string
        'no':
          anyOf:
            - type: integer
            - type: 'null'
          title: 'No'
        start_date:
          description: Start date of the experiment (UTC).
          format: date-time
          title: Start Date
          type: string
        status:
          $ref: '#/components/schemas/ExperimentStatus'
          default: inactive
          description: Lifecycle status of the experiment.
        target_id:
          description: Identifier of the target entity.
          format: uuid
          title: Target Id
          type: string
        target_type:
          $ref: '#/components/schemas/ExperimentTargetType'
          description: Type of the target entity (ad unit or placement).
        updated_at:
          format: date-time
          title: Updated At
          type: string
      required:
        - id
        - created_at
        - updated_at
        - end_date
        - name
        - start_date
        - target_id
        - target_type
      title: ExperimentResponse
      type: object
    HTTPExceptionResponse:
      properties:
        detail:
          description: Detailed explanation for the exception
          title: Detail
          type: string
      required:
        - detail
      title: HTTPExceptionResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    BucketCreate:
      properties:
        gating:
          anyOf:
            - $ref: '#/components/schemas/GatingConfig'
            - type: 'null'
          description: Optional gating configuration for this bucket.
        gating_policy:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional gating policy identifier for this bucket.
          title: Gating Policy
        line_item_rotate:
          $ref: '#/components/schemas/LineItemRotateType'
          default: random
          description: Optional line item rotation strategy for this bucket.
        line_items:
          description: Line items assigned to this bucket.
          items:
            $ref: '#/components/schemas/BucketLineItem'
          maxItems: 10
          title: Line Items
          type: array
        name:
          description: Human-readable name of the bucket.
          title: Name
          type: string
        proportion:
          description: Proportion of traffic assigned to this bucket.
          minimum: 0
          title: Proportion
          type: integer
      required:
        - line_items
        - name
        - proportion
      title: BucketCreate
      type: object
    ExperimentStatus:
      enum:
        - inactive
        - active
        - completed
      title: ExperimentStatus
      type: string
    ExperimentTargetType:
      enum:
        - ad_unit
        - placement
      title: ExperimentTargetType
      type: string
    ExperimentBucket:
      properties:
        gating:
          anyOf:
            - $ref: '#/components/schemas/GatingConfig'
            - type: 'null'
          description: Optional gating configuration for this bucket.
        gating_policy:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional gating policy identifier for this bucket.
          title: Gating Policy
        id:
          description: Identifier of the bucket within the experiment.
          maximum: 255
          minimum: 0
          title: Id
          type: integer
        is_deleted:
          default: false
          description: Whether this bucket has been soft-deleted.
          title: Is Deleted
          type: boolean
        line_item_rotate:
          $ref: '#/components/schemas/LineItemRotateType'
          default: random
          description: Optional line item rotation strategy for this bucket.
        line_items:
          description: Line items assigned to this bucket.
          items:
            $ref: '#/components/schemas/BucketLineItem'
          maxItems: 10
          title: Line Items
          type: array
        name:
          description: Human-readable name of the bucket.
          title: Name
          type: string
        proportion:
          description: Proportion of traffic assigned to this bucket.
          minimum: 0
          title: Proportion
          type: integer
      required:
        - id
        - line_items
        - name
        - proportion
      title: ExperimentBucket
      type: object
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    GatingConfig:
      properties:
        share_aware_ctr_gating:
          anyOf:
            - type: boolean
            - type: 'null'
          description: Whether share-aware CTR gating is enabled.
          title: Share Aware Ctr Gating
        share_aware_ctr_gating_config:
          anyOf:
            - $ref: '#/components/schemas/ShareAwareCtrGatingConfig'
            - type: 'null'
          description: Detailed configuration for share-aware CTR gating.
      title: GatingConfig
      type: object
    LineItemRotateType:
      enum:
        - sequential
        - weighted
        - random
        - score_aware
      title: LineItemRotateType
      type: string
    BucketLineItem:
      properties:
        gating:
          anyOf:
            - $ref: '#/components/schemas/GatingConfig'
            - type: 'null'
          description: Optional gating configuration for this line item.
        lid:
          description: Identifier of the line item.
          format: uuid
          title: Lid
          type: string
        weight:
          description: Relative weight used for rotation.
          minimum: 0
          title: Weight
          type: integer
      required:
        - lid
        - weight
      title: BucketLineItem
      type: object
    ShareAwareCtrGatingConfig:
      properties:
        alpha:
          anyOf:
            - type: number
            - type: 'null'
          description: Smoothing factor controlling adaptation speed.
          title: Alpha
        autotune_deadband:
          anyOf:
            - type: number
            - type: 'null'
          title: Autotune Deadband
        autotune_min_min_mult:
          anyOf:
            - type: number
            - type: 'null'
          title: Autotune Min Min Mult
        autotune_step_size:
          anyOf:
            - type: number
            - type: 'null'
          title: Autotune Step Size
        baseline_prior_impressions:
          anyOf:
            - type: number
            - type: 'null'
          description: Prior impression weight used when smoothing the baseline CTR.
          title: Baseline Prior Impressions
        cold_start_baseline_ctr:
          anyOf:
            - type: number
            - type: 'null'
          description: Baseline CTR used during the cold-start period.
          title: Cold Start Baseline Ctr
        floor_share:
          anyOf:
            - type: number
            - type: 'null'
          description: Minimum guaranteed serving share.
          title: Floor Share
        max_mult:
          anyOf:
            - type: number
            - type: 'null'
          description: Upper bound for the gating multiplier.
          title: Max Mult
        min_exploration_impressions:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          description: Minimum impressions required before gating activates.
          title: Min Exploration Impressions
        min_mult:
          anyOf:
            - type: number
            - type: 'null'
          description: Lower bound for the gating multiplier.
          title: Min Mult
        share_window_minutes:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          title: Share Window Minutes
        target_share_multiplier:
          anyOf:
            - type: number
            - type: 'null'
          description: Target serving share for the line item.
          title: Target Share Multiplier
      title: ShareAwareCtrGatingConfig
      type: object
  securitySchemes:
    HTTPBearer:
      description: >-
        Bearer authentication. Pass the access token in the `Authorization:
        Bearer <token>` header.
      scheme: bearer
      type: http

````