Experiment Variants API

Manage variants on a parent experiment. Create, list, update, and delete control and treatment variants and adjust their weights.

Manage variants on a parent experiment. Each variant is either a redirect (sends matched visitors to a new URL) or a dom_modifications set (declarative on-page mutations). Variant content (redirect URL, DOM modifications) can only be edited while the parent experiment is in draft status. However, traffic weights can be adjusted on running or paused experiments — the change is recorded in the experiment's change log so results remain interpretable. Completed experiments cannot be edited.

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

limit?|

Maximum number of variants to return. Defaults to 200; values below 1 are clamped to 1 and values above 200 are clamped to 200. Variants per experiment are capped at 200 server-side, so a single request returns the full set.

cursor?string

Opaque pagination cursor from pagination.nextCursor in the previous response. Do not decode or modify it. Malformed cursors return 400 Bad Request.

experimentId*string

Required. List variants belonging to this parent experiment.

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/experiment-variants?experimentId=08524dc8-5289-48e8-bf40-b3a7cfa6ca0a"

{
  "entities": [
    {
      "id": "var_01HZX8YJH3Z3W1R2Q4M5N6P7Q8",
      "experimentId": "exp_01HZX8TK6TSN91C5XWZP3N1M4E",
      "name": "Headline Variant B",
      "isControl": false,
      "weight": 50,
      "variantType": "string",
      "redirectUrl": "https://www.example.com/pricing-v2",
      "domModifications": [
        {
          "selector": "h1.hero-title",
          "action": "customCss",
          "value": "Start your free trial",
          "styles": [
            {
              "property": "background-color",
              "value": "#10B981"
            }
          ],
          "attribute": {}
        }
      ]
    }
  ],
  "pagination": {
    "nextCursor": "string",
    "hasMore": true
  }
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

experimentId*string

Parent experiment ID that will own this new variant.

name*string

Human-readable name for the new variant.

weight*integer

Traffic weight for this variant as a percentage (0–100). Treatment weights are percentages of the split and must total 99% or less to leave room for the control; the control variant is the remainder (100 − Σ treatment weights, always ≥ 1%) and is maintained automatically.

variantType?|

Variant delivery mechanism. dom_modifications mutates the current page in-place at SDK runtime — use it for copy/style/image/HTML changes that keep visitors on the same URL (headline copy tests, button color, hero image swap). redirect routes the visitor to a different URL entirely — use it for landing-page A/B tests, alternate pricing pages, or any test where the page itself is the variable. They are not interchangeable: a redirect variant cannot also tweak DOM, and a dom_modifications variant cannot send the visitor elsewhere.

redirectUrl?|

Required for redirect variants. Use either a site-relative path such as /pricing-v2 or an absolute https:// URL. Cross-origin http:// URLs are rejected. Omit for DOM modification variants.

domModifications?array<>|

Required for DOM modification variants. Omit for redirect variants. Each entry is {selector, action, value}.

isControl?|

Mark this variant as the experiment control. Defaults to false. The API rejects the request with 409 if the experiment already has a control variant. Every experiment keeps exactly one control whose weight is the auto-derived remainder of the split, so the control cannot be cleared while it would leave the treatments at 100% (no room for a control). DELETE on the control returns 409.

Response Body

`application/json`

curl -X POST "https://example.com/rest/v1/experiment-variants" \  -H "Content-Type: application/json" \  -d '{    "experimentId": "string",    "name": "Variant B",    "weight": 50  }'

{
  "id": "var_01HZX8YJH3Z3W1R2Q4M5N6P7Q8",
  "experimentId": "exp_01HZX8TK6TSN91C5XWZP3N1M4E",
  "name": "Headline Variant B",
  "isControl": false,
  "weight": 50,
  "variantType": "string",
  "redirectUrl": "https://www.example.com/pricing-v2",
  "domModifications": [
    {
      "selector": "h1.hero-title",
      "action": "customCss",
      "value": "Start your free trial",
      "styles": [
        {
          "property": "background-color",
          "value": "#10B981"
        }
      ],
      "attribute": {}
    }
  ]
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/experiment-variants/string"

{
  "id": "var_01HZX8YJH3Z3W1R2Q4M5N6P7Q8",
  "experimentId": "exp_01HZX8TK6TSN91C5XWZP3N1M4E",
  "name": "Headline Variant B",
  "isControl": false,
  "weight": 50,
  "variantType": "string",
  "redirectUrl": "https://www.example.com/pricing-v2",
  "domModifications": [
    {
      "selector": "h1.hero-title",
      "action": "customCss",
      "value": "Start your free trial",
      "styles": [
        {
          "property": "background-color",
          "value": "#10B981"
        }
      ],
      "attribute": {}
    }
  ]
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?|

Updated variant name.

weight?|

Updated traffic weight as a percentage (0–100). The control variant weight is derived from the treatments (it is the remainder of the split) and cannot be set directly.

variantType?|

Updated variant delivery mechanism. dom_modifications mutates the current page in-place; redirect sends the visitor to a different URL — pick based on whether the page or the content is the variable. Changing this also requires updating the matching payload field (redirectUrl or domModifications).

redirectUrl?|

Updated redirect URL for redirect variants. Use either a site-relative path such as /pricing-v2 or an absolute https:// URL. Cross-origin http:// URLs are rejected.

domModifications?array<>|

Updated declarative DOM mutations. Sending this field replaces the prior list — partial-array merging is not supported.

isControl?|

Promote or demote this variant as the control. Promoting a second variant while another already has isControl: true is rejected with 409. Demoting the control (isControl: false) is rejected when it would leave the treatments at 100% — there must always be room for a control.

Response Body

`application/json`

curl -X PATCH "https://example.com/rest/v1/experiment-variants/string" \  -H "Content-Type: application/json" \  -d '{}'

{
  "id": "var_01HZX8YJH3Z3W1R2Q4M5N6P7Q8",
  "experimentId": "exp_01HZX8TK6TSN91C5XWZP3N1M4E",
  "name": "Headline Variant B",
  "isControl": false,
  "weight": 50,
  "variantType": "string",
  "redirectUrl": "https://www.example.com/pricing-v2",
  "domModifications": [
    {
      "selector": "h1.hero-title",
      "action": "customCss",
      "value": "Start your free trial",
      "styles": [
        {
          "property": "background-color",
          "value": "#10B981"
        }
      ],
      "attribute": {}
    }
  ]
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X DELETE "https://example.com/rest/v1/experiment-variants/string"

{
  "id": "var_01HZX8YJH3Z3W1R2Q4M5N6P7Q8",
  "experimentId": "exp_01HZX8TK6TSN91C5XWZP3N1M4E",
  "name": "Headline Variant B",
  "isControl": false,
  "weight": 50,
  "variantType": "string",
  "redirectUrl": "https://www.example.com/pricing-v2",
  "domModifications": [
    {
      "selector": "h1.hero-title",
      "action": "customCss",
      "value": "Start your free trial",
      "styles": [
        {
          "property": "background-color",
          "value": "#10B981"
        }
      ],
      "attribute": {}
    }
  ]
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

{
  "error": "string",
  "details": "string"
}

Experiment Variants

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`