# Plan an A/B test of a page or a section

`POST /hosting/sites/{id}/experiments` · Rivier · hosting

Plan an A/B test of a page or a section: variants are patches, the goal is a click, a form submit or an event, and the baseline rate and the smallest change worth acting on fix how many page views each arm needs. It stays a draft until a person starts it.

- Scope: hosting:write
- Mcp: rivier_site_experiment_plan
- Graphql: Mutation.hostingExperimentCreate
- Sdk: hosting.experiment.create
- Cli: hosting experiment create

## Parameters

- `id` (path, required), string

## Request body

`application/json`

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "pageId": {
      "type": "string",
      "maxLength": 80
    },
    "hypothesis": {
      "type": "string",
      "maxLength": 400,
      "default": ""
    },
    "variants": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "ops": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "op": {
                      "type": "string",
                      "const": "set"
                    },
                    "block": {
                      "type": "string"
                    },
                    "path": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 200
                    },
                    "value": {},
                    "origin": {
                      "type": "string",
                      "enum": [
                        "human",
                        "ai",
                        "template"
                      ]
                    }
                  },
                  "required": [
                    "op",
                    "block",
                    "path"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "op": {
                      "type": "string",
                      "const": "unset"
                    },
                    "block": {
                      "type": "string"
                    },
                    "path": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 200
                    },
                    "origin": {
                      "type": "string",
                      "enum": [
                        "human",
                        "ai",
                        "template"
                      ]
                    }
                  },
                  "required": [
                    "op",
                    "block",
                    "path"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "op": {
                      "type": "string",
                      "const": "insert"
                    },
                    "block": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "pattern": "^[a-z][a-z0-9_-]{0,39}$"
                        },
                        "parent": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "default": null
                        },
                        "slot": {
                          "type": "string",
                          "maxLength": 24,
                          "default": "children"
                        },
                        "type": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 40
                        },
                        "v": {
                          "type": "string"
                        },
                        "props": {
                          "type": "object",
                          "additionalProperties": {},
                          "default": {}
                        },
                        "bindings": {
                          "type": "object",
                          "additionalProperties": {},
                          "default": {}
                        },
                        "origin": {
                          "type": "string",
                          "enum": [
                            "human",
                            "ai",
                            "template"
                          ],
                          "default": "human"
                        },
                        "locked": {
                          "type": "boolean",
                          "default": false
                        },
                        "lockedProps": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "id",
                        "type"
                      ],
                      "additionalProperties": false
                    },
                    "index": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "descendants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "pattern": "^[a-z][a-z0-9_-]{0,39}$"
                          },
                          "parent": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "default": null
                          },
                          "slot": {
                            "type": "string",
                            "maxLength": 24,
                            "default": "children"
                          },
                          "type": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 40
                          },
                          "v": {
                            "type": "string"
                          },
                          "props": {
                            "type": "object",
                            "additionalProperties": {},
                            "default": {}
                          },
                          "bindings": {
                            "type": "object",
                            "additionalProperties": {},
                            "default": {}
                          },
                          "origin": {
                            "type": "string",
                            "enum": [
                              "human",
                              "ai",
                              "template"
                            ],
                            "default": "human"
                          },
                          "locked": {
                            "type": "boolean",
                            "default": false
                          },
                          "lockedProps": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        },
                        "required": [
                          "id",
                          "type"
                        ],
                        "additionalProperties": false
                      },
                      "maxItems": 200
                    },
                    "origin": {
                      "type": "string",
                      "enum": [
                        "human",
                        "ai",
                        "template"
                      ]
                    }
                  },
                  "required": [
                    "op",
                    "block"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "op": {
                      "type": "string",
                      "const": "remove"
                    },
                    "block": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "op",
                    "block"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "op": {
                      "type": "string",
                      "const": "move"
                    },
                    "block": {
                      "type": "string"
                    },
                    "parent": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "slot": {
                      "type": "string",
                      "maxLength": 24
                    },
                    "index": {
                      "type": "integer",
                      "minimum": 0
                    }
                  },
                  "required": [
                    "op",
                    "block",
                    "parent"
                  ],
                  "additionalProperties": false
                }
              ]
            },
            "minItems": 1,
            "maxItems": 100
          }
        },
        "required": [
          "name",
          "ops"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 3
    },
    "goal": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "click"
            },
            "block": {
              "type": "string",
              "maxLength": 80
            }
          },
          "required": [
            "kind"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "submit"
            },
            "block": {
              "type": "string",
              "maxLength": 80
            }
          },
          "required": [
            "kind"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "event"
            },
            "name": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9_-]{1,39}$"
            }
          },
          "required": [
            "kind",
            "name"
          ],
          "additionalProperties": false
        }
      ]
    },
    "baselineRate": {
      "type": "number",
      "minimum": 0.001,
      "maximum": 0.9
    },
    "minEffect": {
      "type": "number",
      "minimum": 0.02,
      "maximum": 1,
      "default": 0.2
    },
    "horizon": {
      "type": "integer",
      "minimum": 100,
      "maximum": 1000000
    }
  },
  "required": [
    "name",
    "pageId",
    "variants",
    "goal",
    "baselineRate"
  ],
  "additionalProperties": false
}
```

## Responses

- `201`: Success
- `400`: The request was malformed
- `401`: No valid credential
- `403`: The credential lacks the scope, origin or address
- `429`: Over the key's rate limit; see Retry-After

## Example

```sh
curl -X POST 'https://api.rivier.ai/hosting/sites/{id}/experiments' \
  -H 'Authorization: Bearer $KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "pageId": "string",
  "variants": [
    {
      "name": "string",
      "ops": []
    }
  ],
  "goal": {
    "kind": "click"
  },
  "baselineRate": 0
}'
```