> ## Documentation Index
> Fetch the complete documentation index at: https://confidence.spotify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Flag Rules

> Learn how to create rules that assign variants to users based on segments.

export const HowToSchema = ({name, description, steps = []}) => {
  const schema = {
    "@context": "https://schema.org",
    "@type": "HowTo",
    name,
    description
  };
  if (steps.length > 0) {
    schema.step = steps.map((s, i) => ({
      "@type": "HowToStep",
      position: i + 1,
      name: typeof s === "string" ? s : s.name,
      text: typeof s === "string" ? s : s.text || s.name
    }));
  }
  return <script type="application/ld+json" dangerouslySetInnerHTML={{
    __html: JSON.stringify(schema)
  }} />;
};

<HowToSchema
  name="Create Flag Rules"
  description="Learn how to create rules that assign variants to users based on segments."
  steps={[
{
  name: "Before You Begin",
  text: "Before creating a rule, you need: 1. A flag with a defined schema and variants 2. An allocated segment that defines your target audience",
},
{
  name: "Create a Basic Rule",
  text: "Assign all users in a segment to a single variant:",
},
{
  name: "Create an A/B Test Rule",
  text: "Randomly assign users to control or treatment (50/50 split):",
},
{
  name: "Create a Multi-Variant Rule",
  text: "Assign users across three variants (40/30/30 split):",
},
{
  name: "Create a Fall-Through Rule",
  text: "Create a rule that matches but passes to the next rule:",
},
{
  name: "Create a Client Default Rule",
  text: "Assign users to their client-specified default values:",
},
{
  name: "Enable a Rule",
  text: "Newly created rules start disabled. Enable a rule to activate it:",
},
{
  name: "Update a Rule",
  text: "Change variant assignments or the segment:",
},
{
  name: "Reorder Rules",
  text: "Change rule evaluation order by updating priority (lower numbers evaluate first):",
},
{ name: "Delete a Rule", text: "Remove a rule from a flag:" },
{
  name: "Use a Custom Targeting Key",
  text: "Specify a different field for randomization (for example, device instead of user):",
},
]}
/>

Create rules to assign variants to users in a segment.

<Tip>
  See [Rules](/docs/flags/define-rules) and [Variant Assignment](/docs/flags/define-rules#general-rules) in the reference for details on how rules work, assignment types, and best practices.
</Tip>

## Before You Begin

Before creating a rule, you need:

1. A flag with a defined [schema](./define-flag-schema) and [variants](./create-flag-variants)
2. An [allocated segment](./create-segment) that defines your target audience

## Create a Basic Rule

Assign all users in a segment to a single variant:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/flags/example-flag/rules" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": "segments/all-users",
    "assignmentSpec": {
      "bucketCount": 100,
      "assignments": [
        {
          "variant": {
            "variant": "flags/example-flag/variants/enabled"
          },
          "bucketRanges": [{"lower": 0, "upper": 100}]
        }
      ]
    },
    "targetingKeySelector": "user_id"
  }'
```

## Create an A/B Test Rule

Randomly assign users to control or treatment (50/50 split):

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/flags/example-flag/rules" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": "segments/experiment-segment",
    "assignmentSpec": {
      "bucketCount": 100,
      "assignments": [
        {
          "variant": {
            "variant": "flags/example-flag/variants/control"
          },
          "bucketRanges": [{"lower": 0, "upper": 50}]
        },
        {
          "variant": {
            "variant": "flags/example-flag/variants/treatment"
          },
          "bucketRanges": [{"lower": 50, "upper": 100}]
        }
      ]
    },
    "targetingKeySelector": "user_id"
  }'
```

## Create a Multi-Variant Rule

Assign users across three variants (40/30/30 split):

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/flags/example-flag/rules" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": "segments/multivariate-test",
    "assignmentSpec": {
      "bucketCount": 100,
      "assignments": [
        {
          "variant": {"variant": "flags/example-flag/variants/option-a"},
          "bucketRanges": [{"lower": 0, "upper": 40}]
        },
        {
          "variant": {"variant": "flags/example-flag/variants/option-b"},
          "bucketRanges": [{"lower": 40, "upper": 70}]
        },
        {
          "variant": {"variant": "flags/example-flag/variants/option-c"},
          "bucketRanges": [{"lower": 70, "upper": 100}]
        }
      ]
    },
    "targetingKeySelector": "user_id"
  }'
```

## Create a Fall-Through Rule

Create a rule that matches but passes to the next rule:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/flags/example-flag/rules" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": "segments/logging-segment",
    "assignmentSpec": {
      "bucketCount": 100,
      "assignments": [
        {
          "fallthrough": {},
          "bucketRanges": [{"lower": 0, "upper": 100}]
        }
      ]
    },
    "targetingKeySelector": "user_id"
  }'
```

## Create a Client Default Rule

Assign users to their client-specified default values:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/flags/example-flag/rules" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": "segments/default-segment",
    "assignmentSpec": {
      "bucketCount": 100,
      "assignments": [
        {
          "clientDefault": {},
          "bucketRanges": [{"lower": 0, "upper": 100}]
        }
      ]
    },
    "targetingKeySelector": "user_id"
  }'
```

## Enable a Rule

Newly created rules start disabled. Enable a rule to activate it:

```bash theme={null}
curl -X PATCH "https://flags.confidence.dev/v1/flags/example-flag/rules/RULE_ID?updateMask=enabled" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'
```

## Update a Rule

Change variant assignments or the segment:

```bash theme={null}
curl -X PATCH "https://flags.confidence.dev/v1/flags/example-flag/rules/RULE_ID?updateMask=assignmentSpec" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assignmentSpec": {
      "bucketCount": 100,
      "assignments": [
        {
          "variant": {"variant": "flags/example-flag/variants/control"},
          "bucketRanges": [{"lower": 0, "upper": 30}]
        },
        {
          "variant": {"variant": "flags/example-flag/variants/treatment"},
          "bucketRanges": [{"lower": 30, "upper": 100}]
        }
      ]
    }
  }'
```

## Reorder Rules

Change rule evaluation order by updating priority (lower numbers evaluate first):

```bash theme={null}
curl -X PATCH "https://flags.confidence.dev/v1/flags/example-flag/rules/RULE_ID?updateMask=priority" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": 1
  }'
```

## Delete a Rule

Remove a rule from a flag:

```bash theme={null}
curl -X DELETE "https://flags.confidence.dev/v1/flags/example-flag/rules/RULE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Use a Custom Targeting Key

Specify a different field for randomization (for example, device instead of user):

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/flags/example-flag/rules" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": "segments/all-users",
    "assignmentSpec": {
      "bucketCount": 100,
      "assignments": [
        {
          "variant": {"variant": "flags/example-flag/variants/enabled"},
          "bucketRanges": [{"lower": 0, "upper": 100}]
        }
      ]
    },
    "targetingKeySelector": "device_id"
  }'
```

## Next Steps

After creating rules:

1. [Resolve flags](./resolve-flags) to test your rules with different evaluation contexts
2. [Apply flags](./apply-flags) to track which users see which variants
3. Monitor your experiments and adjust rules as needed