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

# Create and Manage Global Feature Flags

> Global flags apply to your entire project. Set a flag to on or off and control gradual rollout with a percentage to limit exposure to a fraction of traffic.

Global flags are the simplest way to ship a feature behind a toggle. Each flag belongs to a project, has a human-readable name and a machine-readable key, and carries two runtime values: whether the flag is enabled and what percentage of checks should return active. You check them from your application via a REST endpoint or in the dashboard to verify state at a glance.

## Flag fields

| Field          | Description                                                                                                                               |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**       | Human-readable label shown in the dashboard (e.g. `New Dashboard`).                                                                       |
| **Key**        | Machine-readable identifier used in API calls (e.g. `new-dashboard`). Must be unique within the project.                                  |
| **Enabled**    | Whether the flag is on (`true`) or off (`false`). When disabled, the flag is inactive regardless of percentage.                           |
| **Percentage** | A number from `0` to `100` representing what fraction of traffic should be considered active when the flag is enabled. Defaults to `100`. |

<Note>
  Keys should be lowercase and kebab-case: `dark-mode`, `new-checkout`, `beta-export`. Keys are unique per project — the API enforces this constraint.
</Note>

## Creating a flag

<Steps>
  <Step title="Open Feature Flags">
    Navigate to your project and select **Feature Flags** from the sidebar. Make sure the **Flags** tab is active.
  </Step>

  <Step title="Open the creation dialog">
    Click **New Flag** in the top-right corner of the flags table.
  </Step>

  <Step title="Fill in name and key">
    Enter a **Name** (e.g. `New Dashboard`) and a **Key** (e.g. `new-dashboard`). The key is what your code references at runtime.
  </Step>

  <Step title="Set enabled status and rollout percentage">
    Toggle **Enabled** on or off. Set the **Percentage** to control what fraction of traffic is exposed — `100` means all traffic, `0` means none.
  </Step>

  <Step title="Create the flag">
    Click **Create**. The flag appears immediately in the flags table.
  </Step>
</Steps>

## Checking a flag via API

You can check a global flag from your application with either an API key or a dashboard session. The endpoint resolves the flag for an environment and returns its `enabled` state, configured `rollout` percentage, `source`, and the resolved `environment`.

```bash theme={null}
GET /api/projects/:projectId/flags/check/:flagKey
Authorization: Bearer <api-key>
```

**Example response:**

```json theme={null}
{
  "enabled": true,
  "rollout": 75,
  "source": "global",
  "environment": { "id": "1Rkx7yLBcnX2tGZ4VqHfJp9wYsT", "name": "Production", "key": "production" }
}
```

`enabled` already reflects the rollout roll Swisstools performs for this call, so you can branch on it directly. `source` is `"cache"` when served from the 60-second Redis cache or `"global"` when freshly computed. Pass `?env=` (an environment `key` or `name`) to target a specific environment; otherwise the project's default is used.

## Editing and deleting flags

Find the flag in the table on the **Flags** tab. Each row has two action icons:

* **Pencil icon** — opens the edit dialog. You can update the name, enabled state, and percentage. The key is not editable after creation.
* **Trash icon** — opens a confirmation dialog. Deleting a flag is permanent and removes it from all API responses immediately.