# create\_experiment

Create an experiment. Requires mcp:write and the existing ConversionLab experiment create policy.

Create an experiment. Requires mcp:write and the existing ConversionLab experiment create policy.

## Permissions

```json
{
  "ability": "mcp:write",
  "role": "The existing entity create/update policy must allow this user; write ability alone is insufficient.",
  "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.",
  "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant."
}
```

## Input

```json
{
  "properties": {
    "project_id": {
      "description": "Project ID",
      "type": "integer"
    },
    "type": {
      "description": "Experiment type",
      "enum": [
        "ab_test",
        "multivariate_test"
      ],
      "type": "string"
    },
    "name": {
      "description": "Experiment name",
      "maxLength": 255,
      "type": "string"
    },
    "state_id": {
      "description": "Optional experiment state ID",
      "type": "integer"
    },
    "description": {
      "description": "Optional description",
      "type": "string"
    },
    "hypothesis": {
      "description": "Optional hypothesis",
      "type": "string"
    },
    "insight_ids": {
      "description": "Optional insight IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "idea_ids": {
      "description": "Optional idea IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "page_ids": {
      "description": "Optional page IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "audience_ids": {
      "description": "Optional audience IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "primary_metric_id": {
      "description": "Optional primary metric ID",
      "type": "integer"
    },
    "secondary_metric_ids": {
      "description": "Optional secondary metric IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "guardrail_metric_ids": {
      "description": "Optional guardrail metric IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "start_date": {
      "description": "Optional start date",
      "type": "string"
    },
    "end_date": {
      "description": "Optional end date",
      "type": "string"
    }
  },
  "type": "object",
  "required": [
    "project_id",
    "type",
    "name"
  ]
}
```

## Output

```json
{
  "type": "object",
  "properties": {
    "created": {
      "type": "boolean",
      "const": true
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "project_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "name": {
          "type": "string"
        },
        "state_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "primary_metric_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "type": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "ab_test",
            "multivariate_test",
            null
          ]
        },
        "result": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "conclusive_winner",
            "conclusive_loser",
            "inconclusive",
            "error",
            "other",
            null
          ]
        },
        "decision": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "implement",
            "rollout",
            "retest",
            "iterate",
            "reject",
            null
          ]
        },
        "start_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "end_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "project": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "hypothesis": {
          "type": [
            "string",
            "null"
          ]
        },
        "learning": {
          "type": [
            "string",
            "null"
          ]
        },
        "stop_reason": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "hypothesis_rejected",
            "hypothesis_iteration",
            "user_feedback",
            "data_issue",
            "implementation_issue",
            "experiment_setup_issue",
            "guardrail_metric_impact",
            "secondary_metric_impact",
            "operational_decision",
            "performance_issue",
            "testing",
            "tracking_issue",
            "other",
            null
          ]
        },
        "state": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "primary_metric": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "secondary_metrics": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ]
          }
        },
        "guardrail_metrics": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ]
          }
        },
        "audiences": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ]
          }
        },
        "ideas": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ]
          }
        },
        "insights": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ]
          }
        },
        "pages": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ]
          }
        }
      },
      "required": [
        "id",
        "project_id",
        "name",
        "state_id",
        "primary_metric_id",
        "type",
        "result",
        "decision",
        "start_date",
        "end_date",
        "created_at",
        "updated_at",
        "description",
        "project",
        "hypothesis",
        "learning",
        "stop_reason",
        "state",
        "primary_metric",
        "secondary_metrics",
        "guardrail_metrics",
        "audiences",
        "ideas",
        "insights",
        "pages"
      ]
    }
  },
  "required": [
    "created",
    "data"
  ]
}
```

## Examples

### Request arguments

```json
{
  "project_id": 1,
  "type": "ab_test",
  "name": "Show delivery estimate"
}
```

### Result

```json
{
  "created": true,
  "data": {
    "id": 101,
    "project_id": 1,
    "state_id": null,
    "primary_metric_id": null,
    "name": "Show delivery estimate",
    "type": "ab_test",
    "result": null,
    "decision": null,
    "start_date": null,
    "end_date": null,
    "created_at": "2026-01-15T12:00:00+00:00",
    "updated_at": "2026-01-15T12:00:00+00:00",
    "description": null,
    "hypothesis": null,
    "learning": null,
    "stop_reason": null,
    "project": null,
    "state": null,
    "primary_metric": null,
    "secondary_metrics": [],
    "guardrail_metrics": [],
    "audiences": [],
    "ideas": [],
    "insights": [],
    "pages": []
  }
}
```

## Errors

```json
[
  {
    "status": 401,
    "description": "Missing, expired, or revoked bearer token."
  },
  {
    "status": 403,
    "description": "Missing MCP ability, team membership, plan entitlement, or user permission."
  },
  {
    "status": 404,
    "description": "The MCP server is disabled."
  },
  {
    "status": 429,
    "description": "Rate limited; honor Retry-After before retrying."
  },
  {
    "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call."
  }
]
```

An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication).