Create experiment

POST /v1/experiment

Registers a controlled experiment AND puts its assignment flag live, in that order, so the arms start bucketing subjects the moment this returns 201 — the flag is created active at 100% rollout, with each variant weighted as declared. There is no separate start call; creating IS starting.

A variant carries an opaque payload this primitive never interprets: a feature config, an ad-creative id, a subject line, a model id.

Requires a validated principal, and refuses without one. The org and project are taken from that principal and the creator is stamped from the credential — none of the three is a body field, so an experiment cannot be filed against another tenant. An id already used in this project is a conflict, never a silent overwrite: re-creating would stomp the assignment flag of a run in progress.

It fails closed on the flag write. An experiment whose assignment flag does not exist would assign nobody, so if that write fails nothing is registered.

Request

11 fields, body application/json (required).

Response

201 body — 18 fields.

Failure carries the platform error shape — see Errors.

Examples

hanzo experiment create \
  --id <id> \
  --metric-event <metricEvent> \
  --variants '[{"control":false,"key":"<key>","payload":"<payload>","weight":0}]'

import { Configuration, ExperimentApi } from 'hanzoai';

const api = new ExperimentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postExperiment({ id: "<id>", metricEvent: "<metricEvent>", variants: [{"control":false,"key":"<key>","payload":"<payload>","weight":0}] });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import ExperimentApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = ExperimentApi(client).post_experiment(id="<id>", metric_event="<metricEvent>", variants=[{"control":false,"key":"<key>","payload":"<payload>","weight":0}])

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.ExperimentAPI.PostExperiment(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, experiment_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = experiment_api::post_experiment(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.ExperimentApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new ExperimentApi(client).postExperiment();

curl -X POST https://api.hanzo.ai/v1/experiment \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "id": "<id>",
       "metricEvent": "<metricEvent>",
       "variants": [
         {
           "control": false,
           "key": "<key>",
           "payload": "<payload>",
           "weight": 0
         }
       ]
     }'

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_experiments"
         }
       }
     }'

Experiment API · All Hanzo APIs · Interactive reference