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

# Create a Flag

> Learn how to create a flag using the Confidence API.

**Create a Flag**

Learn how to create a flag using the Confidence API.

[Do this in the app →](/docs/capabilities/flags/create-flag.md)

You identify flags by a string called the flag key. This key is unique within the account. All you have to do to create a new flag is specify the flag key using the `flagId` query parameter.

## Create a Basic Flag

To create a flag with just a flag key:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/flags?flagId=example-flag" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

> [!TIP]
>
> Use a name that is understandable and memorable. For example, `new-navbar`. Avoid too long names, and don't include the configuration in the name itself. For example, don't use `new-navbar-mobile-experience` or `new-navbar-enabled` as the flag name.

## Create a Flag with Clients

You can associate the flag with clients when creating it to control which applications can resolve it:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/flags?flagId=example-flag" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clients": ["clients/my-client"]
  }'
```

> [!TIP]
>
> Not all clients should have access to all flags. Associate a flag with as few clients as possible to:
>
> * Limit the number of resolved flags in batch operations
> * Reduce network payload and costs
> * Prevent sensitive flags from being available in untrusted environments (like mobile apps)

## Retrieve a Flag

To retrieve an existing flag and see its configuration:

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

## Associate with Additional Clients

You can add more clients to a flag after creation using the `addFlagClient` operation:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/flags/example-flag:addFlagClient" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client": "clients/another-client"
  }'
```

Or update the entire list of clients using the PATCH operation:

```bash theme={null}
curl -X PATCH "https://flags.confidence.dev/v1/flags/example-flag?updateMask=clients" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clients": ["clients/my-client", "clients/another-client"]
  }'
```

## Next Steps

After creating a flag:

1. [Define the flag schema](/docs/reference/api/how-to-guides/flags/define-flag-schema.md)
2. [Create variants](/docs/reference/api/how-to-guides/flags/create-flag-variants.md)
3. [Set up flag clients](/docs/reference/api/how-to-guides/flags/setup-flag-clients.md) if you haven't already
4. [Create segments and rules](/docs/reference/api/how-to-guides/flags/create-segment.md) to control who sees what
5. [Resolve the flag](/docs/reference/api/how-to-guides/flags/resolve-flags.md) in your application