Create (overwrite) variants for a feature flag in all environments

PUT 
<your-unleash-url>/api/admin/projects/:projectId/features/:featureName/variants

This overwrites the current variants for the feature specified in the :featureName parameter in all environments.

The backend will validate the input for the following invariants

• If there are variants, there needs to be at least one variant with weightType: variable
• The sum of the weights of variants with weightType: fix must be strictly less than 1000 (< 1000)

The backend will also distribute remaining weight up to 1000 after adding the variants with weightType: fix together amongst the variants of weightType: variable

Request

Path Parameters

projectId stringrequired
featureName stringrequired

application/json

Body arrayrequired

variantsSchema

Array [
namestringrequired
The variants name. Is unique for this feature flag
Example: blue_group
weightnumberrequired
The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information
Possible values: <= 1000
weightTypestring
Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000
Possible values: [variable, fix]
Example: variable
stickinessstring
Stickiness is how Unleash guarantees that the same user gets the same variant every time
Example: custom.context.field
payload object
Extra data configured for this variant
typestringrequired
The type of the value. Commonly used types are string, number, json and csv.
Possible values: [json, csv, string, number]
valuestringrequired
The actual value of payload
overrides object[]
Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.
Array [
contextNamestringrequired
The name of the context field used to determine overrides
Example: userId
valuesstring[]required
Which values that should be overriden
Example: ["red","blue"]
]
]

Responses

200

featureVariantsSchema

application/json

Schema

Schema

versionintegerrequired
The version of the feature variants schema.
Example: 1
variants object[]required
All variants defined for a specific feature flag.
Array [
namestringrequired
The variants name. Is unique for this feature flag
Example: blue_group
weightnumberrequired
The weight is the likelihood of any one user getting this variant. It is a number between 0 and 1000. See the section on variant weights for more information
Possible values: <= 1000
weightTypestring
Set to fix if this variant must have exactly the weight allocated to it. If the type is variable, the weight will adjust so that the total weight of all variants adds up to 1000
Possible values: [variable, fix]
Example: variable
stickinessstring
Stickiness is how Unleash guarantees that the same user gets the same variant every time
Example: custom.context.field
payload object
Extra data configured for this variant
typestringrequired
The type of the value. Commonly used types are string, number, json and csv.
Possible values: [json, csv, string, number]
valuestringrequired
The actual value of payload
overrides object[]
Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.
Array [
contextNamestringrequired
The name of the context field used to determine overrides
Example: userId
valuesstring[]required
Which values that should be overriden
Example: ["red","blue"]
]
]

Example (auto)

{
  "version": 1,
  "variants": [
    {
      "name": "blue_group",
      "weight": 0,
      "weightType": "variable",
      "stickiness": "custom.context.field",
      "payload": {
        "type": "json",
        "value": "{\"color\": \"red\"}"
      },
      "overrides": [
        {
          "contextName": "userId",
          "values": [
            "red",
            "blue"
          ]
        }
      ]
    }
  ]
}

400

The request data does not match what we expect.

application/json

Schema

Schema

idstring
The ID of the error instance
Example: 9c40958a-daac-400e-98fb-3bb438567008
namestring
The name of the error kind
Example: ValidationError
messagestring
A description of what went wrong.
Example: The request payload you provided doesn't conform to the schema. The .parameters property should be object. You sent [].

Example (auto)

{
  "id": "9c40958a-daac-400e-98fb-3bb438567008",
  "name": "ValidationError",
  "message": "The request payload you provided doesn't conform to the schema. The .parameters property should be object. You sent []."
}

401

Authorization information is missing or invalid. Provide a valid API token as the authorization header, e.g. authorization:*.*.my-admin-token.

application/json

Schema

Schema

idstring
The ID of the error instance
Example: 9c40958a-daac-400e-98fb-3bb438567008
namestring
The name of the error kind
Example: AuthenticationRequired
messagestring
A description of what went wrong.
Example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.

Example (auto)

{
  "id": "9c40958a-daac-400e-98fb-3bb438567008",
  "name": "AuthenticationRequired",
  "message": "You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login."
}

403

The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation

application/json

Schema

Schema

idstring
The ID of the error instance
Example: 9c40958a-daac-400e-98fb-3bb438567008
namestring
The name of the error kind
Example: NoAccessError
messagestring
A description of what went wrong.
Example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.

Example (auto)

{
  "id": "9c40958a-daac-400e-98fb-3bb438567008",
  "name": "NoAccessError",
  "message": "You need the \"UPDATE_ADDON\" permission to perform this action in the \"development\" environment."
}

404

The requested resource was not found.

application/json

Schema

Schema

idstring
The ID of the error instance
Example: 9c40958a-daac-400e-98fb-3bb438567008
namestring
The name of the error kind
Example: NotFoundError
messagestring
A description of what went wrong.
Example: Could not find the addon with ID "12345".

Example (auto)

{
  "id": "9c40958a-daac-400e-98fb-3bb438567008",
  "name": "NotFoundError",
  "message": "Could not find the addon with ID \"12345\"."
}

Authorization: Authorization

name: Authorizationtype: apiKeyin: headerdescription: API key needed to access this API

• curl
• python
• go
• nodejs
• ruby
• csharp
• php
• java
• powershell

• CURL

curl -L -X PUT '<your-unleash-url>/api/admin/projects/:projectId/features/:featureName/variants' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: <Authorization>' \
-d '[
  {
    "name": "blue_group",
    "weight": 0,
    "weightType": "variable",
    "stickiness": "custom.context.field",
    "payload": {
      "type": "json",
      "value": "{\"color\": \"red\"}"
    },
    "overrides": [
      {
        "contextName": "userId",
        "values": [
          "red",
          "blue"
        ]
      }
    ]
  }
]'

Request Collapse all

Base URL

<your-unleash-url>

Auth

Security Scheme

apiKeybearerToken

apiKey

Parameters

projectId — pathrequired

featureName — pathrequired

Body required

[
  {
    "name": "blue_group",
    "weight": 0,
    "weightType": "variable",
    "stickiness": "custom.context.field",
    "payload": {
      "type": "json",
      "value": "{\"color\": \"red\"}"
    },
    "overrides": [
      {
        "contextName": "userId",
        "values": [
          "red",
          "blue"
        ]
      }
    ]
  }
]

ResponseClear

Click the Send API Request button above and see the response here!