---
title: create-a-flag
product: vercel
url: /docs/rest-api/feature-flags/create-a-flag
type: reference
prerequisites:
  []
related:
  - /docs/rest-api
summary: Learn about create-a-flag on Vercel.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# Create a flag

```http
PUT /v1/projects/{projectIdOrName}/feature-flags/flags
```

Create a new feature flag for a project. The flag must have a unique slug within the project and specify its kind (boolean, string, number, or json).

## Authentication

**bearerToken**: HTTP bearer

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `projectIdOrName` | string | Yes | The project id or name |


## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `teamId` | string | No | The Team identifier to perform the request on behalf of. |
| `slug` | string | No | The Team slug to perform the request on behalf of. |


## Request body

Required: No

Content-Type: `application/json`

```json
{
  "type": "object",
  "required": [
    "slug",
    "kind",
    "environments"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "description": "A unique (per project) key for the flag, composed of letters, numbers, dashes, and underscores",
      "pattern": "^[a-zA-Z0-9_-]{1,512}$"
    },
    "kind": {
      "description": "The kind of flag",
      "enum": [
        "boolean",
        "string",
        "number",
        "json"
      ]
    },
    "variants": {
      "type": "array",
      "description": "The variants of the flag",
      "items": {
        "type": "object",
        "required": [
          "id",
          "value"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The id of the variant"
          },
          "label": {
            "type": "string",
            "description": "A label for the variant"
          },
          "description": {
            "type": "string",
            "description": "A description of the variant"
          },
          "value": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              },
              {
                "type": "object"
              },
              {
                "type": "array",
                "items": {}
              },
              {
                "type": "string"
              }
            ]
          }
        }
      }
    },
    "environments": {
      "type": "object",
      "description": "The configuration for the flag in different environments",
      "additionalProperties": {
        "type": "object",
        "required": [
          "active",
          "pausedOutcome",
          "rules",
          "fallthrough"
        ],
        "properties": {
          "active": {
            "type": "boolean"
          },
          "reuse": {
            "type": "object",
            "description": "Allows linking this environment to another environment so this flag will be evaluated with the other flag's configuration",
            "required": [
              "active",
              "environment"
            ],
            "properties": {
              "active": {
                "type": "boolean",
                "description": "Whether the reuse is active or not"
              },
              "environment": {
                "type": "string",
                "description": "The environment to link to"
              }
            }
          },
          "targets": {
            "type": "object",
            "description": "Allows assigning targets to variants while bypassing the flag's rules",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": {
                "type": "object",
                "additionalProperties": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "value"
                    ],
                    "properties": {
                      "note": {
                        "type": "string"
                      },
                      "value": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "pausedOutcome": {
            "type": "object",
            "required": [
              "type",
              "variantId"
            ],
            "properties": {
              "type": {},
              "variantId": {
                "type": "string"
              }
            }
          },
          "rules": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "conditions",
                "outcome"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "conditions": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "lhs",
                      "cmp"
                    ],
                    "properties": {
                      "lhs": {
                        "anyOf": [
                          {
                            "type": "object",
                            "required": [
                              "type"
                            ],
                            "properties": {
                              "type": {}
                            }
                          },
                          {
                            "type": "object",
                            "required": [
                              "type",
                              "kind",
                              "attribute"
                            ],
                            "properties": {
                              "type": {},
                              "kind": {
                                "type": "string"
                              },
                              "attribute": {
                                "type": "string"
                              }
                            }
                          }
                        ]
                      },
                      "cmp": {
                        "type": "string",
                        "enum": [
                          "eq",
                          "!eq",
                          "oneOf",
                          "!oneOf",
                          "containsAllOf",
                          "containsAnyOf",
                          "containsNoneOf",
                          "startsWith",
                          "!startsWith",
                          "endsWith",
                          "!endsWith",
                          "contains",
                          "!contains",
                          "ex",
                          "!ex",
                          "gt",
                          "gte",
                          "lt",
                          "lte",
                          "regex",
                          "!regex",
                          "before",
                          "after"
                        ]
                      },
                      "rhs": {
                        "anyOf": [
                          {
                            "type": "object",
                            "required": [
                              "type",
                              "items"
                            ],
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "list/inline",
                                  "list"
                                ]
                              },
                              "items": {
                                "type": "array",
                                "items": {
                                  "anyOf": [
                                    {
                                      "type": "object",
                                      "required": [
                                        "value"
                                      ],
                                      "properties": {
                                        "label": {
                                          "type": "string"
                                        },
                                        "note": {
                                          "type": "string"
                                        },
                                        "value": {
                                          "type": "number"
                                        }
                                      }
                                    },
                                    {
                                      "type": "object",
                                      "required": [
                                        "value"
                                      ],
                                      "properties": {
                                        "label": {
                                          "type": "string"
                                        },
                                        "note": {
                                          "type": "string"
                                        },
                                        "value": {
                                          "type": "string"
                                        }
                                      }
                                    }
                                  ]
                                }
                              }
                            }
                          },
                          {
                            "type": "object",
                            "required": [
                              "type",
                              "pattern",
                              "flags"
                            ],
                            "properties": {
                              "type": {},
                              "pattern": {
                                "type": "string"
                              },
                              "flags": {
                                "type": "string"
                              }
                            }
                          },
                          {
                            "type": "string"
                          },
                          {
                            "type": "number"
                          },
                          {
                            "type": "boolean"
                          }
                        ]
                      },
                      "cmpOptions": {
                        "type": "object",
                        "properties": {
                          "ignoreCase": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  }
                },
                "outcome": {
                  "anyOf": [
                    {
                      "type": "object",
                      "required": [
                        "type",
                        "variantId"
                      ],
                      "properties": {
                        "type": {},
                        "variantId": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "required": [
                        "type",
                        "base",
                        "weights",
                        "defaultVariantId"
                      ],
                      "properties": {
                        "type": {},
                        "base": {
                          "type": "object",
                          "required": [
                            "type",
                            "kind",
                            "attribute"
                          ],
                          "properties": {
                            "type": {},
                            "kind": {
                              "type": "string"
                            },
                            "attribute": {
                              "type": "string"
                            }
                          }
                        },
                        "weights": {
                          "type": "object",
                          "description": "The distribution for each variant",
                          "additionalProperties": {
                            "type": "number"
                          }
                        },
                        "defaultVariantId": {
                          "type": "string",
                          "description": "This variant will be used when the base attribute does not exist"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "fallthrough": {
            "anyOf": [
              {
                "type": "object",
                "required": [
                  "type",
                  "variantId"
                ],
                "properties": {
                  "type": {},
                  "variantId": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "type",
                  "base",
                  "weights",
                  "defaultVariantId"
                ],
                "properties": {
                  "type": {},
                  "base": {
                    "type": "object",
                    "required": [
                      "type",
                      "kind",
                      "attribute"
                    ],
                    "properties": {
                      "type": {},
                      "kind": {
                        "type": "string"
                      },
                      "attribute": {
                        "type": "string"
                      }
                    }
                  },
                  "weights": {
                    "type": "object",
                    "description": "The distribution for each variant",
                    "additionalProperties": {
                      "type": "number"
                    }
                  },
                  "defaultVariantId": {
                    "type": "string",
                    "description": "This variant will be used when the base attribute does not exist"
                  }
                }
              }
            ]
          },
          "revision": {
            "type": "number",
            "description": "The revision of the environment config"
          }
        }
      }
    },
    "seed": {
      "type": "number",
      "description": "A random seed to prevent split points in different flags from having the same targets",
      "minimum": 0,
      "maximum": 100000
    },
    "description": {
      "type": "string",
      "description": "A description of the flag"
    },
    "state": {
      "type": "string",
      "enum": [
        "active",
        "archived"
      ]
    }
  }
}
```

