WHwhop
Experiments

Create Experiment

Creates an experiment or feature flag in draft status for an account. Nothing is served until you activate it with POST /experiments/:id/activate. Requires experiment:manage on the account.

post/experiments

Request

  • Base URL
    https://api.whop.com/api/v1
  • URL
    https://api.whop.com/api/v1/experiments
  • Auth
    HTTP bearer

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

A unique key that makes this request safe to retry. See Idempotent requests.

Request body

account_idstring required

Owning account ID. Required; ownership cannot change.

bucket_by'user' | 'account' | 'anonymous'

Randomization unit, and the only identity the assignment is keyed on — evaluation fails rather than falling back to another. user (default) uses subject[user_id]; account uses subject[account_id], so every user of an account gets the same arm; anonymous uses the anonymous id and survives sign-in. Fixed after creation.

feature_flag_onlyboolean

When true, creates a binary feature flag rather than a full experiment. Feature flags expose the same evaluation API but do not collect metric results. Defaults to false.

flag_keystring required

Developer-chosen handle referenced from code, used in evaluation and results calls. Interchangeable with the returned expt_ id anywhere the API takes an experiment identifier.

hypothesisstring nullable

Required for full experiments; rejected on feature flags. Structure it as "If we [change] for [cohort], then [measurable behavior] will [increase/decrease], resulting in [business outcome], because [evidence]. Created by [name]." Evidence should be something real — a baseline number, a funnel breakdown — not a guess, and [name] is you, not something to leave blank.

namestring

Human-readable display name. Defaults to flag_key when omitted.

Example request

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "bucket_by": "user",
  "control": {
    "related_resource": {
      "object": "app"
    }
  },
  "flag_key": "checkout_redesign_v2",
  "hypothesis": "If we send a blueprint nudge email 30 minutes after business creation, then GTV within 10 hours will increase among newly created businesses, resulting in more new business operators generating GTV within 10 hours, because operators currently land on an empty dashboard with no concrete next step. Created by Jane Doe.",
  "name": "Checkout Redesign V2",
  "related_resource": {
    "object": "app"
  },
  "targeting_rules": [
    {
      "conditions": [
        {
          "operator": "any",
          "type": "user_id"
        }
      ],
      "type": "include"
    }
  ],
  "variants": [
    {
      "name": "treatment",
      "related_resource": {
        "object": "app"
      },
      "weight": 50
    }
  ]
}

Response

experiment created

account_idstring required

Owning account ID.

assignment_seedstring required

Assignment hashes UTF-8 seed + subject ID with CRC32 modulo 100 and selects the stored end-exclusive range.

bucket_by'user' | 'account' | 'anonymous' nullable

Randomization unit — user buckets each user independently, account buckets whole accounts (every user of an account gets the same arm). null for feature flags.

configuration_revisioninteger required

Revision of the serving configuration. Increments on every configuration change, so a cached definition with a lower revision is stale. Does not change the assignment seed.

created_atstring nullable

When the experiment was created, as an ISO 8601 timestamp.

created_bystring nullable

ID of the user who created the experiment, prefixed user_. null for experiments created before creators were recorded.

ended_atstring nullable

When the experiment stopped collecting data, as an ISO 8601 timestamp. null while still running.

feature_flag_onlyboolean nullable

true when this was created as a feature flag rather than a full experiment. Feature flags share the same evaluation API but do not collect metric results.

findingsstring nullable

What was learned and why this outcome, recorded when the experiment was ended. null until then.

flag_keystring required

Developer-chosen handle referenced from code. Anywhere the API takes an experiment identifier, the expt_ id and the flag_key are interchangeable.

hypothesisstring nullable

Hypothesis for this experiment. null when none is set, and always null for feature flags.

idstring required

Unique identifier for the experiment, prefixed expt_.

namestring required

Human-readable display name.

started_atstring nullable

When the experiment began collecting data, as an ISO 8601 timestamp. null for drafts.

status'draft' | 'active' | 'paused' | 'ended' required

Lifecycle state. draft — not yet live; active — currently running; paused — traffic paused; ended — concluded.

updated_atstring date_time nullable required
winning_armstring nullable

The treatment that won, set when the experiment was ended. Once set, every evaluation returns this arm to every caller regardless of targeting or allocation, and no further exposures are recorded. null means control won — an ended experiment with no winning arm evaluates to control for everyone. Always null for feature flags, which simply evaluate to disabled once ended.

Example response

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "assignment_seed": "checkout_redesign_v21768435200",
  "bucket_by": "user",
  "configuration_revision": 1,
  "control": {
    "related_resource": {
      "object": "app"
    }
  },
  "created_at": "2026-01-01T12:00:00.000Z",
  "created_by": "user_xxxxxxxxxxxxxx",
  "ended_at": "2026-01-01T12:00:00.000Z",
  "findings": "Treatment lifted conversion 8%",
  "flag_key": "checkout_redesign_v2",
  "hypothesis": "Users will convert more",
  "id": "expt_xxxxxxxxxxxxxx",
  "name": "Checkout Redesign V2",
  "related_resource": {
    "object": "app"
  },
  "started_at": "2026-01-01T12:00:00.000Z",
  "status": "draft",
  "targeting_rules": [
    {
      "conditions": [
        {
          "operator": "any",
          "type": "user_id"
        }
      ],
      "type": "include"
    }
  ],
  "updated_at": "2026-01-01T12:00:00.000Z",
  "variants": [
    {
      "name": "treatment",
      "ranges": [
        [
          0,
          50
        ]
      ],
      "related_resource": {
        "object": "app"
      },
      "weight": 50
    }
  ],
  "winning_arm": "treatment"
}

Changes

No operation changes recorded.