---
title: "Create Experiment"
method: POST
path: "/core/experiments"
tags: ["Experiments"]
---

# Create Experiment

`POST /core/experiments`

## Request

- Base URL: `https://api.anyreach.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.anyreach.ai/core/experiments`
- Auth: HTTP bearer

Create a draft experiment. Start it to split traffic.

## Headers

- `x-anyreach-org` string, nullable: Organization ID for user PATs (pat_ prefix tokens)

## Request body

- ExperimentCreateRequest
  - `name` string, required
  - `hypothesis` string
  - `primary_metric` string, nullable
  - `widget_ids` string[], required: Web widgets whose visitors are split.
  - `variants` VariantInput[], required
    - `key` string, required: Stable key stamped on events and conversations.
    - `name` string
    - `weight` integer, required: Percent of visitors.
    - `overlay` object: Patch on the widget config (`v1`), and optionally `agent_version_id`. `null` removes a key.

## Response `201`

Successful Response

- ExperimentOut: An experiment, plus what its variants change, for the editors.
  - `id` string, required
  - `organization_id` string, required
  - `name` string, required
  - `hypothesis` string
  - `unit` string
  - `status` 'draft' | 'running' | 'paused' | 'concluded', required
  - `salt` string, required
  - `variants` ExperimentVariant[], required
    - `key` string, required
    - `name` string
    - `weight` integer, required
    - `overlay` object
  - `primary_metric` string, nullable
  - `started_at` string, date-time, nullable
  - `ended_at` string, date-time, nullable
  - `winner_key` string, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `created_by` string, nullable
  - `modified_by` string, nullable
  - `scopes` ExperimentScope[]
    - `scope_type` 'web_widget' | 'phone_number' | 'email_address' | 'agent', required
    - `scope_id` string, required
    - `active` boolean
  - `touched_sections` string[]
  - `swaps_agent_version` boolean
  - `metric_options` string[]

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/anyreach/apis/anyreach-api.md) - [All operations](https://skmtc.dev/anyreach/apis/anyreach-api/llms.txt) - [OpenAPI document](https://skmtc.dev/anyreach/apis/anyreach-api/revisions/2eddf40c8c93?raw)