Add or remove Contextual Bandit variations
Adds and/or removes variations on a Contextual Bandit. Send addVariations and removeVariationIds independently; both are optional. New arms must carry a values entry for each linked feature. Running CBs publish the linked-feature updates; draft CBs stage them until start. Under an approval flow, unapproved drafts leave the added arm pending (zero weight, filtered from the SDK) until every linked feature’s draft is live. Removed arms are tombstoned; their ids can never be re-added. Weights are reconciled server-side.
POST
/
v1
/
contextual-bandits
/
{id}
/
variations
cURL
curl -X POST 'https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations' \
-H 'Authorization: Bearer YOUR_API_KEY'import requests
url = "https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations"
payload = {
"addVariations": [
{
"name": "<string>",
"id": "<string>",
"description": "<string>",
"key": "<string>",
"screenshots": [
{
"path": "<string>",
"width": 123,
"height": 123,
"description": "<string>"
}
],
"values": {}
}
],
"removeVariationIds": ["<string>"],
"updateVariations": [
{
"id": "<string>",
"name": "<string>",
"description": "<string>"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
addVariations: [
{
name: '<string>',
id: '<string>',
description: '<string>',
key: '<string>',
screenshots: [{path: '<string>', width: 123, height: 123, description: '<string>'}],
values: {}
}
],
removeVariationIds: ['<string>'],
updateVariations: [{id: '<string>', name: '<string>', description: '<string>'}]
})
};
fetch('https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'addVariations' => [
[
'name' => '<string>',
'id' => '<string>',
'description' => '<string>',
'key' => '<string>',
'screenshots' => [
[
'path' => '<string>',
'width' => 123,
'height' => 123,
'description' => '<string>'
]
],
'values' => [
]
]
],
'removeVariationIds' => [
'<string>'
],
'updateVariations' => [
[
'id' => '<string>',
'name' => '<string>',
'description' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations"
payload := strings.NewReader("{\n \"addVariations\": [\n {\n \"name\": \"<string>\",\n \"id\": \"<string>\",\n \"description\": \"<string>\",\n \"key\": \"<string>\",\n \"screenshots\": [\n {\n \"path\": \"<string>\",\n \"width\": 123,\n \"height\": 123,\n \"description\": \"<string>\"\n }\n ],\n \"values\": {}\n }\n ],\n \"removeVariationIds\": [\n \"<string>\"\n ],\n \"updateVariations\": [\n {\n \"id\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"addVariations\": [\n {\n \"name\": \"<string>\",\n \"id\": \"<string>\",\n \"description\": \"<string>\",\n \"key\": \"<string>\",\n \"screenshots\": [\n {\n \"path\": \"<string>\",\n \"width\": 123,\n \"height\": 123,\n \"description\": \"<string>\"\n }\n ],\n \"values\": {}\n }\n ],\n \"removeVariationIds\": [\n \"<string>\"\n ],\n \"updateVariations\": [\n {\n \"id\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"addVariations\": [\n {\n \"name\": \"<string>\",\n \"id\": \"<string>\",\n \"description\": \"<string>\",\n \"key\": \"<string>\",\n \"screenshots\": [\n {\n \"path\": \"<string>\",\n \"width\": 123,\n \"height\": 123,\n \"description\": \"<string>\"\n }\n ],\n \"values\": {}\n }\n ],\n \"removeVariationIds\": [\n \"<string>\"\n ],\n \"updateVariations\": [\n {\n \"id\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"contextualBandit": {
"id": "<string>",
"dateCreated": "2023-11-07T05:31:56Z",
"dateUpdated": "2023-11-07T05:31:56Z",
"name": "<string>",
"owner": "<string>",
"tags": [
"<string>"
],
"archived": true,
"status": "draft",
"trackingKey": "<string>",
"hashAttribute": "<string>",
"variations": [
{
"id": "<string>",
"key": "<string>",
"name": "<string>",
"description": "<string>",
"status": "active"
}
],
"datasource": "<string>",
"contextualBanditQueryId": "<string>",
"seed": "<string>",
"currentLeafWeights": [
{
"leafId": 123,
"condition": {},
"weights": [
{
"variationId": "<string>",
"weight": 123
}
]
}
],
"banditVersion": 1,
"contextualAttributes": [
"<string>"
],
"minUsersPerLeaf": 123,
"maxLeaves": 123,
"holdoutPercent": 0.25,
"banditModelVersion": 1,
"description": "<string>",
"project": "<string>",
"ownerEmail": "<string>",
"dateStarted": "2023-11-07T05:31:56Z",
"dateStopped": "2023-11-07T05:31:56Z",
"coverage": 0.5,
"condition": "<string>",
"savedGroups": [
{
"match": "all",
"ids": [
"<string>"
]
}
],
"prerequisites": [
{
"id": "<string>",
"condition": "<string>"
}
],
"variationWeights": [
{
"variationId": "<string>",
"weight": 123
}
],
"decisionMetric": "<string>",
"scheduleValue": 123,
"scheduleUnit": "days",
"burnInValue": 123,
"burnInUnit": "days",
"conversionWindowValue": 123,
"conversionWindowUnit": "hours",
"stage": "explore",
"stageDateStarted": "2023-11-07T05:31:56Z",
"autoSnapshots": true,
"nextSnapshotAttempt": "2023-11-07T05:31:56Z"
},
"featureDraftPublishFailures": [
{
"featureId": "<string>",
"revisionVersion": 123,
"reason": "<string>"
}
]
}Authorizations
bearerAuthbasicAuth
If using Bearer auth, pass the Secret Key as the token:
curl https://api.growthbook.io/api/v1/features -H "Authorization: Bearer secret_abc123DEF456"
Path Parameters
Body
application/json
New arms to add. Omit id to have the server generate one and key to have the server assign the next integer.
Show child attributes
Show child attributes
Ids of active arms to remove. Removed arms are tombstoned in place and their ids can never be re-added.
Metadata edits to existing active arms. Only name and description may be changed; key, values, weights, screenshots, and status are preserved.
Show child attributes
Show child attributes
Was this page helpful?
⌘I
cURL
curl -X POST 'https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations' \
-H 'Authorization: Bearer YOUR_API_KEY'import requests
url = "https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations"
payload = {
"addVariations": [
{
"name": "<string>",
"id": "<string>",
"description": "<string>",
"key": "<string>",
"screenshots": [
{
"path": "<string>",
"width": 123,
"height": 123,
"description": "<string>"
}
],
"values": {}
}
],
"removeVariationIds": ["<string>"],
"updateVariations": [
{
"id": "<string>",
"name": "<string>",
"description": "<string>"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
addVariations: [
{
name: '<string>',
id: '<string>',
description: '<string>',
key: '<string>',
screenshots: [{path: '<string>', width: 123, height: 123, description: '<string>'}],
values: {}
}
],
removeVariationIds: ['<string>'],
updateVariations: [{id: '<string>', name: '<string>', description: '<string>'}]
})
};
fetch('https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'addVariations' => [
[
'name' => '<string>',
'id' => '<string>',
'description' => '<string>',
'key' => '<string>',
'screenshots' => [
[
'path' => '<string>',
'width' => 123,
'height' => 123,
'description' => '<string>'
]
],
'values' => [
]
]
],
'removeVariationIds' => [
'<string>'
],
'updateVariations' => [
[
'id' => '<string>',
'name' => '<string>',
'description' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations"
payload := strings.NewReader("{\n \"addVariations\": [\n {\n \"name\": \"<string>\",\n \"id\": \"<string>\",\n \"description\": \"<string>\",\n \"key\": \"<string>\",\n \"screenshots\": [\n {\n \"path\": \"<string>\",\n \"width\": 123,\n \"height\": 123,\n \"description\": \"<string>\"\n }\n ],\n \"values\": {}\n }\n ],\n \"removeVariationIds\": [\n \"<string>\"\n ],\n \"updateVariations\": [\n {\n \"id\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"addVariations\": [\n {\n \"name\": \"<string>\",\n \"id\": \"<string>\",\n \"description\": \"<string>\",\n \"key\": \"<string>\",\n \"screenshots\": [\n {\n \"path\": \"<string>\",\n \"width\": 123,\n \"height\": 123,\n \"description\": \"<string>\"\n }\n ],\n \"values\": {}\n }\n ],\n \"removeVariationIds\": [\n \"<string>\"\n ],\n \"updateVariations\": [\n {\n \"id\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"addVariations\": [\n {\n \"name\": \"<string>\",\n \"id\": \"<string>\",\n \"description\": \"<string>\",\n \"key\": \"<string>\",\n \"screenshots\": [\n {\n \"path\": \"<string>\",\n \"width\": 123,\n \"height\": 123,\n \"description\": \"<string>\"\n }\n ],\n \"values\": {}\n }\n ],\n \"removeVariationIds\": [\n \"<string>\"\n ],\n \"updateVariations\": [\n {\n \"id\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"contextualBandit": {
"id": "<string>",
"dateCreated": "2023-11-07T05:31:56Z",
"dateUpdated": "2023-11-07T05:31:56Z",
"name": "<string>",
"owner": "<string>",
"tags": [
"<string>"
],
"archived": true,
"status": "draft",
"trackingKey": "<string>",
"hashAttribute": "<string>",
"variations": [
{
"id": "<string>",
"key": "<string>",
"name": "<string>",
"description": "<string>",
"status": "active"
}
],
"datasource": "<string>",
"contextualBanditQueryId": "<string>",
"seed": "<string>",
"currentLeafWeights": [
{
"leafId": 123,
"condition": {},
"weights": [
{
"variationId": "<string>",
"weight": 123
}
]
}
],
"banditVersion": 1,
"contextualAttributes": [
"<string>"
],
"minUsersPerLeaf": 123,
"maxLeaves": 123,
"holdoutPercent": 0.25,
"banditModelVersion": 1,
"description": "<string>",
"project": "<string>",
"ownerEmail": "<string>",
"dateStarted": "2023-11-07T05:31:56Z",
"dateStopped": "2023-11-07T05:31:56Z",
"coverage": 0.5,
"condition": "<string>",
"savedGroups": [
{
"match": "all",
"ids": [
"<string>"
]
}
],
"prerequisites": [
{
"id": "<string>",
"condition": "<string>"
}
],
"variationWeights": [
{
"variationId": "<string>",
"weight": 123
}
],
"decisionMetric": "<string>",
"scheduleValue": 123,
"scheduleUnit": "days",
"burnInValue": 123,
"burnInUnit": "days",
"conversionWindowValue": 123,
"conversionWindowUnit": "hours",
"stage": "explore",
"stageDateStarted": "2023-11-07T05:31:56Z",
"autoSnapshots": true,
"nextSnapshotAttempt": "2023-11-07T05:31:56Z"
},
"featureDraftPublishFailures": [
{
"featureId": "<string>",
"revisionVersion": 123,
"reason": "<string>"
}
]
}