# Flag

URL: /business/nouns/flag · Id: `noun:flag`

> A Flag is a switch, evaluated per Visitor, Customer, or request, that selects which copy or behavior they get.

A Flag is a switch, evaluated per [Visitor](/business/nouns/visitor), [Customer](/business/nouns/customer), or request, that selects which copy or behavior they get.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | `string` | Yes | The name code reads. |
| `rules` | `json` | No | Who gets which value, including percentage splits. |

## Object
```json
{
  "$id": "https://api.sb/quietcopy.com/flags/flag_1",
  "$type": "Flag",
  "key": "new-checkout",
  "rules": {}
}
```

## Relationships
- <a id="rel-assigns"></a>A Flag **assigns** many [Experiments](/business/nouns/experiment): Flags split units across an [Experiment](/business/nouns/experiment)’s [Variants](/business/nouns/variant) and log each assignment with its propensity. `assigns`, inverse [`assignsWith`](/business/nouns/experiment#rel-assigns-with).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Flag.evaluate](/business/nouns/flag/evaluate) | Evaluate returns the Variant a Flag assigns one unit, the same one every time, and records the Exposure with every option and its propensity. | [Agent](/business/nouns/agent) | [`Flag.evaluated`](/business/events/Flag.evaluated) | None. |
| <a id="create"></a>[Flag.create](/business/nouns/flag/create) | Creates a Flag. Inherited from [Noun](/business/nouns/noun). | None. | `Flag.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Flag.get](/business/nouns/flag/get) | Returns one Flag by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Flag.list](/business/nouns/flag/list) | Returns Flags, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Flag.update](/business/nouns/flag/update) | Changes the given properties of a Flag. Inherited from [Noun](/business/nouns/noun). | None. | `Flag.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Flag.delete](/business/nouns/flag/delete) | Deletes a Flag; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Flag.deleted` | One-way: `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Flag.create` | Yes | Yes | Yes | No |
| `Flag.get` | Yes | Yes | Yes | Yes |
| `Flag.list` | Yes | Yes | Yes | Yes |
| `Flag.update` | Yes | Yes | Yes | No |
| `Flag.delete` | Yes | Yes | Yes | No |
| `Flag.evaluate` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Evaluate the latest flag.
```

**API**

```bash
curl -X POST https://api.sb/routewise.dev/flags/flag_1/evaluate \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"unit":"Example unit"}'
```

```json
{
  "api": "https://api.sb/routewise.dev",
  "variant": {
    "$id": "https://api.sb/routewise.dev/variants/variant_1",
    "$type": "Variant",
    "key": "Example key",
    "value": {}
  },
  "exposure": {
    "$id": "https://api.sb/routewise.dev/exposures/exposure_1",
    "$type": "Exposure",
    "unit": "Example unit",
    "options": {},
    "propensity": 1,
    "at": "2026-10-22T12:00:00Z"
  },
  "action": {
    "$id": "https://api.sb/routewise.dev/actions/action_1",
    "operation": "Flag.evaluate",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/routewise.dev/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const { variant, exposure } = await $.Flag.evaluate({ flag: 'flag_1', unit: 'Example unit' })
```

**CLI**

```bash
npx startup-builder do Flag.evaluate --json '{"flag":"flag_1","unit":"Example unit"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Flag.evaluate({ flag: 'flag_1', unit: 'Example unit' })"
  }
}
```

## Example
The Flag `pricing-page-v2` shows the new pricing [Page](/business/nouns/page) to 50% of Visitors and the prior Page to the rest.