## Responses

### 201: No description

Content-Type: `application/json`

```json
{
  "type": "object",
  "required": [
    "createdAt",
    "createdBy",
    "environments",
    "id",
    "kind",
    "ownerId",
    "projectId",
    "revision",
    "seed",
    "slug",
    "state",
    "typeName",
    "updatedAt",
    "variants"
  ],
  "properties": {
    "description": {
      "type": "string"
    },
    "experiment": {
      "type": "object",
      "required": [
        "allocationUnit",
        "primaryMetrics",
        "status"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "numVariants": {
          "type": "number"
        },
        "surfaceArea": {
          "type": "string"
        },
        "stickyRequirement": {
          "type": "boolean",
          "enum": [
            false,
            true
          ]
        },
        "layer": {
          "type": "string"
        },
        "guardrailMetrics": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "directionality",
              "metricType",
              "metricUnit",
              "name"
            ],
            "properties": {
              "description": {
                "type": "string"
              },
              "metricFormula": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "metricType": {
                "type": "string",
                "enum": [
                  "percentage",
                  "currency",
                  "count"
                ]
              },
              "metricUnit": {
                "type": "string",
                "enum": [
                  "user",
                  "session",
                  "visitor"
                ]
              },
              "directionality": {
                "type": "string",
                "enum": [
                  "increaseIsGood",
                  "decreaseIsGood"
                ]
              }
            }
          }
        },
        "hypothesis": {
          "type": "string"
        },
        "device": {
          "type": "string",
          "enum": [
            "android",
            "ios",
            "desktop",
            "mweb"
          ]
        },
        "controlVariantId": {
          "type": "string"
        },
        "startedAt": {
          "type": "number"
        },
        "endedAt": {
          "type": "number"
        },
        "allocationUnit": {
          "type": "string",
          "enum": [
            "cookieId",
            "visitorId",
            "userId"
          ]
        },
        "primaryMetrics": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "directionality",
              "metricType",
              "metricUnit",
              "name"
            ],
            "properties": {
              "description": {
                "type": "string"
              },
              "metricFormula": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "metricType": {
                "type": "string",
                "enum": [
                  "percentage",
                  "currency",
                  "count"
                ]
              },
              "metricUnit": {
                "type": "string",
                "enum": [
                  "user",
                  "session",
                  "visitor"
                ]
              },
              "directionality": {
                "type": "string",
                "enum": [
                  "increaseIsGood",
                  "decreaseIsGood"
                ]
              }
            }
          }
        },
        "status": {
          "type": "string",
          "enum": [
            "draft",
            "running",
            "paused",
            "closed"
          ]
        }
      }
    },
    "variants": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "id": {
      "type": "string"
    },
    "environments": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "required": [
          "active",
          "fallthrough",
          "pausedOutcome",
          "rules"
        ],
        "properties": {
          "reuse": {
            "type": "object",
            "required": [
              "active",
              "environment"
            ],
            "properties": {
              "active": {
                "type": "boolean",
                "enum": [
                  false,
                  true
                ]
              },
              "environment": {
                "type": "string"
              }
            }
          },
          "targets": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": {
                "type": "object",
                "additionalProperties": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "value"
                    ],
                    "properties": {
                      "note": {
                        "type": "string"
                      },
                      "value": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "revision": {
            "type": "number"
          },
          "pausedOutcome": {
            "type": "object",
            "required": [
              "type",
              "variantId"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "variant"
                ]
              },
              "variantId": {
                "type": "string"
              }
            }
          },
          "fallthrough": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "type",
                  "variantId"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "variant"
                    ]
                  },
                  "variantId": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "base",
                  "defaultVariantId",
                  "type",
                  "weights"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "split"
                    ]
                  },
                  "base": {
                    "type": "object",
                    "required": [
                      "attribute",
                      "kind",
                      "type"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "entity"
                        ]
                      },
                      "kind": {
                        "type": "string"
                      },
                      "attribute": {
                        "type": "string"
                      }
                    }
                  },
                  "weights": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "number"
                    }
                  },
                  "defaultVariantId": {
                    "type": "string"
                  }
                }
              }
            ]
          },
          "active": {
            "type": "boolean",
            "enum": [
              false,
              true
            ]
          },
          "rules": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "conditions",
                "id",
                "outcome"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "outcome": {
                  "oneOf": [
                    {
                      "type": "object",
                      "required": [
                        "type",
                        "variantId"
                      ],
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "variant"
                          ]
                        },
                        "variantId": {
                          "type": "string"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "required": [
                        "base",
                        "defaultVariantId",
                        "type",
                        "weights"
                      ],
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "split"
                          ]
                        },
                        "base": {
                          "type": "object",
                          "required": [
                            "attribute",
                            "kind",
                            "type"
                          ],
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": [
                                "entity"
                              ]
                            },
                            "kind": {
                              "type": "string"
                            },
                            "attribute": {
                              "type": "string"
                            }
                          }
                        },
                        "weights": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "number"
                          }
                        },
                        "defaultVariantId": {
                          "type": "string"
                        }
                      }
                    }
                  ]
                },
                "conditions": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "cmp",
                      "lhs"
                    ],
                    "properties": {
                      "rhs": {
                        "oneOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "number"
                          },
                          {
                            "type": "object",
                            "required": [
                              "items",
                              "type"
                            ],
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "list/inline",
                                  "list"
                                ]
                              },
                              "items": {
                                "type": "array",
                                "items": {
                                  "oneOf": [
                                    {
                                      "type": "object",
                                      "required": [
                                        "value"
                                      ],
                                      "properties": {
                                        "label": {
                                          "type": "string"
                                        },
                                        "note": {
                                          "type": "string"
                                        },
                                        "value": {
                                          "type": "number"
                                        }
                                      }
                                    },
                                    {
                                      "type": "object",
                                      "required": [
                                        "value"
                                      ],
                                      "properties": {
                                        "label": {
                                          "type": "string"
                                        },
                                        "note": {
                                          "type": "string"
                                        },
                                        "value": {
                                          "type": "string"
                                        }
                                      }
                                    }
                                  ]
                                }
                              }
                            }
                          },
                          {
                            "type": "object",
                            "required": [
                              "flags",
                              "pattern",
                              "type"
                            ],
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "regex"
                                ]
                              },
                              "pattern": {
                                "type": "string"
                              },
                              "flags": {
                                "type": "string"
                              }
                            }
                          },
                          {
                            "type": "boolean",
                            "enum": [
                              false,
                              true
                            ]
                          }
                        ]
                      },
                      "cmpOptions": {
                        "type": "object",
                        "properties": {
                          "ignoreCase": {
                            "type": "boolean",
                            "enum": [
                              false,
                              true
                            ]
                          }
                        }
                      },
                      "lhs": {
                        "oneOf": [
                          {
                            "type": "object",
                            "required": [
                              "type"
                            ],
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "segment"
                                ]
                              }
                            }
                          },
                          {
                            "type": "object",
                            "required": [
                              "attribute",
                              "kind",
                              "type"
                            ],
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": [
                                  "entity"
                                ]
                              },
                              "kind": {
                                "type": "string"
                              },
                              "attribute": {
                                "type": "string"
                              }
                            }
                          }
                        ]
                      },
                      "cmp": {
                        "type": "string",
                        "enum": [
                          "eq",
                          "!eq",
                          "oneOf",
                          "!oneOf",
                          "containsAllOf",
                          "containsAnyOf",
                          "containsNoneOf",
                          "startsWith",
                          "!startsWith",
                          "endsWith",
                          "!endsWith",
                          "contains",
                          "!contains",
                          "ex",
                          "!ex",
                          "gt",
                          "gte",
                          "lt",
                          "lte",
                          "regex",
                          "!regex",
                          "before",
                          "after"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "kind": {
      "type": "string",
      "enum": [
        "string",
        "number",
        "boolean",
        "json"
      ]
    },
    "revision": {
      "type": "number"
    },
    "seed": {
      "type": "number"
    },
    "state": {
      "type": "string",
      "enum": [
        "active",
        "archived"
      ]
    },
    "slug": {
      "type": "string"
    },
    "createdAt": {
      "type": "number"
    },
    "updatedAt": {
      "type": "number"
    },
    "createdBy": {
      "type": "string"
    },
    "ownerId": {
      "type": "string"
    },
    "projectId": {
      "type": "string"
    },
    "typeName": {
      "type": "string",
      "enum": [
        "flag"
      ]
    }
  }
}
```

### 400: One of the provided values in the request body is invalid.
One of the provided values in the request query is invalid.

### 401: The request is not authorized.

### 402: The account was soft-blocked for an unhandled reason.
The account is missing a payment so payment method must be updated

### 403: You do not have permission to access this resource.

### 404: No description

### 409: No description

### 412: No description

---

## Related

- [feature-flags endpoints](/docs/rest-api#feature-flags)

- [REST API overview](/docs/rest-api)

- [OpenAPI spec](https://openapi.vercel.sh/) (machine-readable, all endpoints)

---

[View full sitemap](/docs/sitemap)