> ## 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 a Flag

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

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 a Flag"
  description="Learn how to create a flag using the Confidence API."
  steps={[
{
  name: "Create a Basic Flag",
  text: "To create a flag with just a flag key: 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.",
},
{
  name: "Create a Flag with Clients",
  text: "You can associate the flag with clients when creating it to control which applications can resolve it: 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",
},
{
  name: "Retrieve a Flag",
  text: "To retrieve an existing flag and see its configuration:",
},
{
  name: "Associate with Additional Clients",
  text: "You can add more clients to a flag after creation using the addFlagClient operation: Or update the entire list of clients using the PATCH operation:",
},
]}
/>

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.
</Tip>

## 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)
</Tip>

## 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](./define-flag-schema)
2. [Create variants](./create-flag-variants)
3. [Set up flag clients](./setup-flag-clients) if you haven't already
4. [Create segments and rules](./create-segment) to control who sees what
5. [Resolve the flag](./resolve-flags) in your application