VoidhashDocs
DevelopersHelp centerGuidesAPI reference
Dashboard
Essentials
API overview
Authentication
Event capture
Push device API
Webhooks
Webhook delivery
Webhook events
Projects & keys
Projects
API keys
Audit log
Customers & access
Persons
Products
Perks
Sandbox
Paywalls
Paywalls
Paywall locations
Components
Component registry
Assets
Experiments & flags
Experiments
Feature flags
Analytics & events
Analytics
Analytics alerts
Events
Ingest policy
VoidQL
Tracking domains
Ads
Ads
Ad accounts
Meta measurement
Payments & stores
Payment providers
Payment provider products
Purchase history imports
Payment sources
Webhooks & notifications
Webhooks
Push notifications
Push configurations
Automations
Organization & team
Organizations
Members
Invitations
Billing
Your account
Profile
Session
Notices
Connected apps
Terms of Service
Developer tools
Schema
SDK
List experiments
Create an experiment
Retrieve an experiment
Update an experiment
Archive an experiment
Unarchive an experiment
Start an experiment
Pause an experiment
Conclude an experiment
List an experiment's arms
Replace an experiment's arms
Retrieve an experiment's results

Replace an experiment's arms

Replaces the experiment's arms and placements with the ones given and answers all of them.

Name an existing arm's id to keep it, so end users in it stay there. Exactly one arm is the control and the weights total 100.

Guide: Feature flags and A/B tests

PUT
/api/v1/projects/{projectId}/experiments/{experimentId}/variants

Authorization

AuthorizationBearer <token>

A project secret key: vh_sk_... for production, vh_sk_test_... for test. Keep it on your servers.

In: header

Path parameters

projectId*string

The project's id, proj_.... A secret key works only in the project it belongs to.

experimentId*string

The experiment's id, exp_....

Request body

application/json

TypeScript definitions

Use the request body type in TypeScript.

variants*array<>

Every arm the experiment has from now on; arms left out are removed. Exactly one is the control, and the weights total 100.

Examples

curl -X PUT "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/experiments/exp_c6v8b3n5q0w2e7h7d2k9m4x1/variants" \  -H "Authorization: Bearer vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "variants": [      {        "id": "exp_var_w2e7h7d2k9m4x1c6v8b3n5q0",        "name": "Monthly first",        "isControl": true,        "weightPercentage": 50,        "placements": [          {            "paywallLocationId": "pw_loc_m4x1c6v8b3n5q0w2e7h7d2k9",            "paywallId": "pw_r3t6y9u2i5o8p1a4s7d0f3g6"          }        ]      },      {        "id": "exp_var_n5q0w2e7h7d2k9m4x1c6v8b3",        "name": "Annual first",        "isControl": false,        "weightPercentage": 50,        "placements": [          {            "paywallLocationId": "pw_loc_m4x1c6v8b3n5q0w2e7h7d2k9",            "paywallId": "pw_h7d2k9m4x1c6v8b3n5q0w2e7"          }        ]      }    ]  }'
{  "data": [    {      "id": "exp_var_w2e7h7d2k9m4x1c6v8b3n5q0",      "name": "Monthly first",      "isControl": true,      "weightPercentage": 50,      "placements": [        {          "paywallLocationId": "pw_loc_m4x1c6v8b3n5q0w2e7h7d2k9",          "paywallId": "pw_r3t6y9u2i5o8p1a4s7d0f3g6"        }      ]    },    {      "id": "exp_var_n5q0w2e7h7d2k9m4x1c6v8b3",      "name": "Annual first",      "isControl": false,      "weightPercentage": 50,      "placements": [        {          "paywallLocationId": "pw_loc_m4x1c6v8b3n5q0w2e7h7d2k9",          "paywallId": "pw_h7d2k9m4x1c6v8b3n5q0w2e7"        }      ]    }  ],  "pageInfo": {    "endCursor": null,    "hasNextPage": false  }}

{  "error": {    "type": "invalid_request",    "code": "invalid_variants",    "message": "Boolean feature flags cannot have variants",    "param": "variants"  }}

{  "error": {    "type": "unauthenticated",    "code": "invalid_api_key",    "message": "This secret key is not valid."  }}
{  "error": {    "type": "permission_denied",    "code": "permission_denied",    "message": "Insufficient permissions."  }}
{  "error": {    "type": "not_found",    "code": "project_not_found",    "message": "There is no project proj_tz4a98xxat96iws9zmbrgj3a, or this credential cannot use it.",    "param": "projectId"  }}
{  "error": {    "type": "conflict",    "code": "experiment_variants_locked",    "message": "This experiment is running, so its arms cannot change; pause it first."  }}
{  "error": {    "type": "internal",    "code": "internal_error",    "message": "Something went wrong on our side. Try again, and contact support with the Request-Id header if it keeps failing."  }}

Response body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

Errors

StatustypecodeWhen
400invalid_requestinvalid_variants—
400invalid_requestexperiment_variant_not_found—
400invalid_requestpaywall_not_found—
400invalid_requestpaywall_location_not_found—
409conflictexperiment_variants_lockedWhile it runs; pause it first.

It can also fail with the errors every operation shares, such as unauthenticated; see Errors.

More in Experiments

  • List experiments GET
  • Create an experiment POST
  • Retrieve an experiment GET
  • Update an experiment PATCH
  • Archive an experiment POST
  • Unarchive an experiment POST
  • Start an experiment POST
  • Pause an experiment POST
  • Conclude an experiment POST
  • List an experiment's arms GET
  • Retrieve an experiment's results GET

Something wrong or missing on this page? Tell us by email or on Discord.

PreviousList an experiment's armsNextRetrieve an experiment's results

On this page

AuthorizationPath parametersRequest bodyExamplesResponse bodyErrorsMore in Experiments